Merge pull request #12 from rwth-iat/main

merge `main` in `feature/http_api`

README.md

@@ -131,8 +131,7 @@ from basyx.aas.adapter.xml import write_aas_xml_file
 
 data: model.DictObjectStore[model.Identifiable] = model.DictObjectStore()
 data.add(submodel)
-with open('Simple_Submodel.xml', 'wb') as f:
- write_aas_xml_file(file=f, data=data)
+write_aas_xml_file(file='Simple_Submodel.xml', data=data)
 ```
 
 

basyx/aas/adapter/_generic.py

@@ -8,10 +8,17 @@
 The dicts defined in this module are used in the json and xml modules to translate enum members of our
 implementation to the respective string and vice versa.
 """
-from typing import Dict, Type
+import os
+from typing import BinaryIO, Dict, IO, Type, Union
 
 from basyx.aas import model
 
+# type aliases for path-like objects and IO
+# used by write_aas_xml_file, read_aas_xml_file, write_aas_json_file, read_aas_json_file
+Path = Union[str, bytes, os.PathLike]
+PathOrBinaryIO = Union[Path, BinaryIO]
+PathOrIO = Union[Path, IO] # IO is TextIO or BinaryIO
+
 # XML Namespace definition
 XML_NS_MAP = {"aas": "https://admin-shell.io/aas/3/0"}
 XML_NS_AAS = "{" + XML_NS_MAP["aas"] + "}"

basyx/aas/adapter/aasx.py

@@ -285,9 +285,11 @@ class AASXWriter:
  file_store)
  writer.write_core_properties(cp)
 
- **Attention:** The AASXWriter must always be closed using the :meth:`~.AASXWriter.close` method or its context
- manager functionality (as shown above). Otherwise the resulting AASX file will lack important data structures
- and will not be readable.
+ .. attention::
+
+ The AASXWriter must always be closed using the :meth:`~.AASXWriter.close` method or its context manager
+ functionality (as shown above). Otherwise, the resulting AASX file will lack important data structures
+ and will not be readable.
  """
  AASX_ORIGIN_PART_NAME = "/aasx/aasx-origin"
 

basyx/aas/adapter/json/json_deserialization.py

@@ -30,15 +30,16 @@
 Other embedded objects are converted using a number of helper constructor methods.
 """
 import base64
+import contextlib
 import json
 import logging
 import pprint
-from typing import Dict, Callable, TypeVar, Type, List, IO, Optional, Set
+from typing import Dict, Callable, ContextManager, TypeVar, Type, List, IO, Optional, Set, get_args
 
 from basyx.aas import model
 from .._generic import MODELLING_KIND_INVERSE, ASSET_KIND_INVERSE, KEY_TYPES_INVERSE, ENTITY_TYPES_INVERSE, \
  IEC61360_DATA_TYPES_INVERSE, IEC61360_LEVEL_TYPES_INVERSE, KEY_TYPES_CLASSES_INVERSE, REFERENCE_TYPES_INVERSE, \
- DIRECTION_INVERSE, STATE_OF_EVENT_INVERSE, QUALIFIER_KIND_INVERSE
+ DIRECTION_INVERSE, STATE_OF_EVENT_INVERSE, QUALIFIER_KIND_INVERSE, PathOrIO, Path
 
 logger = logging.getLogger(__name__)
 
@@ -794,7 +795,7 @@ def _select_decoder(failsafe: bool, stripped: bool, decoder: Optional[Type[AASFr
  return StrictAASFromJsonDecoder
 
 
-def read_aas_json_file_into(object_store: model.AbstractObjectStore, file: IO, replace_existing: bool = False,
+def read_aas_json_file_into(object_store: model.AbstractObjectStore, file: PathOrIO, replace_existing: bool = False,
  ignore_existing: bool = False, failsafe: bool = True, stripped: bool = False,
  decoder: Optional[Type[AASFromJsonDecoder]] = None) -> Set[model.Identifier]:
  """
@@ -803,7 +804,7 @@ def read_aas_json_file_into(object_store: model.AbstractObjectStore, file: IO, r
 
  :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 file: A filename or 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``.
@@ -814,13 +815,31 @@ def read_aas_json_file_into(object_store: model.AbstractObjectStore, file: IO, r
  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
+ :raises KeyError: **Non-failsafe**: Encountered a duplicate identifier
+ :raises KeyError: Encountered an identifier that already exists in the given ``object_store`` with both
+ ``replace_existing`` and ``ignore_existing`` set to ``False``
+ :raises (~basyx.aas.model.base.AASConstraintViolation, KeyError, ValueError, TypeError): **Non-failsafe**:
+ Errors during construction of the objects
+ :raises TypeError: **Non-failsafe**: Encountered an element in the wrong list
+ (e.g. an AssetAdministrationShell in ``submodels``)
  :return: A set of :class:`Identifiers <basyx.aas.model.base.Identifier>` that were added to object_store
  """
  ret: Set[model.Identifier] = set()
  decoder_ = _select_decoder(failsafe, stripped, decoder)
 
+ # json.load() accepts TextIO and BinaryIO
+ cm: ContextManager[IO]
+ if isinstance(file, get_args(Path)):
+ # 'file' is a path, needs to be opened first
+ cm = open(file, "r", encoding="utf-8-sig")
+ else:
+ # 'file' is not a path, thus it must already be IO
+ # mypy seems to have issues narrowing the type due to get_args()
+ cm = contextlib.nullcontext(file) # type: ignore[arg-type]
+
  # read, parse and convert JSON file
- data = json.load(file, cls=decoder_)
+ with cm as fp:
+ data = json.load(fp, cls=decoder_)
 
  for name, expected_type in (('assetAdministrationShells', model.AssetAdministrationShell),
  ('submodels', model.Submodel),
@@ -864,14 +883,19 @@ def read_aas_json_file_into(object_store: model.AbstractObjectStore, file: IO, r
  return ret
 
 
-def read_aas_json_file(file: IO, **kwargs) -> model.DictObjectStore[model.Identifiable]:
+def read_aas_json_file(file: PathOrIO, **kwargs) -> model.DictObjectStore[model.Identifiable]:
  """
  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:`read_aas_json_file_into`
+ :raises KeyError: **Non-failsafe**: Encountered a duplicate identifier
+ :raises (~basyx.aas.model.base.AASConstraintViolation, KeyError, ValueError, TypeError): **Non-failsafe**:
+ Errors during construction of the objects
+ :raises TypeError: **Non-failsafe**: Encountered an element in the wrong list
+ (e.g. an AssetAdministrationShell in ``submodels``)
  :return: A :class:`~basyx.aas.model.provider.DictObjectStore` containing all AAS objects from the JSON file
  """
  object_store: model.DictObjectStore[model.Identifiable] = model.DictObjectStore()

basyx/aas/adapter/json/json_serialization.py

@@ -27,8 +27,10 @@
 conversion functions to handle all the attributes of abstract base classes.
 """
 import base64
+import contextlib
 import inspect
-from typing import List, Dict, IO, Optional, Type, Callable
+import io
+from typing import ContextManager, List, Dict, Optional, TextIO, Type, Callable, get_args
 import json
 
 from basyx.aas import model
@@ -732,13 +734,21 @@ def object_store_to_json(data: model.AbstractObjectStore, stripped: bool = False
  return json.dumps(_create_dict(data), cls=encoder_, **kwargs)
 
 
-def write_aas_json_file(file: IO, data: model.AbstractObjectStore, stripped: bool = False,
+class _DetachingTextIOWrapper(io.TextIOWrapper):
+ """
+ Like :class:`io.TextIOWrapper`, but detaches on context exit instead of closing the wrapped buffer.
+ """
+ def __exit__(self, exc_type, exc_val, exc_tb):
+ self.detach()
+
+
+def write_aas_json_file(file: _generic.PathOrIO, data: model.AbstractObjectStore, stripped: bool = False,
  encoder: Optional[Type[AASToJsonEncoder]] = None, **kwargs) -> None:
  """
  Write a set of AAS objects to an Asset Administration Shell JSON file according to 'Details of the Asset
  Administration Shell', chapter 5.5
 
- :param file: A file-like object to write the JSON-serialized data to
+ :param file: A filename or file-like object to write the JSON-serialized data to
  :param data: :class:`ObjectStore <basyx.aas.model.provider.AbstractObjectStore>` which contains different objects of
  the AAS meta model which should be serialized to a JSON file
  :param stripped: If `True`, objects are serialized to stripped json objects.
@@ -748,5 +758,21 @@ def write_aas_json_file(file: IO, data: model.AbstractObjectStore, stripped: boo
  :param kwargs: Additional keyword arguments to be passed to `json.dump()`
  """
  encoder_ = _select_encoder(stripped, encoder)
+
+ # json.dump() only accepts TextIO
+ cm: ContextManager[TextIO]
+ if isinstance(file, get_args(_generic.Path)):
+ # 'file' is a path, needs to be opened first
+ cm = open(file, "w", encoding="utf-8")
+ elif not hasattr(file, "encoding"):
+ # only TextIO has this attribute, so this must be BinaryIO, which needs to be wrapped
+ # mypy seems to have issues narrowing the type due to get_args()
+ cm = _DetachingTextIOWrapper(file, "utf-8", write_through=True) # type: ignore[arg-type]
+ else:
+ # we already got TextIO, nothing needs to be done
+ # mypy seems to have issues narrowing the type due to get_args()
+ cm = contextlib.nullcontext(file) # type: ignore[arg-type]
+
  # serialize object to json
- json.dump(_create_dict(data), file, cls=encoder_, **kwargs)
+ with cm as fp:
+ json.dump(_create_dict(data), fp, cls=encoder_, **kwargs)

basyx/aas/adapter/xml/__init__.py

@@ -11,7 +11,8 @@
 """
 import os.path
 
-from .xml_serialization import write_aas_xml_file
+from .xml_serialization import object_store_to_xml_element, write_aas_xml_file, object_to_xml_element, \
+ write_aas_xml_element
 from .xml_deserialization import AASFromXmlDecoder, StrictAASFromXmlDecoder, StrippedAASFromXmlDecoder, \
  StrictStrippedAASFromXmlDecoder, XMLConstructables, read_aas_xml_file, read_aas_xml_file_into, read_aas_xml_element
 

basyx/aas/adapter/xml/xml_deserialization.py

@@ -47,10 +47,10 @@
 import base64
 import enum
 
-from typing import Any, Callable, Dict, IO, Iterable, Optional, Set, Tuple, Type, TypeVar
+from typing import Any, Callable, Dict, Iterable, Optional, Set, Tuple, Type, TypeVar
 from .._generic import XML_NS_MAP, XML_NS_AAS, MODELLING_KIND_INVERSE, ASSET_KIND_INVERSE, KEY_TYPES_INVERSE, \
  ENTITY_TYPES_INVERSE, IEC61360_DATA_TYPES_INVERSE, IEC61360_LEVEL_TYPES_INVERSE, KEY_TYPES_CLASSES_INVERSE, \
- REFERENCE_TYPES_INVERSE, DIRECTION_INVERSE, STATE_OF_EVENT_INVERSE, QUALIFIER_KIND_INVERSE
+ REFERENCE_TYPES_INVERSE, DIRECTION_INVERSE, STATE_OF_EVENT_INVERSE, QUALIFIER_KIND_INVERSE, PathOrIO
 
 NS_AAS = XML_NS_AAS
 REQUIRED_NAMESPACES: Set[str] = {XML_NS_MAP["aas"]}
@@ -315,8 +315,8 @@ def _failsafe_construct_mandatory(element: etree.Element, constructor: Callable[
  """
  constructed = _failsafe_construct(element, constructor, False, **kwargs)
  if constructed is None:
- raise TypeError("The result of a non-failsafe _failsafe_construct() call was None! "
- "This is a bug in the Eclipse BaSyx Python SDK XML deserialization, please report it!")
+ raise AssertionError("The result of a non-failsafe _failsafe_construct() call was None! "
+  "This is a bug in the Eclipse BaSyx Python SDK XML deserialization, please report it!")
  return constructed
 
 
@@ -1186,14 +1186,16 @@ class StrictStrippedAASFromXmlDecoder(StrictAASFromXmlDecoder, StrippedAASFromXm
  pass
 
 
-def _parse_xml_document(file: IO, failsafe: bool = True, **parser_kwargs: Any) -> Optional[etree.Element]:
+def _parse_xml_document(file: PathOrIO, failsafe: bool = True, **parser_kwargs: Any) -> Optional[etree.Element]:
  """
  Parse an XML document into an element tree
 
  :param file: A filename or file-like object to read the XML-serialized data from
  :param failsafe: If True, the file is parsed in a failsafe way: Instead of raising an Exception if the document
  is malformed, parsing is aborted, an error is logged and None is returned
  :param parser_kwargs: Keyword arguments passed to the XMLParser constructor
+ :raises ~lxml.etree.XMLSyntaxError: **Non-failsafe**: If the given file(-handle) has invalid XML
+ :raises KeyError: **Non-failsafe**: If a required namespace has not been declared on the XML document
  :return: The root element of the element tree
  """
 
@@ -1249,7 +1251,7 @@ class XMLConstructables(enum.Enum):
  KEY = enum.auto()
  REFERENCE = enum.auto()
  MODEL_REFERENCE = enum.auto()
- GLOBAL_REFERENCE = enum.auto()
+ EXTERNAL_REFERENCE = enum.auto()
  ADMINISTRATIVE_INFORMATION = enum.auto()
  QUALIFIER = enum.auto()
  SECURITY = enum.auto()
@@ -1289,11 +1291,11 @@ class XMLConstructables(enum.Enum):
  DATA_SPECIFICATION_IEC61360 = enum.auto()
 
 
-def read_aas_xml_element(file: IO, construct: XMLConstructables, failsafe: bool = True, stripped: bool = False,
+def read_aas_xml_element(file: PathOrIO, construct: XMLConstructables, failsafe: bool = True, stripped: bool = False,
  decoder: Optional[Type[AASFromXmlDecoder]] = None, **constructor_kwargs) -> Optional[object]:
  """
  Construct a single object from an XML string. The namespaces have to be declared on the object itself, since there
- is no surrounding aasenv element.
+ is no surrounding environment element.
 
  :param file: A filename or file-like object to read the XML-serialized data from
  :param construct: A member of the enum :class:`~.XMLConstructables`, specifying which type to construct.
@@ -1305,6 +1307,10 @@ def read_aas_xml_element(file: IO, construct: XMLConstructables, failsafe: bool
  This parameter is ignored if a decoder class is specified.
  :param decoder: The decoder class used to decode the XML elements
  :param constructor_kwargs: Keyword arguments passed to the constructor function
+ :raises ~lxml.etree.XMLSyntaxError: **Non-failsafe**: If the given file(-handle) has invalid XML
+ :raises KeyError: **Non-failsafe**: If a required namespace has not been declared on the XML document
+ :raises (~basyx.aas.model.base.AASConstraintViolation, KeyError, ValueError): **Non-failsafe**: Errors during
+ construction of the objects
  :return: The constructed object or None, if an error occurred in failsafe mode.
  """
  decoder_ = _select_decoder(failsafe, stripped, decoder)
@@ -1316,7 +1322,7 @@ def read_aas_xml_element(file: IO, construct: XMLConstructables, failsafe: bool
  constructor = decoder_.construct_reference
  elif construct == XMLConstructables.MODEL_REFERENCE:
  constructor = decoder_.construct_model_reference
- elif construct == XMLConstructables.GLOBAL_REFERENCE:
+ elif construct == XMLConstructables.EXTERNAL_REFERENCE:
  constructor = decoder_.construct_external_reference
  elif construct == XMLConstructables.ADMINISTRATIVE_INFORMATION:
  constructor = decoder_.construct_administrative_information
@@ -1397,7 +1403,7 @@ def read_aas_xml_element(file: IO, construct: XMLConstructables, failsafe: bool
  return _failsafe_construct(element, constructor, decoder_.failsafe, **constructor_kwargs)
 
 
-def read_aas_xml_file_into(object_store: model.AbstractObjectStore[model.Identifiable], file: IO,
+def read_aas_xml_file_into(object_store: model.AbstractObjectStore[model.Identifiable], file: PathOrIO,
  replace_existing: bool = False, ignore_existing: bool = False, failsafe: bool = True,
  stripped: bool = False, decoder: Optional[Type[AASFromXmlDecoder]] = None,
  **parser_kwargs: Any) -> Set[model.Identifier]:
@@ -1419,6 +1425,14 @@ def read_aas_xml_file_into(object_store: model.AbstractObjectStore[model.Identif
  This parameter is ignored if a decoder class is specified.
  :param decoder: The decoder class used to decode the XML elements
  :param parser_kwargs: Keyword arguments passed to the XMLParser constructor
+ :raises ~lxml.etree.XMLSyntaxError: **Non-failsafe**: If the given file(-handle) has invalid XML
+ :raises KeyError: **Non-failsafe**: If a required namespace has not been declared on the XML document
+ :raises KeyError: **Non-failsafe**: Encountered a duplicate identifier
+ :raises KeyError: Encountered an identifier that already exists in the given ``object_store`` with both
+ ``replace_existing`` and ``ignore_existing`` set to ``False``
+ :raises (~basyx.aas.model.base.AASConstraintViolation, KeyError, ValueError): **Non-failsafe**: Errors during
+ construction of the objects
+ :raises TypeError: **Non-failsafe**: Encountered an undefined top-level list (e.g. ``<aas:submodels1>``)
  :return: A set of :class:`Identifiers <basyx.aas.model.base.Identifier>` that were added to object_store
  """
  ret: Set[model.Identifier] = set()
@@ -1470,14 +1484,20 @@ def read_aas_xml_file_into(object_store: model.AbstractObjectStore[model.Identif
  return ret
 
 
-def read_aas_xml_file(file: IO, **kwargs: Any) -> model.DictObjectStore[model.Identifiable]:
+def read_aas_xml_file(file: PathOrIO, **kwargs: Any) -> model.DictObjectStore[model.Identifiable]:
  """
  A wrapper of :meth:`~basyx.aas.adapter.xml.xml_deserialization.read_aas_xml_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.xml.xml_deserialization.read_aas_xml_file_into`.
 
  :param file: A filename or file-like object to read the XML-serialized data from
  :param kwargs: Keyword arguments passed to :meth:`~basyx.aas.adapter.xml.xml_deserialization.read_aas_xml_file_into`
+ :raises ~lxml.etree.XMLSyntaxError: **Non-failsafe**: If the given file(-handle) has invalid XML
+ :raises KeyError: **Non-failsafe**: If a required namespace has not been declared on the XML document
+ :raises KeyError: **Non-failsafe**: Encountered a duplicate identifier
+ :raises (~basyx.aas.model.base.AASConstraintViolation, KeyError, ValueError): **Non-failsafe**: Errors during
+ construction of the objects
+ :raises TypeError: **Non-failsafe**: Encountered an undefined top-level list (e.g. ``<aas:submodels1>``)
  :return: A :class:`~basyx.aas.model.provider.DictObjectStore` containing all AAS objects from the XML file
  """
  object_store: model.DictObjectStore[model.Identifiable] = model.DictObjectStore()