#181 Improve documentation (#185)

* #181 Savepoint * #181 Savepoint * #181 Savepoint * #181 Savepoint * #181 Savepoint * #181 Savepoint * #181 Savepoint * #181 Savepoint * #181 Savepoint * #181 Savepoint * #181 Savepoint * #181 Savepoint * #181 Savepoint * #181 Remove /usr/bin/env python3 * #181 Move code inside try-except block * #181 Adjust variable names * #181 Adjust variable names * #181 modify from . import statements * #181 Add datasources * #181 Update errors * #181 Add documentation examples * #181 Wordsmithing * #181 Fix action errors * #181 Prepare for versioned release * Force re-test
senzing-garage · Feb 14, 2025 · 8c596ff · 8c596ff
1 parent 362b59a
commit 8c596ff
Show file tree

Hide file tree

Showing 210 changed files with 6,373 additions and 1,255 deletions.
diff --git a/.github/workflows/README.md b/.github/workflows/README.md
@@ -136,7 +136,7 @@ this action runs [pytest] on the Darwin/macOS platform to perform unit tests and
   - Uses:
     - [actions/checkout]
     - [actions/setup-python]
-    - [senzing-factory/github-action-install-senzing-api]
+    - [senzing-factory/github-action-install-senzing-sdk]
     - [pytest]
     - [actions/upload-artifact]
 
@@ -149,7 +149,7 @@ this action runs [pytest] on the Linux platform to perform unit tests and code c
   - Uses:
     - [actions/checkout]
     - [actions/setup-python]
-    - [senzing-factory/github-action-install-senzing-api]
+    - [senzing-factory/github-action-install-senzing-sdk]
     - [pytest]
     - [actions/upload-artifact]
 
@@ -162,7 +162,7 @@ this action runs [pytest] on the Windows platform to perform unit tests and code
   - Uses:
     - [actions/checkout]
     - [actions/setup-python]
-    - [senzing-factory/github-action-install-senzing-api]
+    - [senzing-factory/github-action-install-senzing-sdk]
     - [pytest]
     - [actions/upload-artifact]
 
@@ -213,5 +213,5 @@ this action runs [pytest] on the Windows platform to perform unit tests and code
 [senzing-factory/build-resources/.../lint-workflows.yaml]: https://github.com/senzing-factory/build-resources/blob/main/.github/workflows/lint-workflows.yaml
 [senzing-factory/build-resources/.../move-pr-to-done-dependabot.yaml]: https://github.com/senzing-factory/build-resources/blob/main/.github/workflows/move-pr-to-done-dependabot.yaml
 [senzing-factory/github-action-docker-buildx-build]: https://github.com/senzing-factory/github-action-docker-buildx-build
-[senzing-factory/github-action-install-senzing-api]: https://github.com/senzing-factory/github-action-install-senzing-api
+[senzing-factory/github-action-install-senzing-sdk]: https://github.com/senzing-factory/github-action-install-senzing-sdk
 [super-linter]: https://github.com/super-linter/super-linter
diff --git a/.github/workflows/mypy.yaml b/.github/workflows/mypy.yaml
@@ -30,9 +30,10 @@ jobs:
           echo "PATH=${PATH}" >> "${GITHUB_ENV}"
           python -m pip install --upgrade pip
           python -m pip install --requirement requirements.txt
+          python -m pip install --requirement test-requirements.txt
           python -m pip install mypy pytest orjson
 
       - name: Run mypy tests
         run: |
           # shellcheck disable=SC2046
-          mypy --strict $(git ls-files '*.py' ':!:docs/source/*' ':!:examples/*')
+          mypy --strict $(git ls-files '*.py' ':!:docs/source/*')
diff --git a/.github/workflows/pylint.yaml b/.github/workflows/pylint.yaml
@@ -28,6 +28,7 @@ jobs:
           echo "PATH=${PATH}" >> "${GITHUB_ENV}"
           python -m pip install --upgrade pip
           python -m pip install --requirement requirements.txt
+          python -m pip install --requirement test-requirements.txt
           python -m pip install psutil pylint pytest pytest_schema
 
       - name: Analysing the code with pylint

diff --git a/.github/workflows/pytest-darwin.yaml b/.github/workflows/pytest-darwin.yaml
@@ -3,21 +3,25 @@ name: pytest darwin
 on: [pull_request, workflow_dispatch]
 
 env:
+  DYLD_LIBRARY_PATH: /opt/senzing/er/lib:/opt/senzing/er/lib/macos
+  LD_LIBRARY_PATH: /opt/senzing/er/lib:/opt/senzing/er/lib/macos
   PYTHONPATH: /Users/runner/work/sz-sdk-python/sz-sdk-python/src
+  SENZING_TOOLS_DATABASE_URL: sqlite3://na:na@nowhere/tmp/sqlite/G2C.db
 
 permissions:
   contents: read
 
 jobs:
   pytest-darwin:
-    name: "pytest OS: ${{ matrix.os }}; Python ${{ matrix.python-version }}"
+    name: "pytest Senzing: ${{ matrix.senzingsdk-version }}; OS: ${{ matrix.os }}; Python ${{ matrix.python-version }}"
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
         os: [macos-latest]
         # 3.9 is unsupported on the darwin runner
         python-version: ["3.10", "3.11", "3.12"]
+        senzingsdk-version: [staging-v4]
 
     steps:
       - name: Checkout repository
@@ -35,6 +39,7 @@ jobs:
           echo "PATH=${PATH}" >> "${GITHUB_ENV}"
           python -m pip install --upgrade pip
           python -m pip install --requirement requirements.txt
+          python -m pip install --requirement test-requirements.txt
           python -m pip install psutil pytest pytest-cov pytest-schema
 
       - if: matrix.python-version == '3.10'
@@ -43,6 +48,21 @@ jobs:
           source ./venv/bin/activate
           python -m pip install typing_extensions
 
+      - name: Install Senzing SDK
+        uses: senzing-factory/github-action-install-senzing-sdk@v2
+        with:
+          senzingsdk-repository-path: ${{ secrets.SENZING_OSX_BETA_REPOSITORY }}
+
+      - name: Copy /etc files
+        run: |
+          sudo mkdir -p /opt/senzing/er/etc
+          sudo cp testdata/senzing-license/g2.lic /opt/senzing/er/etc/g2.lic
+
+      - name: Copy test database files
+        run: |
+          mkdir /tmp/sqlite
+          cp testdata/sqlite/G2C.db /tmp/sqlite/G2C.db
+
       - name: Run pytest on tests
         run: |
           source ./venv/bin/activate

diff --git a/.github/workflows/pytest-linux.yaml b/.github/workflows/pytest-linux.yaml
@@ -3,7 +3,9 @@ name: pytest linux
 on: [push, pull_request]
 
 env:
+  LD_LIBRARY_PATH: /opt/senzing/er/lib
   PYTHONPATH: /home/runner/work/sz-sdk-python/sz-sdk-python/src
+  SENZING_TOOLS_DATABASE_URL: sqlite3://na:na@nowhere/tmp/sqlite/G2C.db
 
 permissions:
   contents: read
@@ -17,6 +19,7 @@ jobs:
       matrix:
         os: [ubuntu-latest]
         python-version: ["3.9", "3.10", "3.11", "3.12"]
+        senzingsdk-version: [staging-v4]
 
     steps:
       - name: Checkout repository
@@ -34,6 +37,7 @@ jobs:
           echo "PATH=${PATH}" >> "${GITHUB_ENV}"
           python -m pip install --upgrade pip
           python -m pip install --requirement requirements.txt
+          python -m pip install --requirement test-requirements.txt
           python -m pip install psutil pytest pytest-cov pytest-schema
 
       - if: matrix.python-version == '3.8' || matrix.python-version == '3.9' || matrix.python-version == '3.10'
@@ -42,22 +46,57 @@ jobs:
           source ./venv/bin/activate
           python -m pip install typing_extensions
 
+      - name: Install Senzing SDK
+        uses: senzing-factory/github-action-install-senzing-sdk@v2
+        with:
+          senzingsdk-repository-package: ${{ secrets.SENZING_APT_BETA_STAGING_REPOSITORY_PACKAGE }}
+          senzingsdk-repository-path: ${{ secrets.SENZING_APT_BETA_STAGING_REPOSITORY_URL }}
+
+      - name: Copy /etc files
+        run: |
+          sudo mkdir -p /etc/opt/senzing
+          sudo cp testdata/senzing-license/g2.lic /etc/opt/senzing/g2.lic
+
+      - name: Copy test database files
+        run: |
+          mkdir /tmp/sqlite
+          cp testdata/sqlite/G2C.db /tmp/sqlite/G2C.db
+
       - name: Run pytest on tests
         run: |
           source ./venv/bin/activate
           pytest tests/ --verbose --capture=no --cov=src --cov-append
 
-      - name: Run unittest on examples
+      # Use pytest to check examples, there are no "test" classes/functions, pytest imports
+      # the .py files. If there is a Python error in the examples, an exit code of 1
+      # is returned. If there are no Python errors but pytest didn't think it found any
+      # tests an exit code of 5 is returned, this is a pass but need to capture it and
+      # return 0 - https://docs.pytest.org/en/stable/reference/exit-codes.html
+      - name: Run pytest on examples
         run: |
           source ./venv/bin/activate
-          python3 -m unittest \
-            examples/szconfig/*.py \
-            examples/szconfigmanager/*.py \
-            examples/szdiagnostic/*.py \
-            examples/szengine/*.py \
-            examples/szproduct/*.py \
-            examples/misc/*.py \
-            || true
+          set +e
+          pytest \
+            examples/misc/ \
+            examples/docs/ \
+            examples/extras/ \
+            examples/szabstractfactory/ \
+            examples/szconfig/ \
+            examples/szconfigmanager/ \
+            examples/szdiagnostic/ \
+            examples/szengine/ \
+            examples/szproduct/ \
+            --capture=no \
+            -o python_files=*.py \
+            --verbose
+          pytest_exit_code="$?"
+          set -e
+          if [ "$pytest_exit_code" -eq 5 ]; then
+            echo -e "\nExit code from pytest was $pytest_exit_code, this is expected testing the examples if there were no Python errors\n"
+            exit 0
+          else
+            exit "$pytest_exit_code"
+          fi
 
       - name: Rename coverage file
         env:

diff --git a/.github/workflows/pytest-windows.yaml b/.github/workflows/pytest-windows.yaml
@@ -3,20 +3,23 @@ name: pytest windows
 on: [pull_request, workflow_dispatch]
 
 env:
+  LD_LIBRARY_PATH: 'C:\Program Files\Senzing\er\lib'
   PYTHONPATH: 'D:\a\sz-sdk-python\sz-sdk-python\src'
+  SENZING_TOOLS_DATABASE_URL: 'sqlite3://na:na@nowhere/C:\Temp\sqlite\G2C.db'
 
 permissions:
   contents: read
 
 jobs:
   pytest-windows:
-    name: "pytest OS: ${{ matrix.os }}; Python ${{ matrix.python-version }}"
+    name: "pytest Senzing: ${{ matrix.senzingsdk-version }}; OS: ${{ matrix.os }}; Python ${{ matrix.python-version }}"
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
         os: [windows-latest]
         python-version: ["3.9", "3.10", "3.11", "3.12"]
+        senzingsdk-version: [staging-v4]
 
     steps:
       - name: Checkout repository
@@ -33,14 +36,33 @@ jobs:
           .\\venv\\Scripts\\activate
           python -m pip install --upgrade pip
           python -m pip install --requirement requirements.txt
+          python -m pip install --requirement test-requirements.txt
           python -m pip install psutil pytest pytest-cov pytest-schema
 
-      - if: matrix.python-version == '3.8' || matrix.python-version == '3.9' || matrix.python-version == '3.10'
-        name: Install python libraries for python 3.8, 3.9, and 3.10
+      - if: matrix.python-version == '3.9' || matrix.python-version == '3.10'
+        name: Install python libraries for python 3.9 and 3.10
         run: |
           .\\venv\\Scripts\\activate
           python -m pip install typing_extensions
 
+      - name: Install Senzing SDK
+        uses: senzing-factory/github-action-install-senzing-sdk@v2
+        with:
+          senzingsdk-repository-path: ${{ secrets.SENZING_WIN_BETA_REPOSITORY }}
+
+      - name: Add to "Path" environment variable
+        run: |
+          printf "C:\Program Files\Senzing\er\lib" | Out-File -FilePath "$env:GITHUB_PATH" -Encoding utf8 -Append
+
+      - name: Copy /etc files
+        run: |
+          copy testdata/senzing-license/g2.lic "C:\Program Files\Senzing\er\etc\g2.lic"
+
+      - name: Copy test database files
+        run: |
+          mkdir "C:\Temp\sqlite"
+          copy testdata/sqlite/G2C.db "C:\Temp\sqlite\G2C.db"
+
       - name: Run pytest on tests
         run: |
           .\\venv\\Scripts\\activate

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,19 +7,24 @@ and this project adheres to [Semantic Versioning].
 
 ## [Unreleased]
 
+## [0.2.4] - 2025-02-14
+
+### Changed in 0.2.4
+
+- Updated documentation
+
 ## [0.2.3] - 2025-02-10
 
 ### Fixed in 0.2.3
 
 - Added SzDatabaseTransientError & SzSdkError to \_\_init\_\_.py for importing
 
-
 ## [0.2.2] - 2025-01-28
 
 ### Added in 0.2.2
 
 - Simpler class methods for szengineflags to build upon in a future release
-- documentation-requirements.txt 
+- documentation-requirements.txt
 
 ### Changed in 0.2.2
 

diff --git a/Makefile b/Makefile
@@ -75,6 +75,7 @@ dependencies-for-development: venv dependencies-for-development-osarch-specific
 		python3 -m pip install --upgrade pip; \
 		python3 -m pip install --requirement development-requirements.txt
 
+
 .PHONY: dependencies-for-documentation
 dependencies-for-documentation: venv dependencies-for-documentation-osarch-specific
 	$(activate-venv); \
@@ -115,24 +116,7 @@ lint: pylint mypy bandit black flake8 isort
 # -----------------------------------------------------------------------------
 
 .PHONY: test
-test: test-tests
-
-
-.PHONY: test-tests
-test-tests:
-	$(info --- Unit tests -----------------------------------------------------------------)
-	@$(activate-venv); pytest tests --verbose --capture=no --cov=src/senzing --cov-report xml:coverage.xml
-
-
-# .PHONY: test-examples
-# test-examples:
-# 	$(info --- Test examples --------------------------------------------------------------)
-# 	@$(activate-venv); python3 -m unittest \
-# 		examples/szconfig/*.py \
-# 		examples/szconfigmanager/*.py \
-# 		examples/szdiagnostic/*.py \
-# 		examples/szengine/*.py \
-# 		examples/szproduct/*.py
+test: test-osarch-specific
 
 
 .PHONY: docker-test
@@ -228,7 +212,7 @@ isort:
 mypy:
 	$(info ${\n})
 	$(info --- mypy -----------------------------------------------------------------------)
-	@$(activate-venv); mypy --strict $(shell git ls-files '*.py' ':!:docs/source/*' ':!:examples/*')
+	@$(activate-venv); mypy --strict $(shell git ls-files '*.py' ':!:docs/source/*')
 
 
 .PHONY: pydoc

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -33,6 +33,7 @@
 
 sys.path.insert(0, os.path.abspath("../../src"))
 
+
 extensions = [
     "autodocsumm",  # to generate tables of functions, attributes, methods, etc.
     "sphinx_toolbox.collapse",  # support collapsable sections