Initial commit

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/builddocs.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+
+sphinx-apidoc -T -f ../src/PyAPplus64 -o source/generated
+sphinx-build -a -E -b html source build/html

docs/builddocspdf.sh

@@ -0,0 +1,14 @@
+#!/bin/sh
+##
+## Copyright (c) 2023 Thomas Tuerk (kontakt@thomas-tuerk.de)
+##
+## This file is part of PyAPplus64.
+##
+
+sphinx-apidoc -T -f ../src/PyAPplus64 -o source/generated
+sphinx-build -a -E -b latex source build/pdf
+cd build/pdf
+pdflatex pyapplus64.tex
+pdflatex pyapplus64.tex
+
+

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/abhaengigkeiten.rst

@@ -0,0 +1,40 @@
+Abhängigkeiten
+==============
+
+pyodbc
+------
+Für die Datenbankverbindung wird ``pyodbc`` (``python -m pip install pyodbc``) verwendet. 
+Der passende ODBC Treiber, MS SQL Server 2012 Native Client, wird zusätzlich benötigt. 
+Dieser kann von Microsoft bezogen werden.
+
+
+zeep
+----
+Die Soap-Library ``zeep`` wird benutzt (``python -m pip install zeep``).
+
+
+PyYaml
+------
+
+Die Library ``pyyaml`` wird für Config-Dateien benutzt (``python -m pip install pyyaml``).
+
+
+Sphinx 
+------
+Diese Dokumentation ist mit Sphinx geschrieben. 
+``python -m pip install sphinx``. Dokumentation ist im Unterverzeichnis 
+`docs` zu finden. Sie kann mittels ``make.bat html`` erzeugt werden, 
+dies ruft intern ``sphinx-build -M html source build`` auf. Die Dokumentation 
+der Python-API sollte evtl. vorher
+mittels ``sphinx-apidoc -T -f ../src/PyAPplus64 -o source/generated`` erzeugt
+oder aktualisiert werden. Evtl. können 2 Aufrufe von ``make.bat html`` sinnvoll
+sein, falls sich die Struktur der Dokumentation ändert.
+Diese Aufrufe werden von ``builddocs.sh`` automatisiert.
+
+Die erzeugte Doku findet sich im Verzeichnis ``build/html``.
+
+
+Pandas / SqlAlchemy / xlsxwriter
+--------------------------------
+Sollen Excel-Dateien mit Pandas erzeugt, werden, so muss Pandas, SqlAlchemy und xlsxwriter installiert sein 
+(`python -m pip install pandas sqlalchemy xlsxwriter`).

docs/source/anwendungen.rst

@@ -0,0 +1,92 @@
+typische Anwendungsfälle
+========================
+
+einfache Admin-Aufgaben
+-----------------------
+
+Selten auftretende Admin-Aufgaben lassen sich gut mittels Python-Scripten automatisieren.
+Es ist sehr einfach möglich, auf die DB, aber auch auf SOAP-Schnittstelle zuzugreifen.
+Ich habe dies vor allem für Wartungsarbeiten an Anpassungstabellen, die für eigene Erweiterungen
+entwickelt wurden, genutzt. 
+
+Als triviales Beispiel sucht folgender Code alle `DOCUMENTS` Einträge in
+Artikeln (angezeigt als `Bild` in `ArtikelRec.aspx`), für die Datei, auf die
+verwiesen wird, nicht im Dateisystem existiert. Diese fehlenden Dateien werden
+ausgegeben und das Feld `DOCUMENTS` gelöscht. Das Löschen erfolgt dabei über 
+`useXML`, so dass die Felder `UPDDATE` und `UPDUSER` korrekt gesetzt werden.
+
+.. literalinclude:: ../../examples/check_dokumente.py
+   :language: python
+   :linenos:
+
+Man kann alle Python Bibliotheken nutzen. Als Erweiterung wäre es in obigem Script 
+zum Beispiel einfach möglich, alle BMP-Bilder zu suchen, nach PNG zu konvertieren 
+und den DB-Eintrag anzupassen.
+
+
+Ad-hoc Reports
+--------------
+
+APplus erlaubt es mittels Jasper-Reports, flexible und schöne Reports zu erzeugen.
+Dies funktioniert gut und ist für regelmäßig benutzte Reports sehr sinnvoll.
+
+Für ad-hoc Reports, die nur sehr selten oder sogar nur einmal benutzt werden, ist die
+Erstellung eines Jasper-Reports und die Einbindung in APplus jedoch zu zeitaufwändig. 
+Teilweise genügen die Ergebnisse einer SQL-Abfrage, die direkt im MS SQL Server abgesetzt 
+werden kann. Wird es etwas komplizierter oder sollen die Ergebnisse noch etwas verarbeitet
+werden, bietet sich evtl. Python an. 
+
+Folgendes Script erzeugt zum Beispiel eine Excel-Tabelle, mit einer Übersicht,
+welche Materialen wie oft für Artikel benutzt werden:
+
+.. literalinclude:: ../../examples/adhoc_report.py
+   :language: python
+   :linenos:
+
+Dieses kurze Script nutzt Standard-Pandas Methoden zur Erzeugung der Excel-Datei. Allerdings
+sind diese Methoden in den Aufrufen von `pandasReadSql` und `exportToExcel` gekapselt,
+so dass der Aufruf sehr einfach ist. Zudem ist es sehr einfach, die Verbindung zur Datenbank
+und zum APP-Server mittels der YAML-Konfigdatei herzustellen. Bei diesem 
+Aufruf kann optional ein Nutzer und eine Umgebung übergeben werden, die die Standard-Werte aus 
+der YAML-Datei überschreiben. `pandasReadSql` nutzt intern `completeSQL`, so dass 
+der für die Umgebung korrekte Mandant automatisch verwendet wird.
+
+
+
+Anbindung eigener Tools
+-----------------------
+
+Ursprünglich wurde `PyAPplus64` für die Anbindung einer APplus-Anpassung geschrieben. Dieses ist 
+als Windows-Service auf einem eigenen Rechner installiert und überwacht dort ein bestimmtes Verzeichnis.
+Bei Änderungen an Dateien in diesem Verzeichnis (Hinzufügen, Ändern, Löschen) werden die Dateien verarbeitet
+und die Ergebnisse an APplus gemeldet. Dafür werden DB-Operationen aber auch SOAP-Calls benutzt.
+Ebenso wird auf die SysConf zugegriffen.
+
+Viele solcher Anpassungen lassen sich gut und sinnvoll im App-Server einrichten und als Job regelmäßig aufrufen. 
+Im konkreten Fall wird jedoch für die Verarbeitung der Dateien viel Rechenzeit benötigt. Dies würde dadurch 
+verschlimmert, dass die Dateien nicht auf der gleichen Maschine wie der App-Server liegen und somit 
+viele, relativ langsame Dateizugriffe über das Netzwerk nötig wären. Hinzu kommt, dass die
+Verarbeitung der Dateien dank existierender Bibliotheken in Python einfacher ist.
+
+`PyAPplus64` kann für solche Anpassungen eine interessante Alternative zur Implementierung im App-Server 
+oder zur Entwicklung eines Tools ohne spezielle Bibliotheken sein. Nach Initialisierung des Servers::
+
+   import PyAPplus64
+
+   server = PyAPplus64.applus.applusFromConfigFile("my-applus-server.yaml") 
+
+bietet `P2APplus64` wie oben demonstriert einfachen lesenden und schreibenden Zugriff auf die DB. Hierbei 
+werden automatisch die für die Umgebung nötigen Mandanten zu den SQL Statements hinzugefügt. Zudem ist einfach ein
+Zugriff auf die Sysconf möglich::
+
+   print (server.sysconf.getString("STAMM", "MYLAND"))
+   print (server.sysconf.getList("STAMM", "EULAENDER"))
+
+Dank der Bibliothek `zeep` ist es auch sehr einfach möglich, auf beliebige SOAP-Methoden zuzugreifen.
+Beispielsweise kann auf die Sys-Config auch händisch, d.h. durch direkten Aufruf einer SOAP-Methode,
+zugegriffen werden::
+
+   client = server.server_conn.getClient("p2system", "SysConf");
+   print (client.service.getString("STAMM", "MYLAND"))
+
+

docs/source/beschreibung.rst

@@ -0,0 +1,42 @@
+Beschreibung
+============
+
+Das Paket `PyAPplus64` enthält eine Sammlung von Python Tools für die Interaktion mit dem ERP-System APplus 6.4. 
+Es sollte auch für andere APplus Versionen nützlich sein. 
+
+Zielgruppe sind APplus-Administratoren und Anpassungs-Entwickler. `PyAPplus64` erlaubt u.a.
+
+- einfacher Zugriff auf SOAP-Schnittstelle des APP-Servers
+   + damit Zugriff auf SysConfig
+   + Zugriff auf Tools wie z.B. `nextNumber` für Erzeugung der nächsten Nummer für ein Business-Object
+   + ...   
+- Zugriff auf APplus DB per direktem DB-Zugriff und mittels SOAP
+   + automatischer Aufruf von `completeSQL`, um per AppServer SQL-Statements um z.B. Mandanten erweitern zu lassen
+   + Tools für einfache Benutzung von `useXML`, d.h. für das Einfügen, Löschen und Ändern von Datensätzen
+     mit Hilfe des APP-Servers. Genau wie bei Änderungen an Datensätzen über die Web-Oberfläche und im Gegensatz 
+     zum direkten Zugriff über die Datenbank werden dabei evtl. zusätzliche 
+     Checks ausgeführt, bestimmte Felder automatisch gesetzt oder bestimmte Aktionen angestoßen. 
+- das Duplizieren von Datensätzen
+   + zu kopierende Felder aus XML-Definitionen werden ausgewertet
+   + Abhängige Objekte können einfach ebenfalls mit-kopiert werden
+   + Änderungen wie beispielsweise Nummer des Objektes möglich
+   + Unterstützung für Kopieren dyn. Attribute
+   + Anlage neuer Objekte mittels APP-Server
+   + Datensätze können zwischen Systemen kopiert und auch in Dateien gespeichert werden
+   + Beispiel: Kopieren von Artikeln mit Arbeitsplan und Stückliste zwischen Deploy- und Prod-System
+- einfaches Erstellen von Excel-Reports aus SQL-Abfragen
+   + mittels Pandas und XlsxWriter
+   + einfache Wrapper um andere Libraries, spart aber Zeit
+- ...
+
+In `PyAPplus64` wurden die Features (vielleicht leicht verallgemeinert)
+implementiert, die ich für konkrete Aufgabenstellungen benötigte. Ich gehe davon
+aus, dass im Laufe der Zeit weitere Features hinzukommen.
+
+Warnung
+-------
+
+`PyAPplus64` erlaubt den schreibenden Zugriff auf die APplus Datenbank und beliebige 
+Aufrufe von SOAP-Methoden. Unsachgemäße Nutzung kann Ihre Daten zerstören. Benutzen Sie 
+`PyAPplus64` daher bitte vorsichtig. Zudem kann ich leider nicht garantieren, dass `PyAPplus64` fehlerfrei ist. 
+

docs/source/conf.py

@@ -0,0 +1,56 @@
+import pathlib
+import sys
+
+sys.path.append('../src/')
+
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'PyAPplus64'
+copyright = '2023, Thomas Tuerk'
+author = 'Thomas Tuerk'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.duration',
+    'sphinx.ext.doctest',
+    'sphinx.ext.autodoc',    
+    'sphinx.ext.autosummary',
+]
+
+templates_path = ['_templates']
+exclude_patterns = [] # type: ignore
+
+language = 'de'
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'nature'
+# html_static_path = ['_static']
+
+source_suffix = {
+    '.rst': 'restructuredtext',
+}
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    'papersize': 'a4paper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    # 'pointsize': '11pt',
+
+    # Additional stuff for the LaTeX preamble.
+    # 'preamble': PREAMBLE
+}
+
+autodoc_type_aliases = {
+    'SqlValue': 'SqlValue'
+}

docs/source/examples.rst

@@ -0,0 +1,73 @@
+Beispiele
+=========
+
+Im Verzeichnis ``examples`` finden sich Python Dateien, die die Verwendung von `PyAPplus64` demonstrieren. 
+
+
+Config-Dateien
+--------------
+Viele Scripte teilen sich Einstellungen. Beispielsweise greifen fast alle Scripte irgendwie auf APplus zu und benötigen Informationen,
+mit welchem APP-Server, welchem Web-Server und welcher Datenbank sie sich verbinden sollen. Solche Informationen, insbesondere die Passwörter, werden nicht in  
+jedem Script gespeichert, sondern nur in den Config-Dateien. Es bietet sich wohl meist an, 3 Konfigdateien zu erstellen, je eine für 
+das Deploy-, das Test- und das Prod-System. Ein Beispiel ist im Unterverzeichnis ``examples/applus-server.yaml`` zu finden.
+
+.. literalinclude:: ../../examples/applus-server.yaml
+   :language: yaml
+   :linenos:
+   
+Damit nicht in jedem Script immer wieder neu die Konfig-Dateien ausgewählt werden müssen, werden die Konfigs für 
+das Prod-, Test- und Deploy-System in ``examples/applus_configs.py`` hinterlegt. Diese wird in allen Scripten importiert,
+so dass das Config-Verzeichnis und die darin enthaltenen Configs einfach zur Verfügung stehen.
+
+.. literalinclude:: ../../examples/applus_configs.py
+   :language: python
+   :linenos:
+
+   
+``check_dokumente.py``
+-----------------------
+Einfaches Beispiel für lesenden und schreibenden Zugriff auf APplus Datenbank.
+
+.. literalinclude:: ../../examples/check_dokumente.py
+   :language: python
+   :lines: 6-
+   :linenos:
+
+
+``adhoc_report.py``
+-------------------
+Sehr einfaches Beispiel zur Erstellung einer Excel-Tabelle aus einer SQL-Abfrage.
+
+.. literalinclude:: ../../examples/adhoc_report.py
+   :language: python
+   :lines: 7-
+   :linenos:
+
+
+``mengenabweichung.py``
+-----------------------
+Etwas komplizierteres Beispiel zur Erstellung einer Excel-Datei aus SQL-Abfragen.
+
+.. literalinclude:: ../../examples/mengenabweichung.py
+   :language: python
+   :lines: 9-
+   :linenos:
+
+``mengenabweichung_gui.py``
+---------------------------
+Beispiel für eine sehr einfache GUI, die die Eingabe einfacher Parameter erlaubt.
+Die GUI wird um die Erzeugung von Excel-Dateien mit Mengenabweichungen gebaut.
+
+.. literalinclude:: ../../examples/mengenabweichung_gui.pyw
+   :language: python
+   :lines: 7-
+   :linenos:
+
+``copy_artikel.py``
+-----------------------
+Beispiel, wie Artikel inklusive Arbeitsplan und Stückliste dupliziert werden kann.
+
+.. literalinclude:: ../../examples/copy_artikel.py
+   :language: python
+   :lines: 21-
+   :linenos:

docs/source/generated/PyAPplus64.rst

@@ -0,0 +1,93 @@
+PyAPplus64 package
+==================
+
+Submodules
+----------
+
+PyAPplus64.applus module
+------------------------
+
+.. automodule:: PyAPplus64.applus
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+PyAPplus64.applus\_db module
+----------------------------
+
+.. automodule:: PyAPplus64.applus_db
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+PyAPplus64.applus\_scripttool module
+------------------------------------
+
+.. automodule:: PyAPplus64.applus_scripttool
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+PyAPplus64.applus\_server module
+--------------------------------
+
+.. automodule:: PyAPplus64.applus_server
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+PyAPplus64.applus\_sysconf module
+---------------------------------
+
+.. automodule:: PyAPplus64.applus_sysconf
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+PyAPplus64.applus\_usexml module
+--------------------------------
+
+.. automodule:: PyAPplus64.applus_usexml
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+PyAPplus64.duplicate module
+---------------------------
+
+.. automodule:: PyAPplus64.duplicate
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+PyAPplus64.pandas module
+------------------------
+
+.. automodule:: PyAPplus64.pandas
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+PyAPplus64.sql\_utils module
+----------------------------
+
+.. automodule:: PyAPplus64.sql_utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+PyAPplus64.utils module
+-----------------------
+
+.. automodule:: PyAPplus64.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: PyAPplus64
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/index.rst

@@ -0,0 +1,11 @@
+PyAPplus64 Dokumentation
+########################
+
+.. toctree::
+   :maxdepth: 1
+
+   beschreibung
+   anwendungen
+   abhaengigkeiten.rst
+   examples.rst
+   generated/PyAPplus64