3.2. adapter.xml - XML serialization and deserialization

This package contains functionality for serialization and deserialization of BaSyx Python SDK objects into/from XML.

xml_serialization: The module offers a function to write an ObjectStore to a given file.

xml_deserialization: The module offers a function to create an ObjectStore from a given xml document.

3.2.1. adapter.xml.xml_serialization - Serialization from AAS-objects to XML

Module for serializing Asset Administration Shell data to the official XML format

How to use:

  • For generating an XML-File from a AbstractObjectStore, check out the function write_aas_xml_file().

  • For serializing any object to an XML fragment, that fits the XML specification from ‘Details of the Asset Administration Shell’, chapter 5.4, check out <your_object_class_name_here>_to_xml(). These functions return an xml.etree.ElementTree.Element object to be serialized into XML.

basyx.aas.adapter.xml.xml_serialization.write_aas_xml_file(file: IO, data: basyx.aas.model.provider.AbstractObjectStore, **kwargs) → None

Write a set of AAS objects to an Asset Administration Shell XML file according to ‘Details of the Asset Administration Shell’, chapter 5.4

Parameters

  • file – A file-like object to write the XML-serialized data to

  • data – ObjectStore which contains different objects of the AAS meta model which should be serialized to an XML file

  • kwargs – Additional keyword arguments to be passed to tree.write()

3.2.2. adapter.xml.xml_deserialization - Deserialization from XML to AAS-objects

Module for deserializing Asset Administration Shell data from the official XML format

This module provides the following functions for parsing XML documents:

  • read_aas_xml_element() constructs a single object from an XML document containing a single element

  • read_aas_xml_file_into() constructs all elements of an XML document and stores them in a given ObjectStore

  • read_aas_xml_file() constructs all elements of an XML document and returns them in a DictObjectStore

These functions take a decoder class as keyword argument, which allows parsing in failsafe (default) or non-failsafe mode. Parsing stripped elements - used in the HTTP adapter - is also possible. It is also possible to subclass the default decoder class and provide an own decoder.

In failsafe mode errors regarding missing attributes and elements or invalid values are caught and logged. In non-failsafe mode any error would abort parsing. Error handling is done only by _failsafe_construct() in this module. Nearly all constructor functions are called by other constructor functions via _failsafe_construct(), so an error chain is constructed in the error case, which allows printing stacktrace-like error messages like the following in the error case (in failsafe mode of course):

KeyError: aas:id on line 252 has no attribute with name idType!
    -> Failed to construct aas:id on line 252 using construct_identifier!
    -> Failed to construct aas:conceptDescription on line 247 using construct_concept_description!

Unlike the JSON deserialization, parsing is done top-down. Elements with a specific tag are searched on the level directly below the level of the current xml element (in terms of parent and child relation) and parsed when found. Constructor functions of these elements will then again search for mandatory and optional child elements and construct them if available, and so on.

class basyx.aas.adapter.xml.xml_deserialization.AASFromXmlDecoder

The default XML decoder class.

It parses XML documents in a failsafe manner, meaning any errors encountered will be logged and invalid XML elements will be skipped. Most member functions support the object_class parameter. It was introduced so they can be overwritten in subclasses, which allows constructing instances of subtypes.

class basyx.aas.adapter.xml.xml_deserialization.StrictAASFromXmlDecoder

Non-failsafe XML decoder. Encountered errors won’t be caught and abort parsing.

class basyx.aas.adapter.xml.xml_deserialization.StrippedAASFromXmlDecoder

Decoder for stripped XML elements. Used in the HTTP adapter.

class basyx.aas.adapter.xml.xml_deserialization.StrictStrippedAASFromXmlDecoder

Non-failsafe decoder for stripped XML elements.

basyx.aas.adapter.xml.xml_deserialization.read_aas_xml_file(file: IO, **kwargs: Any) → basyx.aas.model.provider.DictObjectStore[basyx.aas.model.base.Identifiable]

A wrapper of read_aas_xml_file_into(), that reads all objects in an empty DictObjectStore. This function supports the same keyword arguments as read_aas_xml_file_into().

Parameters

  • file – A filename or file-like object to read the XML-serialized data from

  • kwargs – Keyword arguments passed to read_aas_xml_file_into()

Returns

A DictObjectStore containing all AAS objects from the XML file

basyx.aas.adapter.xml.xml_deserialization.read_aas_xml_file_into(object_store: basyx.aas.model.provider.AbstractObjectStore[basyx.aas.model.base.Identifiable], file: IO, replace_existing: bool = False, ignore_existing: bool = False, failsafe: bool = True, stripped: bool = False, decoder: Optional[Type[basyx.aas.adapter.xml.xml_deserialization.AASFromXmlDecoder]] = None, **parser_kwargs: Any) → Set[str]

Read an Asset Administration Shell XML file according to ‘Details of the Asset Administration Shell’, chapter 5.4 into a given ObjectStore.

Parameters

  • object_store – The ObjectStore in which the Identifiable objects should be stored

  • file – A filename or file-like object to read the XML-serialized data from

  • replace_existing – Whether to replace existing objects with the same identifier in the object store or not

  • 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.

  • 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.

  • stripped – If True, stripped XML elements are parsed. See https://git.rwth-aachen.de/acplt/pyi40aas/-/issues/91 This parameter is ignored if a decoder class is specified.

  • decoder – The decoder class used to decode the XML elements

  • parser_kwargs – Keyword arguments passed to the XMLParser constructor

Returns

A set of Identifiers that were added to object_store

basyx.aas.adapter.xml.xml_deserialization.read_aas_xml_element(file: IO, construct: basyx.aas.adapter.xml.xml_deserialization.XMLConstructables, failsafe: bool = True, stripped: bool = False, decoder: Optional[Type[basyx.aas.adapter.xml.xml_deserialization.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.

Parameters

  • file – A filename or file-like object to read the XML-serialized data from

  • construct – A member of the enum XMLConstructables, specifying which type to construct.

  • 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.

  • stripped – If true, stripped XML elements are parsed. See https://git.rwth-aachen.de/acplt/pyi40aas/-/issues/91 This parameter is ignored if a decoder class is specified.

  • decoder – The decoder class used to decode the XML elements

  • constructor_kwargs – Keyword arguments passed to the constructor function

Returns

The constructed object or None, if an error occurred in failsafe mode.