delta-barth-cs/dopt.DeltaBarth/Plugin.cs

using Python.Runtime;
using System.ComponentModel;
using System.Text.Json;

namespace dopt.DeltaBarth
{
    /// <summary>
    /// Spiegelung der internen Fehlertypen innerhalb der Python-Bibliothek
    /// </summary>
    public enum StatusCodes
    {
        /// <summary>
        /// erfolgreiche, fehlerfreie Durchführung der Routine
        /// </summary>
        [Description("Keine Fehler aufgetreten")]
        Erfolg = 0,
        /// <summary>
        /// Bei der API-Abfrage wurde der Timeout getriggert.
        /// </summary>
        [Description("Bei der Verbindung zum API-Server kam es zum Timeout")]
        VerbindungTimeout = 1,
        /// <summary>
        /// Bei der API-Abfrage ist ein unerwarteter Fehler aufgetreten, der unmittelbar die HTTP-Anfrage betrifft.
        /// </summary>
        [Description("Bei der Verbindung zum API-Server ist ein Fehler aufgetreten")]
        VerbindungFehler = 2,
        /// <summary>
        /// Der ausgewählte Datensatz enthält nicht genügend Datenpunkte.
        /// </summary>
        [Description("Der bereitgestellte Datensatz enthält in Summe zu wenige Einzeleinträge")]
        DatensatzZuWenigeDatenpunkte = 3,
        /// <summary>
        /// Der ausgewählte Datensatz enthält nach Aggregation pro Monat nicht genügend Datenpunkte.
        /// </summary>
        [Description("Der bereitgestellte Datensatz enthält nach Aggregation zu Monaten zu wenig Einträge")]
        DatensatzZuWenigeMonatsdatenpunkte = 4,
        /// <summary>
        /// Die Prognosequalität des Modells ist nicht zufriedenstellend. Eine verlässliche Prognose ist nicht möglich.
        /// </summary>
        [Description("Die Prognosequalität des Modells erfüllt nicht die Mindestanforderungen")]
        KeineVerlaesslichePrognose = 5,
        /// <summary>
        /// Es ist intern ein Fehler aufgetreten aufgetreten
        /// </summary>
        [Description("Interne Fehler, die während der Routine aufgetreten sind")]
        InternerFehler = 100,
        /// <summary>
        /// Es ist ein Fehler beim Schreiben der programminternen Datenbank aufgetreten.
        /// </summary>
        [Description("Interne Fehler, die während der Datenbankinteraktion aufgetreten sind")]
        InternerDbFehler = 150,
        /// <summary>
        /// Es ist ein Fehler auf dem API-Server aufgetreten. 
        /// Das dazugehörige Status-Objekt sollte diesen Fehler zur Verfügung stellen können.
        /// <see cref="DataObjects.Status"/>
        /// <see cref="DataObjects.ApiServerError"/>
        /// </summary>
        [Description("Vom API-Server wurde eine Fehlermeldung zurückgegeben")]
        ApiServerFehler = 400,
    }
    /// <summary>
    /// Eine Exception, die genutzt wird, um anzuzeigen, dass beim Parsen der Python-Objekte
    /// ein Fehler aufgetreten ist.
    /// </summary>
    public class PythonParsingException : Exception
    {
        /// <summary>
        /// Konstruktor ohne Inhalt
        /// </summary>
        public PythonParsingException() { }
        /// <summary>
        /// Konstruktor mit Nachricht
        /// </summary>
        /// <param name="message"></param>
        public PythonParsingException(string message) : base(message) { }
    }
    /// <summary>
    /// Plugin-Klasse, mit der die Interaktion der zugrundeliegenden Python-Runtime erfolgt
    /// </summary>
    public class Plugin : SharpPython.BasePlugin
    {
        /// <summary>
        /// Python-interne Zustandsverwaltung
        /// </summary>
        protected dynamic pyModManagement;
        /// <summary>
        /// Python-interne Routinen und Pipelines
        /// </summary>
        protected dynamic pyModPipeline;
        /// <summary>
        /// Konstruktor der Plugin-Klasse.
        /// Kann mit beliebigem Pfad zu einer Python-Runtime initialisiert werden.
        /// </summary>
        /// <param name="runtimePath">Der Pfad zur Python-Runtime. Dieser muss zu dem Ordner zeigen, 
        /// in welchem die Runtime in Form eines Ordners mit dem Namen "python" abliegt.</param>
        public Plugin(string runtimePath) : base(SharpPython.PyOptimLevels.O, threaded: true, runtimePath: runtimePath, verbose: false) 
        {
            base.Initialise();
            using (Py.GIL())
            {
                pyModManagement = Py.Import("delta_barth.management");
                pyModPipeline = Py.Import("delta_barth.pipelines");
            }
        }
        /// <summary>
        /// Initialisiert das Plugin mit allen relevanten Paramtern für die weitere Nutzung.
        /// Diese Methode sollte nur einmal je Instanz genutzt werden.
        /// </summary>
        /// <param name="datenPfad">Pfad zu einem Ordner, in dem Programmdaten ohne Bedenken dauerhaft abgelegt werden können.</param>
        /// <param name="basisApiUrl">Basis-URL zum Zugriff auf die API. Dies muss eine vollständige URL sein inkl. der Route "/api".</param>
        /// <param name="nutzername">Nutzername für die Datenbankanmeldung.</param>
        /// <param name="passwort">Passwort für die Datenbankanmeldung.</param>
        /// <param name="datenbank">Name der Datenbank, bei der die Anmeldung erfolgen soll.</param>
        /// <param name="mandant">Mandant für die Datenbankanmeldung.</param>
        public void Startup(string datenPfad, string basisApiUrl, string nutzername, string passwort, string datenbank, string mandant)
        {
            AssertNotDisposed();
            Setup(datenPfad, basisApiUrl);
            SetzeNutzerdaten(nutzername, passwort, datenbank, mandant);
        }
        /// <summary>
        /// Diese Methode erlaubt es, die relevanten Nutzerdaten zur Laufzeit des Plugins zu ändern.
        /// Dies beinhaltet: Nutzername, Passwort, Datenbankname, Mandant
        /// </summary>
        /// <param name="nutzername">Nutzername für die Datenbankanmeldung.</param>
        /// <param name="passwort">Passwort für die Datenbankanmeldung.</param>
        /// <param name="datenbank">Name der Datenbank, bei der die Anmeldung erfolgen soll.</param>
        /// <param name="mandant">Mandant für die Datenbankanmeldung.</param>
        public void SetzeNutzerdaten(string nutzername, string passwort, string datenbank, string mandant)
        {
            AssertNotDisposed();
            using (Py.GIL()) {
                pyModManagement.set_credentials(nutzername, passwort, datenbank, mandant);
            }
        }
        /// <summary>
        /// Ausführung der Umsatzprognose-Pipeline mit Dummy-Daten.
        /// Es werden keine API-Abrufe durchgeführt und somit auch keine Live-Daten genutzt.
        /// </summary>
        /// <param name="firmaId">optional: Firmen-ID, für die die Pipeline ausgeführt werden soll. 
        /// Wird der Parameter nicht zur Verfügung gestellt, werden alle Firmen bzw. Kunden abgerufen</param>
        /// <param name="analyseBeginn">optional: Start-Datum, ab dem die Daten für die Erstellung des Prognosemodells genutzt werden.
        /// Daten, die weiter in der Vergangenheit liegen, werden nicht berücksichtigt. 
        /// Wird der Parameter nicht zur Verfügung gestellt, wird die gesamte Historie genutzt.</param>
        /// <returns cref="DataObjects.UmsatzPrognoseAusgabe">Umsatzprognose inkl. Status-Objekt zur Nachvollziehbarkeit etwaig aufgetretener Fehler.</returns>
        /// <exception cref="PythonParsingException"></exception>
        public DataObjects.UmsatzPrognoseAusgabe UmsatzprognoseDummy(int? firmaId, DateTime? analyseBeginn)
        {
            AssertNotDisposed();
            string pyJson;
            using (Py.GIL())
            {
                pyJson = pyModPipeline.pipeline_sales_forecast_dummy(firmaId, analyseBeginn);
            }
            var parsed = JsonSerializer.Deserialize<DataObjects.UmsatzPrognoseAusgabe>(pyJson) ?? throw new PythonParsingException("Could not correctly parse object from Python");
            return parsed;
        }
        /// <summary>
        /// Ausführung der Umsatzprognose-Pipeline mit Live-Daten.
        /// Es werden API-Abrufe durchgeführt und somit auch Live-Daten genutzt. 
        /// Hierfür muss sichergestellt sein, dass der API-Server erreichbar und abrufbereit ist.
        /// </summary>
        /// <param name="firmaIds">optional: Liste von Firmen-IDs, für die die Pipeline ausgeführt werden soll. 
        /// Wird der Parameter nicht zur Verfügung gestellt, werden alle Firmen bzw. Kunden abgerufen</param>
        /// <param name="analyseBeginn">optional: Start-Datum, ab dem die Daten für die Erstellung des Prognosemodells genutzt werden.
        /// Daten, die weiter in der Vergangenheit liegen, werden nicht berücksichtigt. 
        /// Wird der Parameter nicht zur Verfügung gestellt, wird die gesamte Historie genutzt.</param>
        /// <returns cref="DataObjects.UmsatzPrognoseAusgabe">Umsatzprognose inkl. Status-Objekt zur Nachvollziehbarkeit etwaig aufgetretener Fehler.</returns>
        /// <exception cref="PythonParsingException"></exception>
        public DataObjects.UmsatzPrognoseAusgabe Umsatzprognose(List<int>? firmaIds, DateTime? analyseBeginn)
        {
            AssertNotDisposed();
            string pyJson;
            using (Py.GIL())
            {
                pyJson = pyModPipeline.pipeline_sales_forecast(firmaIds, analyseBeginn);
            }
            var parsed = JsonSerializer.Deserialize<DataObjects.UmsatzPrognoseAusgabe>(pyJson) ?? throw new PythonParsingException("Could not correctly parse object from Python");
            return parsed;
        }
        /// <summary>
        /// Setup der Python-internen Umgebung
        /// </summary>
        /// <param name="datenPfad">Pfad zu einem Ordner, in dem Programmdaten ohne Bedenken dauerhaft abgelegt werden können.</param>
        /// <param name="basisApiUrl">Basis-URL zum Zugriff auf die API. Dies muss eine vollständige URL sein inkl. der Route "/api".</param>
        protected void Setup(string datenPfad, string basisApiUrl)
        {
            AssertNotDisposed();
            using (Py.GIL())
            {
                pyModManagement.setup(datenPfad, basisApiUrl);
            }
        }
        /// <summary>
        /// Hole die konfigurierte API-Basis-URL aus der Python-Umgebung
        /// </summary>
        /// <returns>konfigurierte Basis-URL</returns>
        protected string GetBaseApiUrl()
        {
            AssertNotDisposed();
            string pyJson;
            using (Py.GIL())
            {
                pyJson = (string)pyModManagement.get_base_url();
            }
            return pyJson;
        }
        /// <summary>
        /// Hole den konfigurierten Datenpfad zur Dateiverwaltung aus der Python-Umgebung
        /// </summary>
        /// <returns>konfigurierten Datenpfad</returns>
        protected string GetDataPath()
        {
            AssertNotDisposed();
            string pyJson;
            using (Py.GIL())
            {
                pyJson = (string)pyModManagement.get_data_path();
            }
            return pyJson;
        }
        /// <summary>
        /// Hole die konfigurierten Nutzerdaten zur API-Interaktion aus der Python-Umgebung
        /// </summary>
        /// <returns cref="DataObjects.Credentials">konfigurierte Nutzerdaten</returns>
        /// <exception cref="PythonParsingException"></exception>
        protected DataObjects.Credentials GetCredentials()
        {
            AssertNotDisposed();
            string pyJson;
            using (Py.GIL())
            {
                pyJson = (string)pyModManagement.get_credentials();
            }

            DataObjects.Credentials? parsed = JsonSerializer.Deserialize<DataObjects.Credentials>(pyJson);
            return parsed ?? throw new PythonParsingException("Could not correctly parse object from Python");
        }
    }
}