Merge remote-tracking branch 'origin/main' into docker_ci

# Conflicts:
#	.github/workflows/release.yml

Author: s-heppner

.github/workflows/ci.yml

@@ -3,7 +3,7 @@ name: ci
 on: [push, pull_request]
 
 env:
-  X_PYTHON_MIN_VERSION: "3.9"
+  X_PYTHON_MIN_VERSION: "3.10"
   X_PYTHON_MAX_VERSION: "3.12"
 
 jobs:
@@ -45,7 +45,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.9", "3.12"]
+        python-version: ["3.10", "3.12"]
     env:
       COUCHDB_ADMIN_PASSWORD: "yo0Quai3"
       # (2024-10-11, s-heppner)
@@ -154,15 +154,14 @@ jobs:
         working-directory: ./sdk
     steps:
     - uses: actions/checkout@v4
-    - name: Set up Python ${{ env.X_PYTHON_MIN_VERSION }}
+    - name: Set up Python ${{ env.X_PYTHON_MAX_VERSION }}
       uses: actions/setup-python@v5
       with:
-        python-version: ${{ env.X_PYTHON_MIN_VERSION }}
+        python-version: ${{ env.X_PYTHON_MAX_VERSION }}
     - name: Install Python dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install .
-        pip install -r docs/add-requirements.txt
+        pip install .[docs]
     - name: Check documentation for errors
       run: |
         SPHINXOPTS="-a -E -n -W --keep-going" make -C docs html
@@ -209,7 +208,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.9", "3.12"]
+        python-version: ["3.10", "3.12"]
     defaults:
       run:
         working-directory: ./compliance_tool
@@ -255,13 +254,13 @@ jobs:
         pip install .[dev]
     - name: Check typing with MyPy
       run: |
-        mypy ./aas_compliance_tool test
+        mypy aas_compliance_tool test
     - name: Check code style with PyCodestyle
       run: |
-        pycodestyle --count --max-line-length 120 ./aas_compliance_tool test
+        pycodestyle --count --max-line-length 120 aas_compliance_tool test
 
-  compliance-tool-readme-codeblocks:
-    # This job runs the same static code analysis (mypy and pycodestyle) on the codeblocks in our docstrings.
+  compliance-tool-package:
+    # This job checks if we can build our compliance_tool package
     runs-on: ubuntu-latest
 
     defaults:
@@ -273,42 +272,43 @@ jobs:
       uses: actions/setup-python@v5
       with:
         python-version: ${{ env.X_PYTHON_MIN_VERSION }}
-    - name: Install Python dependencies
-      # install the local sdk in editable mode so it does not get overwritten
+    - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install -e ../sdk[dev]
-        pip install .[dev]
-    - name: Check typing with MyPy
-      run: |
-        mypy <(codeblocks python README.md)
-    - name: Check code style with PyCodestyle
-      run: |
-        codeblocks --wrap python README.md | pycodestyle --count --max-line-length 120 -
-    - name: Run readme codeblocks with Python
+        pip install build
+    - name: Create source and wheel dist
       run: |
-        codeblocks python README.md | python
+        python -m build
 
-  compliance-tool-package:
-    # This job checks if we can build our compliance_tool package
+ #server-test:
+    # TODO: This job runs the unittests on the python versions specified down at the matrix
+    #   and aas-test-engines on the server
+
+
+  server-static-analysis:
+    # This job runs static code analysis, namely pycodestyle and mypy
     runs-on: ubuntu-latest
 
     defaults:
       run:
-        working-directory: ./compliance_tool
+        working-directory: ./server/app
     steps:
     - uses: actions/checkout@v4
     - name: Set up Python ${{ env.X_PYTHON_MIN_VERSION }}
       uses: actions/setup-python@v5
       with:
         python-version: ${{ env.X_PYTHON_MIN_VERSION }}
-    - name: Install dependencies
+    - name: Install Python dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install build
-    - name: Create source and wheel dist
+        pip install ../../sdk
+        pip install .[dev]
+    - name: Check typing with MyPy
       run: |
-        python -m build
+        mypy .
+    - name: Check code style with PyCodestyle
+      run: |
+        pycodestyle --count --max-line-length 120 .
 
   server-package:
     # This job checks if we can build our server package
@@ -320,7 +320,7 @@ jobs:
       - uses: actions/checkout@v4
       - name: Build the Docker image
         run: |
-          docker build -t basyx-python-server .
+          docker build -t basyx-python-server -f Dockerfile ..
       - name: Run container
         run: |
            docker run -d --name basyx-python-server basyx-python-server

.github/workflows/release.yml

@@ -5,7 +5,7 @@ on:
     types: [published]
 
 jobs:
-  publish-pypi:
+  sdk-publish:
     # This job publishes the package to PyPI
     runs-on: ubuntu-latest
     defaults:
@@ -32,7 +32,34 @@ jobs:
       with:
         password: ${{ secrets.PYPI_ORG_TOKEN }}
 
-  publish-dockerhub:
+  compliance-tool-publish:
+    # This job publishes the compliance_tool package to PyPI
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./compliance_tool
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+      - name: Create source and wheel dist
+        # (2024-12-11, s-heppner)
+        # The PyPI Action expects the dist files in a toplevel `/dist` directory,
+        # so we have to specify this as output directory here.
+        run: |
+          python -m build --outdir ../dist
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_ORG_TOKEN }}
+
+  server-publish:
     # This job publishes the server docker image to DockerHub
     runs-on: ubuntu-latest
     defaults:

.gitignore

@@ -21,14 +21,16 @@ htmlcov/
 docs/build/
 .hypothesis/
 
-# customized config files
+# Customized config files
 sdk/test/test_config.ini
 # Schema files needed for testing
 sdk/test/adapter/schemas
 
 # Ignore dynamically generated version file
 sdk/basyx/version.py
 compliance_tool/aas_compliance_tool/version.py
+server/app/version.py
 
-# ignore the content of the server storage
+# Ignore the content of the server storage
+server/input/
 server/storage/

CONTRIBUTING.md

@@ -119,16 +119,41 @@ The following guidelines are for the commit or PR message text:
   via `https://link/to.pdf#Page=123`
 - Optionally, where applicable reference respective issues: `Fixes #123`
 
-## Codestyle and Testing
+## Code Quality
 
+The Eclipse BaSyx Python project emphasizes high code quality.
+To achieve this, we apply best practices where possible and have developed an extensive suite of tests that are 
+expected to pass for each Pull Request to the project. 
+
+### Codestyle
 Our code follows the [PEP 8 -- Style Guide for Python Code](https://www.python.org/dev/peps/pep-0008/)
 with the following exceptions:
 - Line length is allowed to be up to 120 characters, though lines up to 100 characters are preferred.
 
 Additionally, we use [PEP 484 -- Type Hints](https://www.python.org/dev/peps/pep-0484/) throughout the code to enable type checking the code.
 
-Before submitting any changes, make sure to let `mypy` and `pycodestyle` check your code and run the unit tests with
-Python's builtin `unittest`. To install the required tools, use:
+Before submitting any changes to the SDK, make sure to let `mypy` and `pycodestyle` check your code and run the unit 
+tests with Python's builtin `unittest`. 
+
+### Testing
+There are many automated checks implemented in the CI pipelines of this project, all of which are expected to pass 
+before new code can be added:
+
+- We check that the Python packages can be built.
+- We run the developed unittests and aim for a code coverage of at least 80%.
+- We perform static code analysis for type-checking and codestyle, not just in the code itself, but also in codeblocks 
+  that are inside docstrings and the `README.md`.
+- We check that the automatically generated developer documentation compiles.
+- We check that the Python Versions we support match between the different subprojects in the monorepository and are 
+  not End of Life.
+- We check that the year in the copyright headers in each file (stemming from the license) is correct.
+
+> [!note]
+> We strongly suggest to run the tests locally, before submitting a Pull Request, in order to accelerate the review 
+> process. 
+
+### Testing the SDK
+For testing the SDK locally on your machine, you can install the required tools like so:
 ```bash
 pip install .[dev]
 ```
@@ -142,12 +167,51 @@ Running all checks:
 mypy basyx test
 pycodestyle --max-line-length 120 basyx test
 python -m unittest
+coverage run --source basyx --branch -m unittest
+coverage report -m
 ```
 
-We aim to cover our code with test by at least 80%. To check test coverage, you can use `coverage`:
+We aim to cover our code with tests by at least 80%.
+
+This should help you sort out the most important bugs in your code.
+Note that there are more checks that run in the CI once you open a Pull Request.
+If you want to run the additional checks, please refer to the [CI definition](./.github/workflows/ci.yml).
 
+### Testing the Server
+Currently, the automated server tests are still under development. 
+To test that the server is working, we expect to at least be able to build the docker images and run a container
+of it without error. 
+
+For that, you need to have Docker installed on your system. 
+In the directory with the `Dockerfile`: 
 ```bash
-pip install coverage
+docker build -t basyx-python-server .
+docker run --name basyx-python-server basyx-python-server
+```
+Wait until you see the line:
+```
+INFO success: quit_on_failure entered RUNNING state
+```
+
+### Testing the Compliance Tool
+For the Compliance Tool, you can install the required tools like this (from the `./compliance_tool` directory):
+```bash
+pip install -e ../sdk[dev]
+pip install .[dev]
+```
+The first line installs the SDK and its dependencies, the second the developer dependencies for the compliance tool
+itself.
+
+Then you can run the checks via:
+```bash
+mypy basyx test
+pycodestyle --max-line-length 120 basyx test
+python -m unittest
 coverage run --source basyx --branch -m unittest
 coverage report -m
 ```
+
+We aim to cover our code with tests by at least 80%.
+This should help you sort out the most important bugs in your code.
+Note that there are more checks that run in the CI once you open a Pull Request.
+If you want to run the additional checks, please refer to the [CI definition](./.github/workflows/ci.yml).

README.md

@@ -1,10 +1,11 @@
 # Eclipse BaSyx Python SDK
 
-(formerly known as PyI40AAS – Python Industry 4.0 Asset Administration Shell)
-
 The Eclipse BaSyx Python project focuses on providing a Python implementation of the Asset Administration Shell (AAS) 
-for Industry 4.0 Systems. 
-These are the currently implemented specifications:
+for Industry 4.0 Systems.
+
+**Please note that the SDK version number is independent of the supported AAS versions!**
+
+These are the implemented AAS specifications of the [current SDK release](https://github.com/eclipse-basyx/basyx-python-sdk/releases/latest), which can be also found on [PyPI](https://pypi.org/project/basyx-python-sdk/):
 
 | Specification                         | Version                                                                                                                                                                         |
 |---------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -14,6 +15,9 @@ These are the currently implemented specifications:
 | Part 3a: Data Specification IEC 61360 | [v3.0 (01003-a-3-0)](https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01003-a-3-0_SpecificationAssetAdministrationShell_Part3a_DataSpecification_IEC61360.pdf) |
 | Part 5: Package File Format (AASX)    | [v3.0 (01005-3-0)](https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01005-3-0_SpecificationAssetAdministrationShell_Part5_AASXPackageFileFormat.pdf)           |
 
+If you need support to an older version of the specifications, please refer to our [prior releases](https://github.com/eclipse-basyx/basyx-python-sdk/releases). 
+Each of them has a similar table at the top of the release notes.
+
 ## Features
 This repository is structured into separate packages. 
 The `sdk` directory provides the AAS metamodel as Python objects and fundamental functionalities to handle AAS.

compliance_tool/pyproject.toml

@@ -34,7 +34,7 @@ classifiers = [
     "Operating System :: OS Independent",
     "Development Status :: 5 - Production/Stable"
 ]
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 dependencies = [
     "pyecma376-2>=0.2.4",
     "jsonschema>=4.21.1",

compliance_tool/setup.py

@@ -6,7 +6,7 @@ version: 2
 build:
   os: ubuntu-20.04
   tools:
-    python: "3.9"
+    python: "3.10"
 
 sphinx:
    configuration: docs/source/conf.py
@@ -15,4 +15,5 @@ python:
   install:
     - method: pip
       path: .
-    - requirements: docs/add-requirements.txt
+      extra_requirements:
+        - docs