diff --git a/.github/workflows/build-test-docs.yml b/.github/workflows/build-test-docs.yml index cffd57b..398b809 100644 --- a/.github/workflows/build-test-docs.yml +++ b/.github/workflows/build-test-docs.yml @@ -6,19 +6,25 @@ on: tags: [ "**" ] pull_request: branches: [ "**" ] + workflow_dispatch: + +permissions: + contents: read jobs: - Execute: + Build-and-test: runs-on: ubuntu-latest strategy: matrix: + # NOTE: sphinx-paramlinks depends on distutils, which has been removed + # in Python 3.12. python-version: ['3.10'] steps: - - uses: actions/checkout@master + - uses: actions/checkout@v4 - name: Set up Python ${{ matrix.python-version }} - uses: actions/setup-python@v2 + uses: actions/setup-python@v5 with: python-version: ${{ matrix.python-version }} @@ -30,8 +36,35 @@ jobs: - name: Build the docs run: | - sphinx-build docs/source docs/build + sphinx-build -W --keep-going docs/source docs/build - name: Test the docs run: | - sphinx-build docs/source docs/build -b doctest + sphinx-build docs/source docs/build-doctest -b doctest + + - name: Upload the docs as a Pages artifact + uses: actions/upload-pages-artifact@v3 + with: + path: docs/build + + Deploy: + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + needs: Build-and-test + runs-on: ubuntu-latest + + permissions: + pages: write + id-token: write + + concurrency: + group: pages + cancel-in-progress: false + + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.readthedocs.yml b/.readthedocs.yml deleted file mode 100644 index b407e63..0000000 --- a/.readthedocs.yml +++ /dev/null @@ -1,27 +0,0 @@ -# .readthedocs.yml -# Read the Docs configuration file -# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details - -# Required -version: 2 - -# Set the version of Python and other tools you might need -build: - os: ubuntu-22.04 - tools: - python: "3.9" - -# Build documentation in the docs/ directory with Sphinx -sphinx: - configuration: docs/source/conf.py - -# Optionally build your docs in additional formats such as PDF -formats: - - pdf - -# Optionally set the version of Python and requirements required to build your docs -python: - install: - - method: pip - path: . - - requirements: docs/requirements.txt diff --git a/README.rst b/README.rst index 01b4f0b..aedea1f 100644 --- a/README.rst +++ b/README.rst @@ -17,13 +17,13 @@ Eclipse aas-core3.2-python .. image:: https://img.shields.io/pypi/pyversions/aas-core3.2.svg :alt: PyPI - Python Version -.. image:: https://readthedocs.org/projects/aas-core32-python/badge/?version=latest - :target: https://aas-core32-python.readthedocs.io/en/latest/?badge=latest +.. image:: https://github.com/eclipse-aascw/aas-core3.2-python/actions/workflows/build-test-docs.yml/badge.svg + :target: https://eclipse-aascw.github.io/aas-core3.2-python/ :alt: Documentation This is a software development kit (SDK) to manipulate, verify and de/serialize Asset Administration Shells based on the version 3.2 of the meta-model. -The documentation is available on: https://aas-core32-python.readthedocs.io/en/latest/. +The documentation is available on: https://eclipse-aascw.github.io/aas-core3.2-python/ The majority of the code has been automatically generated by `aas-core-codegen`_. @@ -31,4 +31,4 @@ If you want to contribute, see our `contributing guide`_. .. _aas-core-codegen: https://github.com/eclipse-aascw/aas-core-codegen -.. _contributing guide: https://aas-core32-python.readthedocs.io/en/latest/contributing.html +.. _contributing guide: https://eclipse-aascw.github.io/aas-core3.2-python/contributing.html diff --git a/docs/source/api/common.rst b/docs/source/api/common.rst new file mode 100644 index 0000000..8264c2c --- /dev/null +++ b/docs/source/api/common.rst @@ -0,0 +1,8 @@ +******************** +aas_core3_2.common +******************** + +.. automodule:: aas_core3_2.common + :special-members: + :members: + :exclude-members: __abstractmethods__, __module__, __annotations__, __dict__, __weakref__ diff --git a/docs/source/api/constants.rst b/docs/source/api/constants.rst new file mode 100644 index 0000000..31479d4 --- /dev/null +++ b/docs/source/api/constants.rst @@ -0,0 +1,8 @@ +*********************** +aas_core3_2.constants +*********************** + +.. automodule:: aas_core3_2.constants + :special-members: + :members: + :exclude-members: __abstractmethods__, __module__, __annotations__, __dict__, __weakref__ diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst new file mode 100644 index 0000000..1ecffd5 --- /dev/null +++ b/docs/source/api/index.rst @@ -0,0 +1,21 @@ +*** +API +*** + +This is the documentation automatically generated from the source code. + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + common + constants + jsonization + jsonvalueverification + reporting + stringification + types + verification + xmlcommon + xmlization + xmlrpc diff --git a/docs/source/api/jsonization.rst b/docs/source/api/jsonization.rst new file mode 100644 index 0000000..231ca97 --- /dev/null +++ b/docs/source/api/jsonization.rst @@ -0,0 +1,8 @@ +************************* +aas_core3_2.jsonization +************************* + +.. automodule:: aas_core3_2.jsonization + :special-members: + :members: + :exclude-members: __abstractmethods__, __module__, __annotations__, __dict__, __weakref__ diff --git a/docs/source/api/jsonvalueverification.rst b/docs/source/api/jsonvalueverification.rst new file mode 100644 index 0000000..bda5ea7 --- /dev/null +++ b/docs/source/api/jsonvalueverification.rst @@ -0,0 +1,8 @@ +*********************************** +aas_core3_2.jsonvalueverification +*********************************** + +.. automodule:: aas_core3_2.jsonvalueverification + :special-members: + :members: + :exclude-members: __abstractmethods__, __module__, __annotations__, __dict__, __weakref__ diff --git a/docs/source/api/reporting.rst b/docs/source/api/reporting.rst new file mode 100644 index 0000000..b010115 --- /dev/null +++ b/docs/source/api/reporting.rst @@ -0,0 +1,8 @@ +*********************** +aas_core3_2.reporting +*********************** + +.. automodule:: aas_core3_2.reporting + :special-members: + :members: + :exclude-members: __abstractmethods__, __module__, __annotations__, __dict__, __weakref__ diff --git a/docs/source/api/stringification.rst b/docs/source/api/stringification.rst new file mode 100644 index 0000000..7281ca8 --- /dev/null +++ b/docs/source/api/stringification.rst @@ -0,0 +1,8 @@ +***************************** +aas_core3_2.stringification +***************************** + +.. automodule:: aas_core3_2.stringification + :special-members: + :members: + :exclude-members: __abstractmethods__, __module__, __annotations__, __dict__, __weakref__ diff --git a/docs/source/api/types.rst b/docs/source/api/types.rst new file mode 100644 index 0000000..999ed4d --- /dev/null +++ b/docs/source/api/types.rst @@ -0,0 +1,8 @@ +******************* +aas_core3_2.types +******************* + +.. automodule:: aas_core3_2.types + :special-members: + :members: + :exclude-members: __abstractmethods__, __module__, __annotations__, __dict__, __weakref__ diff --git a/docs/source/api/verification.rst b/docs/source/api/verification.rst new file mode 100644 index 0000000..8034662 --- /dev/null +++ b/docs/source/api/verification.rst @@ -0,0 +1,8 @@ +************************** +aas_core3_2.verification +************************** + +.. automodule:: aas_core3_2.verification + :special-members: + :members: + :exclude-members: __abstractmethods__, __module__, __annotations__, __dict__, __weakref__ diff --git a/docs/source/api/xmlcommon.rst b/docs/source/api/xmlcommon.rst new file mode 100644 index 0000000..75a3314 --- /dev/null +++ b/docs/source/api/xmlcommon.rst @@ -0,0 +1,8 @@ +*********************** +aas_core3_2.xmlcommon +*********************** + +.. automodule:: aas_core3_2.xmlcommon + :special-members: + :members: + :exclude-members: __abstractmethods__, __module__, __annotations__, __dict__, __weakref__ diff --git a/docs/source/api/xmlization.rst b/docs/source/api/xmlization.rst new file mode 100644 index 0000000..7108ca3 --- /dev/null +++ b/docs/source/api/xmlization.rst @@ -0,0 +1,8 @@ +************************ +aas_core3_2.xmlization +************************ + +.. automodule:: aas_core3_2.xmlization + :special-members: + :members: + :exclude-members: __abstractmethods__, __module__, __annotations__, __dict__, __weakref__,__subclasshook__,__parameters__ diff --git a/docs/source/api/xmlrpc.rst b/docs/source/api/xmlrpc.rst new file mode 100644 index 0000000..ef3c1c6 --- /dev/null +++ b/docs/source/api/xmlrpc.rst @@ -0,0 +1,8 @@ +******************** +aas_core3_2.xmlrpc +******************** + +.. automodule:: aas_core3_2.xmlrpc + :special-members: + :members: + :exclude-members: __abstractmethods__, __module__, __annotations__, __dict__, __weakref__ diff --git a/docs/source/conf.py b/docs/source/conf.py index 5e1a0d0..3592721 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -49,6 +49,11 @@ autodoc_typehints = 'signature' +# NOTE: The bare ``>>>`` blocks in the docstrings of the generated modules are +# already doctest'ed in dev/continuous_integration/precommit.py with +# the module namespace. Here we only test the explicit doctest directives. +doctest_test_doctest_blocks = '' + autodoc_default_options = { 'members': True, 'undoc-members': True, diff --git a/docs/source/getting_started/create_get_set.rst b/docs/source/getting_started/create_get_set.rst index 1a2b5bc..9b8f3ae 100644 --- a/docs/source/getting_started/create_get_set.rst +++ b/docs/source/getting_started/create_get_set.rst @@ -2,17 +2,17 @@ Create, Get and Set Properties of an AAS Model ********************************************** -The module :py:mod:`aas_core3_1.types` contains all the data types of the meta-model. +The module :py:mod:`aas_core3_2.types` contains all the data types of the meta-model. This includes enumerations, abstract and concrete classes. -The module :py:mod:`aas_core3_1.types` also contains visitors and transformers, but we will write more about them in :ref:`iterate_and_transform` section. +The module :py:mod:`aas_core3_2.types` also contains visitors and transformers, but we will write more about them in :ref:`iterate_and_transform` section. Creation ======== We use constructors to create an AAS model. -Usually you start bottom-up, all the way up to the :py:class:`aas_core3_1.types.Environment`. +Usually you start bottom-up, all the way up to the :py:class:`aas_core3_2.types.Environment`. Getting and Setting Properties ============================== @@ -28,7 +28,7 @@ For optional properties which come with a default value, we provide special gett If the property is ``None``, this getter will give you the default value. Otherwise, if the property is set, the actual value of the property will be returned. -For example, see :py:meth:`aas_core3_1.types.HasKind.kind_or_default`. +For example, see :py:meth:`aas_core3_2.types.HasKind.kind_or_default`. Example: Create an Environment with a Submodel ============================================== @@ -39,7 +39,7 @@ The submodel will contain two elements, a property and a blob. .. doctest:: - import aas_core3_1.types as aas_types + import aas_core3_2.types as aas_types # Create the first element some_element = aas_types.Property( diff --git a/docs/source/getting_started/install.rst b/docs/source/getting_started/install.rst index 06af336..5c8d479 100644 --- a/docs/source/getting_started/install.rst +++ b/docs/source/getting_started/install.rst @@ -8,4 +8,4 @@ Install the SDK by calling: .. code-block:: - pip3 install aas-core3.1 + pip3 install aas-core3.2 diff --git a/docs/source/getting_started/iterate_and_transform.rst b/docs/source/getting_started/iterate_and_transform.rst index 766aee7..38bc33f 100644 --- a/docs/source/getting_started/iterate_and_transform.rst +++ b/docs/source/getting_started/iterate_and_transform.rst @@ -15,23 +15,23 @@ It gives you an :py:class:`Iterator`. If the property is not set, this getter will yield empty. Otherwise, it will yield from the actual property value. -For example, see :py:meth:`aas_core3_1.types.Environment.over_submodels_or_empty`. +For example, see :py:meth:`aas_core3_2.types.Environment.over_submodels_or_empty`. ``descend_once`` and ``descend`` ================================ -If you are writing a simple script and do not care about the performance, the SDK provides two methods in the most general interface :py:class:`aas_core3_1.types.Class`, :py:meth:`~aas_core3_1.types.Class.descend_once` and :py:meth:`~aas_core3_1.types.Class.descend`, which you can use to loop through the instances. +If you are writing a simple script and do not care about the performance, the SDK provides two methods in the most general interface :py:class:`aas_core3_2.types.Class`, :py:meth:`~aas_core3_2.types.Class.descend_once` and :py:meth:`~aas_core3_2.types.Class.descend`, which you can use to loop through the instances. -Both :py:meth:`~aas_core3_1.types.Class.descend_once` and :py:meth:`~aas_core3_1.types.Class.descend` iterate over referenced children of an instance of :py:class:`~aas_core3_1.types.Class`. -:py:meth:`~aas_core3_1.types.Class.descend_once`, as it names suggests, stops after all the children has been iterated over. -:py:meth:`~aas_core3_1.types.Class.descend` continues recursively to grand-children, grand-grand-children *etc.* +Both :py:meth:`~aas_core3_2.types.Class.descend_once` and :py:meth:`~aas_core3_2.types.Class.descend` iterate over referenced children of an instance of :py:class:`~aas_core3_2.types.Class`. +:py:meth:`~aas_core3_2.types.Class.descend_once`, as it names suggests, stops after all the children has been iterated over. +:py:meth:`~aas_core3_2.types.Class.descend` continues recursively to grand-children, grand-grand-children *etc.* Here is a short example how you can get all the properties from an environment whose ID-short starts with ``another``: .. testcode:: - import aas_core3_1.types as aas_types + import aas_core3_2.types as aas_types # Prepare the environment environment = aas_types.Environment( @@ -71,7 +71,7 @@ Here is a short example how you can get all the properties from an environment w another_property yet_another_property -Iteration with :py:meth:`~aas_core3_1.types.Class.descend_once` and :py:meth:`~aas_core3_1.types.Class.descend` works well if the performance is irrelevant. +Iteration with :py:meth:`~aas_core3_2.types.Class.descend_once` and :py:meth:`~aas_core3_2.types.Class.descend` works well if the performance is irrelevant. However, if the performance matters, this is not a good approach. First, all the children will be visited (even though you need only a small subset). Second, you need to switch with :py:func:`isinstance` on the runtime type, which grows linearly in computational cost with the number of types you switch on. @@ -84,26 +84,26 @@ Visitor `Visitor pattern`_ is a common design pattern in software engineering. We will not explain the details of the pattern here as you can read about in the ample literature in books or in Internet. -The cornerstone of the visitor pattern is `double dispatch`_: instead of casting to the desired type during the iteration, the method :py:meth:`aas_core3_1.types.Class.accept` directly dispatches to the appropriate visitation method. +The cornerstone of the visitor pattern is `double dispatch`_: instead of casting to the desired type during the iteration, the method :py:meth:`aas_core3_2.types.Class.accept` directly dispatches to the appropriate visitation method. .. _Visitor pattern: https://en.wikipedia.org/wiki/Visitor_pattern .. _double dispatch: https://en.wikipedia.org/wiki/Double_dispatch This allows us to spare runtime type switches and directly dispatch the execution. -The SDK already implements :py:meth:`~aas_core3_1.types.Class.accept` methods, so you only have to implement the visitor. +The SDK already implements :py:meth:`~aas_core3_2.types.Class.accept` methods, so you only have to implement the visitor. The visitor class has a visiting method for each class of the meta-model. In the SDK, we provide different flavors of the visitor abstract classes which you can readily implement: -* :py:class:`~aas_core3_1.types.AbstractVisitor` which needs all the visit methods to be implemented, -* :py:class:`~aas_core3_1.types.PassThroughVisitor` which visits all the elements and does nothing, and -* :py:class:`~aas_core3_1.types.AbstractVisitorWithContext` which propagates a context object along the iteration. +* :py:class:`~aas_core3_2.types.AbstractVisitor` which needs all the visit methods to be implemented, +* :py:class:`~aas_core3_2.types.PassThroughVisitor` which visits all the elements and does nothing, and +* :py:class:`~aas_core3_2.types.AbstractVisitorWithContext` which propagates a context object along the iteration. -Let us re-write the above example related to :py:meth:`~aas_core3_1.types.Class.descend` method with a visitor pattern: +Let us re-write the above example related to :py:meth:`~aas_core3_2.types.Class.descend` method with a visitor pattern: .. testcode:: - import aas_core3_1.types as aas_types + import aas_core3_2.types as aas_types class Visitor(aas_types.PassThroughVisitor): def visit_property(self, that: aas_types.Property): @@ -147,11 +147,11 @@ Expected output: another_property yet_another_property -There are important differences to iteration with :py:meth:`~aas_core3_1.types.Class.descend`: +There are important differences to iteration with :py:meth:`~aas_core3_2.types.Class.descend`: * Due to `double dispatch`_, we spare a cast. This is usually more efficient. -* The iteration logic in :py:meth:`~aas_core3_1.types.Class.descend` lives very close to where it is executed. +* The iteration logic in :py:meth:`~aas_core3_2.types.Class.descend` lives very close to where it is executed. In contrast, the visitor needs to be defined as a separate class. While sometimes faster, writing the visitor makes the code less readable. @@ -159,7 +159,7 @@ Descend or Visitor? =================== In general, people familiar with the `visitor pattern`_ and object-oriented programming will prefer, obviously, visitor class. -People who like functional programming, generator expressions and ilks will prefer :py:meth:`~aas_core3_1.types.Class.descend`. +People who like functional programming, generator expressions and ilks will prefer :py:meth:`~aas_core3_2.types.Class.descend`. It is difficult to discuss different tastes, so you should probably come up with explicit code guidelines in your code and stick to them. @@ -173,11 +173,11 @@ It is very common in compiler design, where the abstract syntax tree is transfor The SDK provides different flavors of a transformer: -* :py:class:`~aas_core3_1.types.AbstractTransformer`, where the model element is directly transformed into something, and -* :py:class:`~aas_core3_1.types.AbstractTransformerWithContext`, which propagates the context object along the transformations. +* :py:class:`~aas_core3_2.types.AbstractTransformer`, where the model element is directly transformed into something, and +* :py:class:`~aas_core3_2.types.AbstractTransformerWithContext`, which propagates the context object along the transformations. Usually you implement for each concrete class how it should be transformed. -If you want to specify only a subset of transformations, and provide the default value for the remainder, the SDK provides :py:class:`~aas_core3_1.types.TransformerWithDefault` and :py:class:`~aas_core3_1.types.TransformerWithDefaultAndContext`. +If you want to specify only a subset of transformations, and provide the default value for the remainder, the SDK provides :py:class:`~aas_core3_2.types.TransformerWithDefault` and :py:class:`~aas_core3_2.types.TransformerWithDefaultAndContext`. We deliberately omit an example due to the length of the code. -Please let us know by `creating an issue `__ if you would like to have an example here. +Please let us know by `creating an issue `__ if you would like to have an example here. diff --git a/docs/source/getting_started/jsonize.rst b/docs/source/getting_started/jsonize.rst index 4385ddf..ab6b3db 100644 --- a/docs/source/getting_started/jsonize.rst +++ b/docs/source/getting_started/jsonize.rst @@ -2,12 +2,12 @@ JSON De/serialization ********************* -Our SDK handles the de/serialization of the AAS models from and to JSON format through the module :py:mod:`aas_core3_1.jsonization`. +Our SDK handles the de/serialization of the AAS models from and to JSON format through the module :py:mod:`aas_core3_2.jsonization`. Serialize ========= -To serialize, you call the function :py:func:`aas_core3.jsonization.to_jsonable` on an instance of :py:class:`aas_core3_1.types.Environment` which will convert it to a JSON-able mapping. +To serialize, you call the function :py:func:`aas_core3_2.jsonization.to_jsonable` on an instance of :py:class:`aas_core3_2.types.Environment` which will convert it to a JSON-able mapping. Here is a snippet that converts the environment first into a JSON-able mapping, and next converts the JSON-able mapping to text: @@ -15,8 +15,8 @@ Here is a snippet that converts the environment first into a JSON-able mapping, import json - import aas_core3_1.types as aas_types - import aas_core3_1.jsonization as aas_jsonization + import aas_core3_2.types as aas_types + import aas_core3_2.jsonization as aas_jsonization # Prepare the environment environment = aas_types.Environment( @@ -64,8 +64,8 @@ Expected output: De-serialize ============ -Our SDK can convert a JSON-able mapping back to an instance of :py:class:`aas_core3_1.types.Environment`. -To that end, you call the function :py:func:`aas_core3_1.jsonization.environment_from_jsonable`. +Our SDK can convert a JSON-able mapping back to an instance of :py:class:`aas_core3_2.types.Environment`. +To that end, you call the function :py:func:`aas_core3_2.jsonization.environment_from_jsonable`. Here is an example snippet: @@ -74,7 +74,7 @@ Here is an example snippet: import json - import aas_core3_1.jsonization as aas_jsonization + import aas_core3_2.jsonization as aas_jsonization text = """\ { @@ -106,12 +106,12 @@ Expected output: .. testoutput:: - - + + Errors ====== -If there are any errors during the de-serialization, an :py:class:`aas_core3_1.jsonization.DeserializationException` will be thrown. +If there are any errors during the de-serialization, an :py:class:`aas_core3_2.jsonization.DeserializationException` will be thrown. Errors occur whenever we encounter invalid JSON values. For example, this is the case when the de-serialization function expects a JSON object, but encounters a JSON array instead. diff --git a/docs/source/getting_started/verify.rst b/docs/source/getting_started/verify.rst index 1fd1972..321ebee 100644 --- a/docs/source/getting_started/verify.rst +++ b/docs/source/getting_started/verify.rst @@ -4,16 +4,16 @@ Verify Our SDK allows you to verify that a model satisfies the constraints of the meta-model. -The verification logic is concentrated in the module :py:mod:`aas_core3_1.verification`, and all it takes is a call to :py:func:`aas_core3_1.verification.verify` function. -The function :py:func:`aas_core3_1.verification.verify` will check that constraints in the given model element are satisfied, including the recursion into children elements. -The function returns an iterator of :py:class:`aas_core3_1.verification.Error`'s, which you can use for further processing (*e.g.*, report to the user). +The verification logic is concentrated in the module :py:mod:`aas_core3_2.verification`, and all it takes is a call to :py:func:`aas_core3_2.verification.verify` function. +The function :py:func:`aas_core3_2.verification.verify` will check that constraints in the given model element are satisfied, including the recursion into children elements. +The function returns an iterator of :py:class:`aas_core3_2.verification.Error`'s, which you can use for further processing (*e.g.*, report to the user). Here is a short example snippet: .. testcode:: - import aas_core3_1.types as aas_types - import aas_core3_1.verification as aas_verification + import aas_core3_2.types as aas_types + import aas_core3_2.verification as aas_verification # Prepare the environment environment = aas_types.Environment( @@ -40,12 +40,12 @@ Expected output: .. testoutput:: - .submodels[0].submodel_elements[0].id_short: ID-short of Referables shall only feature letters, digits, hyphen (``-``) and underscore (``_``); starting mandatory with a letter, and not ending with a hyphen, *I.e.* ``^[a-zA-Z][a-zA-Z0-9_-]*[a-zA-Z0-9_]+$``. + .submodels[0].submodel_elements[0].id_short: AASd-002: ID-short of Referables shall consist of at least two characters and shall only feature letters, digits, hyphen (``-``) and underscore (``_``); starting mandatory with a letter, and not ending with a hyphen, *I.e.* ``^[a-zA-Z][a-zA-Z0-9_-]*[a-zA-Z0-9_]+$``. Limit the Number of Reported Errors =================================== -Since the function :py:func:`aas_core3_1.verification.verify` gives you an iterator, you can use :py:mod:`itertools` on it. +Since the function :py:func:`aas_core3_2.verification.verify` gives you an iterator, you can use :py:mod:`itertools` on it. Here is a snippet which reports only the first 10 errors: @@ -70,4 +70,4 @@ Some constraints require external dependencies such as an AAS registry. Verifying the constraints with external dependencies is out-of-scope of our SDK, as we still lack standardized interfaces to those dependencies. However, all the constraints which need no external dependency are verified. -For a full list of exception, please see the description of the module :py:mod:`aas_core3_1.types`. +For a full list of exception, please see the description of the module :py:mod:`aas_core3_2.types`. diff --git a/docs/source/getting_started/xmlize.rst b/docs/source/getting_started/xmlize.rst index 791e26b..67b34d4 100644 --- a/docs/source/getting_started/xmlize.rst +++ b/docs/source/getting_started/xmlize.rst @@ -2,21 +2,21 @@ XML De/serialization ******************** -The code that de/serializes AAS models from and to XML documents lives in the module :py:mod:`aas_core3_1.xmlization`. +The code that de/serializes AAS models from and to XML documents lives in the module :py:mod:`aas_core3_2.xmlization`. Serialize ========= -You serialize the AAS model to XML-encoded text by calling the function :py:func:`aas_core3_1.xmlization.to_str`. +You serialize the AAS model to XML-encoded text by calling the function :py:func:`aas_core3_2.xmlization.to_str`. -If you want the same text to be written incrementally to a :py:class:`typing.TextIO` stream, you can use the function :py:func:`aas_core3_1.xmlization.write`. +If you want the same text to be written incrementally to a :py:class:`typing.TextIO` stream, you can use the function :py:func:`aas_core3_2.xmlization.write`. Here is an example snippet: .. testcode:: - import aas_core3_1.types as aas_types - import aas_core3_1.xmlization as aas_xmlization + import aas_core3_2.types as aas_types + import aas_core3_2.xmlization as aas_xmlization # Prepare the environment environment = aas_types.Environment( @@ -43,7 +43,7 @@ Expected output: .. testoutput:: - some-unique-global-identifiersome_propertyxs:int1984 + some-unique-global-identifiersome_propertyxs:int1984 De-serialize @@ -51,19 +51,19 @@ De-serialize You can de-serialize an environment from XML coming from four different sources by using different functions: -* :py:func:`aas_core3_1.xmlization.environment_from_iterparse`, where a stream coming from :py:func:`xml.etree.ElementTree.iterparse` is expected with ``events`` set to ``["start", "end"]``, -* :py:func:`aas_core3_1.xmlization.environment_from_stream`, which expects a textual stream behaving according to :py:class:`typing.TextIO`, -* :py:func:`aas_core3_1.xmlization.environment_from_file`, which expects a path to the file containing the XML of the environment, or -* :py:func:`aas_core3.xmlization.environment_from_str`, which de-serialized the environment from an XML-encoded string. +* :py:func:`aas_core3_2.xmlization.environment_from_iterparse`, where a stream coming from :py:func:`xml.etree.ElementTree.iterparse` is expected with ``events`` set to ``["start", "end"]``, +* :py:func:`aas_core3_2.xmlization.environment_from_stream`, which expects a textual stream behaving according to :py:class:`typing.TextIO`, +* :py:func:`aas_core3_2.xmlization.environment_from_file`, which expects a path to the file containing the XML of the environment, or +* :py:func:`aas_core3_2.xmlization.environment_from_str`, which de-serialized the environment from an XML-encoded string. -Here is a snippet which parses XML as text and then de-serializes it into an instance of :py:class:`~aas_core3_1.types.Environment`: +Here is a snippet which parses XML as text and then de-serializes it into an instance of :py:class:`~aas_core3_2.types.Environment`: .. testcode:: - import aas_core3_1.xmlization as aas_xmlization + import aas_core3_2.xmlization as aas_xmlization text = ( - "" + + "" + "" + "some-unique-global-identifier" + "someProperty" + @@ -80,18 +80,18 @@ Expected output: .. testoutput:: - - + + You can also de-serialize other model classes other than ``Environment``. -For example, to de-serialize a submodel, you can use :py:func:`aas_core3_1.xmlization.submodel_from_str`: +For example, to de-serialize a submodel, you can use :py:func:`aas_core3_2.xmlization.submodel_from_str`: .. testcode:: - import aas_core3_1.xmlization as aas_xmlization + import aas_core3_2.xmlization as aas_xmlization text = ( - "" + + "" + "some-unique-global-identifier" + "someProperty" + "xs:boolean" + @@ -107,18 +107,18 @@ Expected output: .. testoutput:: - + -If you do not know the model type in advance, you can use the general functions such as :py:func:`aas_core3_1.xmlization.from_str` and :py:func:`aas_core3_1.xmlization.from_file`. +If you do not know the model type in advance, you can use the general functions such as :py:func:`aas_core3_2.xmlization.from_str` and :py:func:`aas_core3_2.xmlization.from_file`. The model type will be determined based on the first start element. The same example above can be thus rewritten: .. testcode:: - import aas_core3_1.xmlization as aas_xmlization + import aas_core3_2.xmlization as aas_xmlization text = ( - "" + + "" + "some-unique-global-identifier" + "someProperty" + "xs:boolean" + @@ -134,15 +134,15 @@ Expected output: .. testoutput:: - + -Prefer the particular de-serialization (:py:func:`aas_core3_1.xmlization.submodel_from_str`) whenever you know the type in advance. +Prefer the particular de-serialization (:py:func:`aas_core3_2.xmlization.submodel_from_str`) whenever you know the type in advance. The particular de-serialization function will check the actual model type for you, and you also get more precise type annotations for your downstream code. Errors ====== -If the XML document comes in an unexpected form, our SDK throws a :py:class:`aas_core3_1.xmlization.DeserializationException`. +If the XML document comes in an unexpected form, our SDK throws a :py:class:`aas_core3_2.xmlization.DeserializationException`. This can happen, for example, if unexpected XML elements or XML attributes are encountered, or an expected XML element is missing. Disregarding XML Attributes @@ -161,14 +161,14 @@ Here is an example snippet: import xml.etree.ElementTree from typing import Tuple, Iterator - import aas_core3_1.xmlization as aas_xmlization + import aas_core3_2.xmlization as aas_xmlization text = ( '\n' '\n' + ' xsi:schemaLocation="https://admin-shell.io/aas/3/2/AAS.xsd">\n' '\n' ) @@ -200,6 +200,6 @@ Here is an example snippet: serialization = aas_xmlization.to_str(environment) assert ( - '' + '' == serialization ) diff --git a/docs/source/index.rst b/docs/source/index.rst index e71362f..8b3c1fc 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,4 +1,4 @@ -Welcome to aas-core3.1's documentation! +Welcome to aas-core3.2's documentation! ================================================== Table of Contents diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst index cf715d3..dfe99fd 100644 --- a/docs/source/introduction.rst +++ b/docs/source/introduction.rst @@ -8,9 +8,9 @@ This is a software development kit (SDK) to: * verify, and * de/serialize to and from JSON and XML -... Asset Administration Shells based on `the version 3.1 of the meta-model`_. +... Asset Administration Shells based on `the version 3.2 of the meta-model`_. -.. _the version 3.1 of the meta-model: https://industrialdigitaltwin.org/content-hub/aasspecifications +.. _the version 3.2 of the meta-model: https://industrialdigitaltwin.org/content-hub/aasspecifications For a brief introduction, see :doc:`Getting Started `. diff --git a/pyproject.toml b/pyproject.toml index 6ddb14d..b848acf 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -28,6 +28,7 @@ classifiers = [ [project.urls] Homepage = "https://github.com/eclipse-aascw/aas-core3.2-python" +Documentation = "https://eclipse-aascw.github.io/aas-core3.2-python/" Repository = "https://github.com/eclipse-aascw/aas-core3.2-python" Issues = "https://github.com/eclipse-aascw/aas-core3.2-python/issues"