Add adapter to write/read AASX packages

.github/workflows/ci.yml

@@ -51,6 +51,7 @@ jobs:
         pip install pycodestyle mypy
         cd ./sdk
         pip install .
+        python -m pip install lxml-stubs
     - name: Check typing with MyPy
       run: |
         mypy sdk --exclude sdk/build
@@ -99,3 +100,23 @@ jobs:
     - name: Check documentation for errors
       run: |
         SPHINXOPTS="-a -E -n -W --keep-going" make -C docs html
+
+
+  package:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python ${{ env.X_PYTHON_VERSION }}
+      uses: actions/setup-python@v2
+      with:
+        python-version: ${{ env.X_PYTHON_VERSION }}
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -q build
+    - name: Create source and wheel dist
+      run: |
+        ls
+        cd ./sdk
+        python -m build

sdk/basyx/__init__.py

@@ -1 +1,5 @@
 from .object_store import *
+
+# Alias `types` as `model` to maintain consistency with the import style of the predecessor project (BaSyx-Python SDK),
+# ensuring a familiar experience for users transitioning to the new BaSyx-Python Framework.
+from aas_core3 import types as model

sdk/basyx/object_store.py

@@ -15,9 +15,8 @@
 
 from aas_core3.types import Identifiable, Referable, Class
 
-# We define types for :class:`aas_core3.types.Identifier` and :class:`aas_core3.types.Referable` for easier referencing.
+# We define types for :class:`aas_core3.types.Identifier` for easier referencing.
 _IdentifiableType = TypeVar('_IdentifiableType', bound=Identifiable)
-_ReferableType = TypeVar('_ReferableType', bound=Referable)
 
 
 class AbstractObjectProvider(metaclass=abc.ABCMeta):

sdk/basyx/tutorial/tutorial_aasx.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""
+Tutorial for exporting Asset Administration Shells with related objects and auxiliary files to AASX package files, using
+the :mod:`~basyx.aasx` module from the Eclipse BaSyx Python Framework.
+
+"""
+
+import datetime
+from pathlib import Path  # Used for easier handling of auxiliary file's local path
+
+import pyecma376_2  # The base library for Open Packaging Specifications. We will use the OPCCoreProperties class.
+from basyx import model
+from basyx.aasx import AASXWriter, AASXReader, DictSupplementaryFileContainer
+from basyx.object_store import ObjectStore
+
+# step 1: Setting up an SupplementaryFileContainer and AAS & submodel with File objects
+# step 2: Writing AAS objects and auxiliary files to an AASX package
+# step 3: Reading AAS objects and auxiliary files from an AASX package
+
+
+########################################################################################
+# Step 1: Setting up a SupplementaryFileContainer and AAS & submodel with File objects #
+########################################################################################
+
+# Let's first create a basic Asset Administration Shell with a simple submodel.
+# See `tutorial_create_simple_aas.py` for more details.
+submodel = model.Submodel(id='https://acplt.org/Submodel', submodel_elements=[])
+
+key_types = model.KeyTypes("Submodel")
+Referencetype = model.ReferenceTypes("ModelReference")
+key = model.Key(value='https://acplt.org/Submodel', type=key_types)
+reference = model.Reference(type=Referencetype, keys=[key])
+
+aas = model.AssetAdministrationShell(id='https://acplt.org/Simple_AAS',
+                                        asset_information=model.AssetInformation(
+                                           asset_kind=model.AssetKind.TYPE),
+                                        submodels=[reference])
+
+# Another submodel, which is not related to the AAS:
+unrelated_submodel = model.Submodel(
+    id='https://acplt.org/Unrelated_Submodel'
+)
+
+# We add these objects to an ObjectStore for easy retrieval by id.
+object_store: ObjectStore = ObjectStore([unrelated_submodel, submodel, aas])
+
+
+# For holding auxiliary files, which will eventually be added to an AASX package, we need a SupplementaryFileContainer.
+# The `DictSupplementaryFileContainer` is a simple SupplementaryFileContainer that stores the files' contents in simple
+# bytes objects in memory.
+file_store = DictSupplementaryFileContainer()
+
+# Now, we add an example file from our local filesystem to the SupplementaryFileContainer.
+#
+# For this purpose, we need to specify the file's name in the SupplementaryFileContainer. This name is used to reference
+# the file in the container and will later be used as the filename in the AASX package file. Thus, this file must begin
+# with a slash and should begin with `/aasx/`. Here, we use `/aasx/suppl/MyExampleFile.pdf`. The
+# SupplementaryFileContainer's add_file() method will ensure uniqueness of the name by adding a suffix if an equally
+# named file with different contents exists. The final name is returned.
+#
+# In addition, we need to specify the MIME type of the file, which is later used in the metadata of the AASX package.
+# (This is actually a requirement of the underlying Open Packaging Conventions (ECMA376-2) format, which imposes the
+# specification of the MIME type ("content type") of every single file within the package.)
+
+with open(Path(__file__).parent / 'data' / 'TestFile.pdf', 'rb') as f:
+    actual_file_name = file_store.add_file("/aasx/suppl/MyExampleFile.pdf", f, "application/pdf")
+
+
+# With the actual_file_name in the SupplementaryFileContainer, we can create a reference to that file in our AAS
+# Submodel, in the form of a `File` object:
+
+model.File(id_short="documentationFile", content_type="application/pdf", value=actual_file_name)
+
+file = model.File(id_short="documentationFile", content_type="application/pdf", value=actual_file_name)
+if submodel.submodel_elements is not None:
+    submodel.submodel_elements.append(file)
+
+
+######################################################################
+# Step 2: Writing AAS objects and auxiliary files to an AASX package #
+######################################################################
+
+# After setting everything up in Step 1, writing the AAS, including the Submodel objects and the auxiliary file
+# to an AASX package is simple.
+
+# Open an AASXWriter with the destination file name and use it as a context handler, to make sure it is properly closed
+# after doing the modifications:
+with AASXWriter("./MyAASXPackage.aasx") as writer:
+    # Write the AAS and everything belonging to it to the AASX package
+    # The `write_aas()` method will automatically fetch the AAS object with the given id
+    # and all referenced Submodel objects from the ObjectStore. It will also scan every object for
+    # semanticIds referencing ConceptDescription, fetch them from the ObjectStore, and scan all sbmodels for `File`
+    # objects and fetch the referenced auxiliary files from the SupplementaryFileContainer.
+    # In order to add more than one AAS to the package, we can simply add more Identifiers to the `aas_ids` list.
+    #
+    # ATTENTION: As of Version 3.0 RC01 of Details of the Asset Administration Shell, it is no longer valid to add more
+    # than one "aas-spec" part (JSON/XML part with AAS objects) to an AASX package. Thus, `write_aas` MUST
+    # only be called once per AASX package!
+    writer.write_aas(aas_ids=['https://acplt.org/Simple_AAS'],
+                     object_store=object_store,
+                     file_store=file_store)
+
+    # Alternatively, we can use a more low-level interface to add a JSON/XML part with any Identifiable objects (not
+    # only an AAS and referenced objects) in the AASX package manually. `write_aas_objects()` will also take care of
+    # adding referenced auxiliary files by scanning all submodel objects for contained `File` objects.
+    #
+    # ATTENTION: As of Version 3.0 RC01 of Details of the Asset Administration Shell, it is no longer valid to add more
+    # than one "aas-spec" part (JSON/XML part with AAS objects) to an AASX package. Thus, `write_all_aas_objects` SHALL
+    # only be used as an alternative to `write_aas` and SHALL only be called once!
+    objects_to_be_written: ObjectStore[model.Identifiable] = ObjectStore([unrelated_submodel])
+    writer.write_all_aas_objects(part_name="/aasx/my_aas_part.xml",
+                                 objects=objects_to_be_written,
+                                 file_store=file_store)
+
+    # We can also add a thumbnail image to the package (using `writer.write_thumbnail()`) or add metadata:
+    meta_data = pyecma376_2.OPCCoreProperties()
+    meta_data.creator = "Chair of Process Control Engineering"
+    meta_data.created = datetime.datetime.now()
+    writer.write_core_properties(meta_data)
+
+# Closing the AASXWriter will write some required parts with relationships and MIME types to the AASX package file and
+# close the package file afterward. Make sure, to always call `AASXWriter.close()` or use the AASXWriter in a `with`
+# statement (as a context manager) as shown above.
+
+
+########################################################################
+# Step 3: Reading AAS objects and auxiliary files from an AASX package #
+########################################################################
+
+# Let's read the AASX package file, we have just written.
+# We'll use a fresh ObjectStore and SupplementaryFileContainer to read AAS objects and auxiliary files into.
+new_object_store: ObjectStore = ObjectStore()
+new_file_store = DictSupplementaryFileContainer()
+
+# Again, we need to use the AASXReader as a context manager (or call `.close()` in the end) to make sure the AASX
+# package file is properly closed when we are finished.
+with AASXReader("MyAASXPackage.aasx") as reader:
+    # Read all contained AAS objects and all referenced auxiliary files
+    reader.read_into(object_store=new_object_store,
+                     file_store=new_file_store)
+
+    # We can also read the metadata
+    new_meta_data = reader.get_core_properties()
+
+    # We could also read the thumbnail image, using `reader.get_thumbnail()`
+
+
+# Some quick checks to make sure, reading worked as expected
+assert 'https://acplt.org/Submodel' in new_object_store
+assert actual_file_name in new_file_store
+assert new_meta_data.creator == "Chair of Process Control Engineering"

sdk/basyx/tutorial/tutorial_objectstore.py

@@ -7,7 +7,7 @@
 
 from basyx.object_store import ObjectStore
 from aas_core3.types import Identifiable, AssetAdministrationShell, AssetInformation, AssetKind
-import aas_core3.types as aas_types
+from basyx import model as aas_types
 
 aas = AssetAdministrationShell(id="urn:x-test:aas1",
                                asset_information=AssetInformation(asset_kind=AssetKind.TYPE))
@@ -78,3 +78,6 @@
 # Retrieve parent of list_element by id_short
 
 print(element_list == obj_store.get_parent_referable("list_1"))
+
+print(aas.__dict__)
+print(type(submodel1), type(aas))

sdk/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "basyx-python-framework-base"
 version = "0.1"
-dependencies = ["aas-core3.0"]
+dependencies = ["aas-core3.0", "pyecma376-2"]
 requires-python = ">=3.8, <3.13"
 authors = [
   {name = "The Eclipse BaSyx Authors"}
@@ -14,3 +14,7 @@ authors = [
 description="The Eclipse BaSyx Python SDK, an implementation of the Asset Administration Shell for Industry 4.0 systems"
 readme = "README.md"
 license = {file = "./LICENSE"}
+
+[tool.setuptools]
+packages = ["basyx"]
+py-modules = ['basyx']

sdk/test/example_aas.py

@@ -0,0 +1,52 @@
+from aas_core3 import types as model
+from basyx.object_store import ObjectStore
+import aas_core3.types as aas_types
+from basyx.aasx import DictSupplementaryFileContainer
+from pathlib import Path
+
+
+def create_full_example() -> ObjectStore:
+    """
+    Creates an object store which is filled with an example :class:`~basyx.aas.model.submodel.Submodel`,
+    :class:`~basyx.aas.model.concept.ConceptDescription` and :class:`~basyx.aas.model.aas.AssetAdministrationShell`
+    using the functions of this module
+
+    :return: :class:`~basyx.aas.model.provider.DictObjectStore`
+    """
+    Referencetype = aas_types.ReferenceTypes("ModelReference")
+
+    key_types = aas_types.KeyTypes("Submodel")
+
+    key = aas_types.Key(value="some-unique-global-identifier", type=key_types)
+
+    reference = aas_types.Reference(type=Referencetype, keys=[key])
+
+    submodel = aas_types.Submodel(
+        id="some-unique-global-identifier",
+        submodel_elements=[
+            aas_types.Property(
+                id_short="some_property",
+                value_type=aas_types.DataTypeDefXSD.INT,
+                value="1984",
+                semantic_id=reference
+            )
+        ]
+    )
+    file_store = DictSupplementaryFileContainer()
+
+    with open(Path(__file__).parent.parent / 'basyx' / 'tutorial' / 'data' / 'TestFile.pdf', 'rb') as f:
+        actual_file_name = file_store.add_file("/aasx/suppl/MyExampleFile.pdf", f, "application/pdf")
+
+    if submodel.submodel_elements is not None:
+        submodel.submodel_elements.append(aas_types.File(id_short="documentationFile",
+                                                         content_type="application/pdf",
+                                                         value=actual_file_name))
+
+    aas = aas_types.AssetAdministrationShell(id="https://acplt.org/Test_AssetAdministrationShell",
+                                             asset_information=aas_types.AssetInformation(
+                                                 asset_kind=aas_types.AssetKind.TYPE),
+                                             submodels=[reference])
+    obj_store: ObjectStore[model.Identifiable] = ObjectStore()
+    obj_store.add(aas)
+    obj_store.add(submodel)
+    return obj_store