adapter.{json,xml}: improve docstrings

basyx/aas/adapter/json/json_deserialization.py

@@ -815,6 +815,13 @@ def read_aas_json_file_into(object_store: model.AbstractObjectStore, file: PathO
  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()
@@ -884,6 +891,11 @@ def read_aas_json_file(file: PathOrIO, **kwargs) -> model.DictObjectStore[model.
 
  :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/xml/xml_deserialization.py

@@ -1194,6 +1194,8 @@ def _parse_xml_document(file: PathOrIO, failsafe: bool = True, **parser_kwargs:
  :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
  """
 
@@ -1293,7 +1295,7 @@ def read_aas_xml_element(file: PathOrIO, construct: XMLConstructables, failsafe:
  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: PathOrIO, construct: XMLConstructables, failsafe:
  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)
@@ -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()
@@ -1478,6 +1492,12 @@ def read_aas_xml_file(file: PathOrIO, **kwargs: Any) -> model.DictObjectStore[mo
 
  :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()