massive docstring overhaul

This fixes missing references, improves the layout, removes outdated
information in some places, and more.

basyx/aas/adapter/json/__init__.py

@@ -4,16 +4,17 @@
 This package contains functionality for serialization and deserialization of BaSyx Python SDK objects into/from JSON.
 
 :ref:`json_serialization <adapter.json.json_serialization>`: The module offers a function to write an ObjectStore to a
-given file and therefore defines the custom JSONEncoder :class:`~.aas.adapter.json.json_serialization.AASToJsonEncoder`
-which handles encoding of all BaSyx Python SDK objects and their attributes by converting them into standard python
-objects.
+given file and therefore defines the custom JSONEncoder
+:class:`~basyx.aas.adapter.json.json_serialization.AASToJsonEncoder` which handles encoding of all BaSyx Python SDK
+objects and their attributes by converting them into standard python objects.
 
 :ref:`json_deserialization <adapter.json.json_deserialization>`: The module implements custom JSONDecoder classes
-:class:`~aas.adapter.json.json_deserialization.AASFromJsonDecoder` and
-:class:`~aas.adapter.json.json_deserialization.StrictAASFromJsonDecoder`, that — when used with Python's `json`
-module — detect AAS objects in the parsed JSON and convert them into the corresponding BaSyx Python SDK object.
-A function :meth:`~aas.adapter.json.json_deserialization.read_aas_json_file` is provided to read all AAS objects
-within a JSON file and return them as BaSyx Python SDK objectstore.
+:class:`~basyx.aas.adapter.json.json_deserialization.AASFromJsonDecoder` and
+:class:`~basyx.aas.adapter.json.json_deserialization.StrictAASFromJsonDecoder`, that — when used with Python's
+:mod:`json` module — detect AAS objects in the parsed JSON and convert them into the corresponding BaSyx Python SDK
+object. A function :meth:`~basyx.aas.adapter.json.json_deserialization.read_aas_json_file` is provided to read all
+AAS objects within a JSON file and return them as BaSyx Python SDK
+:class:`ObjectStore <basyx.aas.model.provider.AbstractObjectStore>`.
 """
 import os.path
 

basyx/aas/adapter/json/json_deserialization.py

@@ -10,24 +10,24 @@
 Module for deserializing Asset Administration Shell data from the official JSON format
 
 The module provides custom JSONDecoder classes :class:`~.AASFromJsonDecoder` and :class:`~.StrictAASFromJsonDecoder` to
-be used with the Python standard `json` module.
-
-Furthermore it provides two classes :class:`~aas.adapter.json.json_deserialization.StrippedAASFromJsonDecoder` and
-:class:`~aas.adapter.json.json_deserialization.StrictStrippedAASFromJsonDecoder` for parsing stripped JSON objects,
-which are used in the http adapter (see https://git.rwth-aachen.de/acplt/pyi40aas/-/issues/91).
-The classes contain a custom :meth:`~aas.adapter.json.json_deserialization.AASFromJsonDecoder.object_hook` function
-to detect encoded AAS objects within the JSON data and convert them to BaSyx Python SDK objects while parsing.
-Additionally, there's the :meth:`~aas.adapter.json.json_deserialization.read_aas_json_file_into` function, that takes a
-complete AAS JSON file, reads its contents and stores the objects in the provided
-:class:`~aas.model.provider.AbstractObjectStore`. :meth:`~aas.adapter.json.json_deserialization.read_aas_json_file` is
-a wrapper for this function. Instead of storing the objects in a given :class:`~aas.model.provider.AbstractObjectStore`,
+be used with the Python standard :mod:`json` module.
+
+Furthermore it provides two classes :class:`~basyx.aas.adapter.json.json_deserialization.StrippedAASFromJsonDecoder` and
+:class:`~basyx.aas.adapter.json.json_deserialization.StrictStrippedAASFromJsonDecoder` for parsing stripped
+JSON objects, which are used in the http adapter (see https://git.rwth-aachen.de/acplt/pyi40aas/-/issues/91).
+The classes contain a custom :meth:`~basyx.aas.adapter.json.json_deserialization.AASFromJsonDecoder.object_hook`
+function to detect encoded AAS objects within the JSON data and convert them to BaSyx Python SDK objects while parsing.
+Additionally, there's the :meth:`~basyx.aas.adapter.json.json_deserialization.read_aas_json_file_into` function, that
+takes a complete AAS JSON file, reads its contents and stores the objects in the provided
+:class:`~basyx.aas.model.provider.AbstractObjectStore`. :meth:`read_aas_json_file` is a wrapper for this function.
+Instead of storing the objects in a given :class:`~basyx.aas.model.provider.AbstractObjectStore`,
 it returns a :class:`~basyx.aas.model.provider.DictObjectStore` containing parsed objects.
 
-The deserialization is performed in a bottom-up approach: The `object_hook()` method gets called for every parsed JSON
-object (as dict) and checks for existence of the `modelType` attribute. If it is present, the `AAS_CLASS_PARSERS` dict
-defines, which of the constructor methods of the class is to be used for converting the dict into an object. Embedded
-objects that should have a `modelType` themselves are expected to be converted already. Other embedded objects are
-converted using a number of helper constructor methods.
+The deserialization is performed in a bottom-up approach: The ``object_hook()`` method gets called for every parsed JSON
+object (as dict) and checks for existence of the ``modelType`` attribute. If it is present, the ``AAS_CLASS_PARSERS``
+dict defines, which of the constructor methods of the class is to be used for converting the dict into an object.
+Embedded objects that should have a ``modelType`` themselves are expected to be converted already.
+Other embedded objects are converted using a number of helper constructor methods.
 """
 import base64
 import json
@@ -101,7 +101,7 @@ def _expect_type(object_: object, type_: Type, context: str, failsafe: bool) ->
 
 class AASFromJsonDecoder(json.JSONDecoder):
     """
-    Custom JSONDecoder class to use the `json` module for deserializing Asset Administration Shell data from the
+    Custom JSONDecoder class to use the :mod:`json` module for deserializing Asset Administration Shell data from the
     official JSON format
 
     The class contains a custom :meth:`~.AASFromJsonDecoder.object_hook` function to detect encoded AAS objects within
@@ -113,17 +113,17 @@ class AASFromJsonDecoder(json.JSONDecoder):
 
         data = json.loads(json_string, cls=AASFromJsonDecoder)
 
-    The `object_hook` function uses a set of `_construct_*()` methods, one for each
+    The ``object_hook`` function uses a set of ``_construct_*()`` methods, one for each
     AAS object type to transform the JSON objects in to BaSyx Python SDK objects. These constructor methods are divided
-    into two parts: "Helper Constructor Methods", that are used to construct AAS object types without a `modelType`
+    into two parts: "Helper Constructor Methods", that are used to construct AAS object types without a ``modelType``
     attribute as embedded objects within other AAS objects, and "Direct Constructor Methods" for AAS object types *with*
-    `modelType` attribute. The former are called from other constructor methods or utility methods based on the expected
-    type of an attribute, the latter are called directly from the `object_hook()` function based on the `modelType`
-    attribute.
+    ``modelType`` attribute. The former are called from other constructor methods or utility methods based on the
+    expected type of an attribute, the latter are called directly from the ``object_hook()`` function based on the
+    ``modelType`` attribute.
 
     This class may be subclassed to override some of the constructor functions, e.g. to construct objects of specialized
-    subclasses of the BaSyx Python SDK object classes instead of these normal classes from the `model` package. To
-    simplify this tasks, (nearly) all the constructor methods take a parameter `object_type` defaulting to the normal
+    subclasses of the BaSyx Python SDK object classes instead of these normal classes from the ``model`` package. To
+    simplify this tasks, (nearly) all the constructor methods take a parameter ``object_type`` defaulting to the normal
     BaSyx Python SDK object class, that can be overridden in a derived function:
 
     .. code-block:: python
@@ -139,11 +139,11 @@ def _construct_submodel(cls, dct, object_class=EnhancedSubmodel):
                 return super()._construct_submodel(dct, object_class=object_class)
 
 
-    :cvar failsafe: If `True` (the default), don't raise Exceptions for missing attributes and wrong types, but instead
-                    skip defective objects and use logger to output warnings. Use StrictAASFromJsonDecoder for a
+    :cvar failsafe: If ``True`` (the default), don't raise Exceptions for missing attributes and wrong types, but
+                    instead skip defective objects and use logger to output warnings. Use StrictAASFromJsonDecoder for a
                     non-failsafe version.
-    :cvar stripped: If `True`, the JSON objects will be parsed in a stripped manner, excluding some attributes.
-                    Defaults to `False`.
+    :cvar stripped: If ``True``, the JSON objects will be parsed in a stripped manner, excluding some attributes.
+                    Defaults to ``False``.
                     See https://git.rwth-aachen.de/acplt/pyi40aas/-/issues/91
     """
     failsafe = True
@@ -160,10 +160,10 @@ def object_hook(cls, dct: Dict[str, object]) -> object:
             return dct
 
         # The following dict specifies a constructor method for all AAS classes that may be identified using the
-        # `modelType` attribute in their JSON representation. Each of those constructor functions takes the JSON
+        # ``modelType`` attribute in their JSON representation. Each of those constructor functions takes the JSON
         # representation of an object and tries to construct a Python object from it. Embedded objects that have a
         # modelType themselves are expected to be converted to the correct PythonType already. Additionally, each
-        # function takes a bool parameter `failsafe`, which indicates weather to log errors and skip defective objects
+        # function takes a bool parameter ``failsafe``, which indicates weather to log errors and skip defective objects
         # instead of raising an Exception.
         AAS_CLASS_PARSERS: Dict[str, Callable[[Dict[str, object]], object]] = {
             'AssetAdministrationShell': cls._construct_asset_administration_shell,
@@ -281,7 +281,7 @@ def _get_kind(cls, dct: Dict[str, object]) -> model.ModellingKind:
         Utility method to get the kind of an HasKind object from its JSON representation.
 
         :param dct: The object's dict representation from JSON
-        :return: The object's `kind` value
+        :return: The object's ``kind`` value
         """
         return MODELLING_KIND_INVERSE[_get_ts(dct, "kind", str)] if 'kind' in dct else model.ModellingKind.INSTANCE
 
@@ -366,8 +366,8 @@ def _construct_administrative_information(
     @classmethod
     def _construct_operation_variable(cls, dct: Dict[str, object]) -> model.SubmodelElement:
         """
-        Since we don't implement `OperationVariable`, this constructor discards the wrapping `OperationVariable` object
-        and just returns the contained :class:`~basyx.aas.model.submodel.SubmodelElement`.
+        Since we don't implement ``OperationVariable``, this constructor discards the wrapping ``OperationVariable``
+        object and just returns the contained :class:`~basyx.aas.model.submodel.SubmodelElement`.
         """
         # TODO: remove the following type: ignore comments when mypy supports abstract types for Type[T]
         # see https://github.com/python/mypy/issues/5374
@@ -750,7 +750,7 @@ class StrictAASFromJsonDecoder(AASFromJsonDecoder):
     A strict version of the AASFromJsonDecoder class for deserializing Asset Administration Shell data from the
     official JSON format
 
-    This version has set `failsafe = False`, which will lead to Exceptions raised for every missing attribute or wrong
+    This version has set ``failsafe = False``, which will lead to Exceptions raised for every missing attribute or wrong
     object type.
     """
     failsafe = False
@@ -776,8 +776,8 @@ def _select_decoder(failsafe: bool, stripped: bool, decoder: Optional[Type[AASFr
     Returns the correct decoder based on the parameters failsafe and stripped. If a decoder class is given, failsafe
     and stripped are ignored.
 
-    :param failsafe: If `True`, a failsafe decoder is selected. Ignored if a decoder class is specified.
-    :param stripped: If `True`, a decoder for parsing stripped JSON objects is selected. Ignored if a decoder class is
+    :param failsafe: If ``True``, a failsafe decoder is selected. Ignored if a decoder class is specified.
+    :param stripped: If ``True``, a decoder for parsing stripped JSON objects is selected. Ignored if a decoder class is
                      specified.
     :param decoder: Is returned, if specified.
     :return: An :class:`~.AASFromJsonDecoder` (sub)class.
@@ -801,16 +801,16 @@ def read_aas_json_file_into(object_store: model.AbstractObjectStore, file: IO, r
     Read an Asset Administration Shell JSON file according to 'Details of the Asset Administration Shell', chapter 5.5
     into a given object store.
 
-    :param object_store: The :class:`ObjectStore <aas.model.provider.AbstractObjectStore>` in which the identifiable
-                         objects should be stored
+    :param object_store: The :class:`ObjectStore <basyx.aas.model.provider.AbstractObjectStore>` in which the
+                         identifiable objects should be stored
     :param file: A file-like object to read the JSON-serialized data from
     :param replace_existing: Whether to replace existing objects with the same identifier in the object store or not
     :param ignore_existing: Whether to ignore existing objects (e.g. log a message) or raise an error.
-                            This parameter is ignored if replace_existing is `True`.
-    :param failsafe: If `True`, the document is parsed in a failsafe way: Missing attributes and elements are logged
+                            This parameter is ignored if replace_existing is ``True``.
+    :param failsafe: If ``True``, the document is parsed in a failsafe way: Missing attributes and elements are logged
                      instead of causing exceptions. Defect objects are skipped.
                      This parameter is ignored if a decoder class is specified.
-    :param stripped: If `True`, stripped JSON objects are parsed.
+    :param stripped: If ``True``, stripped JSON objects are parsed.
                      See https://git.rwth-aachen.de/acplt/pyi40aas/-/issues/91
                      This parameter is ignored if a decoder class is specified.
     :param decoder: The decoder class used to decode the JSON objects
@@ -866,12 +866,12 @@ def read_aas_json_file_into(object_store: model.AbstractObjectStore, file: IO, r
 
 def read_aas_json_file(file: IO, **kwargs) -> model.DictObjectStore[model.Identifiable]:
     """
-    A wrapper of :meth:`~aas.adapter.json.json_deserialization.read_aas_json_file_into`, that reads all objects in an
-    empty :class:`~basyx.aas.model.provider.DictObjectStore`. This function supports the same keyword arguments as
-    :meth:`~aas.adapter.json.json_deserialization.read_aas_json_file_into`.
+    A wrapper of :meth:`~basyx.aas.adapter.json.json_deserialization.read_aas_json_file_into`, that reads all objects
+    in an empty :class:`~basyx.aas.model.provider.DictObjectStore`. This function supports the same keyword arguments as
+    :meth:`~basyx.aas.adapter.json.json_deserialization.read_aas_json_file_into`.
 
     :param file: A filename or file-like object to read the JSON-serialized data from
-    :param kwargs: Keyword arguments passed to :meth:`~aas.adapter.json.json_deserialization.read_aas_json_file_into`
+    :param kwargs: Keyword arguments passed to :meth:`read_aas_json_file_into`
     :return: A :class:`~basyx.aas.model.provider.DictObjectStore` containing all AAS objects from the JSON file
     """
     object_store: model.DictObjectStore[model.Identifiable] = model.DictObjectStore()