Common objects for XML serialization base (sarpy.io.xml.base)

This module contains the base objects for use in base xml/serializable functionality.

sarpy.io.xml.base.get_node_value(nod: Element) → str | None

Extracts and returns the stripped text value from an ElementTree Element. Returns None if the text is None or only whitespace. :param nod: The XML DOM element. :type nod: ElementTree.Element

Returns:

The stripped string value of the node, or None.

Return type:

Optional[str]

sarpy.io.xml.base.create_new_node(doc: ElementTree, tag: str, parent: Element | None = None) → Element

XML ElementTree node creation helper function.

Parameters:

  • doc (ElementTree.ElementTree) – The xml Document object.

  • tag (str) – Name/tag for new xml element.

  • parent (None|ElementTree.Element) – The parent element for the new element. Defaults to the document root element if unspecified.

Returns:

The new element populated as a child of parent.

Return type:

ElementTree.Element

sarpy.io.xml.base.create_text_node(doc: ElementTree, tag: str, value: str, parent: Element | None = None) → Element

XML ElementTree text node creation helper function

Parameters:

  • doc (ElementTree.ElementTree) – The xml Document object.

  • tag (str) – Name/tag for new xml element.

  • value (str) – The value for the new element.

  • parent (None|ElementTree.Element) – The parent element for the new element. Defaults to the document root element if unspecified.

Returns:

The new element populated as a child of parent.

Return type:

ElementTree.Element

sarpy.io.xml.base.find_first_child(node: Element, tag: str, xml_ns: Dict[str, str] | None = None, ns_key: str | None = None) → Element

Finds the first child node

Parameters:

  • node (ElementTree.Element)

  • tag (str)

  • xml_ns (None|dict XML namespace of the node in question)

  • ns_key (None|str Namespace key to use to preface the tag)

Return type:

ElementTree.Element

sarpy.io.xml.base.find_children(node: Element, tag: str, xml_ns: Dict[str, str] | None = None, ns_key: str | None = None)

Finds the collection of children nodes

Parameters:

  • node (ElementTree.Element)

  • tag (str)

  • xml_ns (None|dict)

  • ns_key (None|str)

sarpy.io.xml.base.parse_xml_from_string(xml_string)

Parse the ElementTree root node and xml namespace dict from a xml string.

Parameters:

xml_string (str|bytes)

Returns:

  • root_node (ElementTree.Element)

  • xml_ns (Dict[str, str])

sarpy.io.xml.base.parse_xml_from_file(xml_file_path)

Parse the ElementTree root node and xml namespace dict from a xml file.

Parameters:

xml_file_path (str)

Returns:

  • root_node (ElementTree.Element)

  • xml_ns (Dict[str, str])

sarpy.io.xml.base.validate_xml_from_string(xml_string, xsd_path, output_logger=None)

Validate a xml string against a given xsd document.

Parameters:

  • xml_string (str|bytes)

  • xsd_path (str) – The path to the relevant xsd document.

  • output_logger – A desired output logger.

Returns:

True if valid, False otherwise. Failure reasons will be logged at ‘error’ level by the module.

Return type:

bool

sarpy.io.xml.base.validate_xml_from_file(xml_path, xsd_path, output_logger=None)

Validate a xml string against a given xsd document.

Parameters:

  • xml_path (str) – The path to the relevant xml file

  • xsd_path (str) – The path to the relevant xsd document.

  • output_logger – A desired output logger.

Returns:

True if valid, False otherwise. Failure reasons will be logged at ‘error’ level by the module.

Return type:

bool

sarpy.io.xml.base.parse_str(value, name, instance)

The parse_str function is not a generic string parser. It is a helper function specifically for parsing values within XML elements in sarpy.io.xml.base. It’s used internally by the library to extract text values from XML ElementTree objects. The function is not intended for public use for general string parsing, and attempting to use it on a simple text string will just return the initial string as parse_str expects an XML element as its input.

Parameters:

  • value (ElementTree.Element|None|str) – The ElementTree.Element entity that you want to get the value from. None returns None. A string value will return the given string unchanged.

  • name (str) – Name of the field to return the value of. This is only used in the raised error message

  • instance – The class of the variable. This is only used in the raised error message.

Returns:

Returns None if value passed is None. Returns the string passed if value is a string. Returns the string value of a node when passed an ElementTree.Element

Return type:

None | str

Raises:

TypeError – When passed a value with a type other than the expected input types.

sarpy.io.xml.base.parse_bool(value, name, instance)

The parse_bool function is a helper function specifically for parsing boolean values within XML elements in sarpy.io.xml.base. The function is not intended for public use.

Parameters:

  • value (ElementTree.Element|None|str[0, 1, true, false]) – The ElementTree.Element entity that you want to get the value from. None returns None. A string value will return the boolean value for the string if it can be converted to a boolean.

  • name (str) – Name of the field to return the value of. This is only used in the raised error message

  • instance – The class of the variable. This is only used in the raised error message.

Returns:

Returns None if value passed is None. Returns the boolean value of a node when passed an ElementTree.Element

Return type:

None | bool

Raises:

ValueError – When passed a value with a type other than the expected input types.

sarpy.io.xml.base.parse_int(value, name, instance)

The parse_int function is a helper function specifically for parsing integer values within XML elements in sarpy.io.xml.base. The function is not intended for public use. This function is recursive.

Parameters:

  • value (ElementTree.Element|None|int|str) – The ElementTree.Element entity that you want to get the value from. None returns None. int returns the integer. A string value will return the integer value for the string if it can be converted to an integer.

  • name (str) – Name of the field to return the value of. This is only used in the raised error message

  • instance – The class of the variable. This is only used in the raised error message.

Returns:

Returns None if value passed is None. Returns the boolean value of a node when passed an ElementTree.Element

Return type:

None | bool

Raises:

TypeError – When passed a value with a type other than the expected input types.

sarpy.io.xml.base.parse_float(value, name, instance)

The parse_float function is a helper function specifically for parsing float values within XML elements in sarpy.io.xml.base. The function is not intended for public use. This function is recursive.

Parameters:

  • value (ElementTree.Element|None|float|str) – The ElementTree.Element entity that you want to get the value from. None returns None. Float returns a float. A string value will return the float value for the string if it can be converted to a float.

  • name (str) – Name of the field to return the value of. This is only used in the raised error message

  • instance – The class of the variable. This is only used in the raised error message.

Returns:

Returns None if value passed is None. Returns the float value of a node when passed an ElementTree.Element

Return type:

None | bool

Raises:

TypeError – When passed a value with a type other than the expected input types.

sarpy.io.xml.base.parse_complex(value, name, instance)

The parse_complex function is a helper function specifically for parsing complex number (numbers with both a real and an imaginary component) values within XML elements in sarpy.io.xml.base. The function is not intended for public use. This function is recursive.

Parameters:

  • value (ElementTree.Element|None|complex|dict) – The ElementTree.Element entity that you want to get the value from. None returns None. complex returns a complex. dict is a dictionary representation of a complex number.

  • name (str) – Name of the field to return the value of. This is only used in the raised error message

  • instance – The class of the variable. This is only used in the raised error message.

Returns:

Returns None if value passed is None. Returns the complex value of a node when passed an ElementTree.Element

Return type:

None | bool

Raises:

TypeError – When passed a value with a type other than the expected input types.

sarpy.io.xml.base.parse_datetime(value, name, instance, units='us')

The parse_datetime function is a helper function specifically for parsing datetime values within XML elements in sarpy.io.xml.base. The function is not intended for public use. This function is recursive.

Parameters:

  • value (ElementTree.Element|None|datetime|dict) – The ElementTree.Element entity that you want to get the value from. None returns None. datetime returns a datetime. A string value will return the datetime value for the string if it can be converted to a datetime.

  • name (str) – Name of the field to return the value of. This is only used in the raised error message

  • instance – The class of the variable. This is only used in the raised error message.

Returns:

Returns None if value passed is None. Returns the float value of a node when passed an ElementTree.Element

Return type:

None | bool

Raises:

TypeError – When passed a value with a type other than the expected input types.

class sarpy.io.xml.base.Serializable(**kwargs)

Bases: object

Basic abstract class specifying the serialization pattern. There are no clearly defined Python conventions for this issue. Every effort has been made to select sensible choices, but this is an individual effort.

Notes

All fields MUST BE LISTED in the _fields tuple. Everything listed in _required tuple will be checked for inclusion in _fields tuple. Note that special care must be taken to ensure compatibility of _fields tuple, if inheriting from an extension of this class.

set_numeric_format(attribute, format_string)

Sets the numeric format string for the given attribute.

Parameters:

  • attribute (str) – attribute for which the format applies - must be in _fields.

  • format_string (str) – format string to be applied

Return type:

None

log_validity_error(msg)

Log a validity check error message.

Parameters:

msg (str)

log_validity_warning(msg)

Log a validity check warning message.

Parameters:

msg (str)

log_validity_info(msg)

Log a validation info message.

Parameters:

msg (str)

is_valid(recursive=False, stack=False)

Returns the validity of this object according to the schema. This is done by inspecting that all required fields (i.e. entries of _required) are not None.

Parameters:

  • recursive (bool) – True if we recursively check that child are also valid. This may result in verbose (i.e. noisy) logging.

  • stack (bool) – Print a recursive error message?

Returns:

condition for validity of this element

Return type:

bool

classmethod from_node(node, xml_ns, ns_key=None, kwargs=None)

For XML deserialization.

Parameters:

  • node (ElementTree.Element) – dom element for serialized class instance

  • xml_ns (None|dict) – The xml namespace dictionary.

  • ns_key (None|str) – The xml namespace key. If xml_ns is None, then this is ignored. If None and xml_ns is not None, then the string default will be used. This will be recursively passed down, unless overridden by an entry of the cls._child_xml_ns_key dictionary.

  • kwargs (None|dict) – None or dictionary of previously serialized attributes. For use in inheritance call, when certain attributes require specific deserialization.

Return type:

Corresponding class instance

to_node(doc, tag, ns_key=None, parent=None, check_validity=False, strict=False, exclude=())

For XML serialization, to a dom element.

Parameters:

  • doc (ElementTree.ElementTree) – The xml Document

  • tag (None|str) – The tag name. Defaults to the value of self._tag and then the class name if unspecified.

  • ns_key (None|str) – The namespace prefix. This will be recursively passed down, unless overridden by an entry in the _child_xml_ns_key dictionary.

  • parent (None|ElementTree.Element) – The parent element. Defaults to the document root element if unspecified.

  • check_validity (bool) – Check whether the element is valid before serializing, by calling is_valid().

  • strict (bool) – Only used if check_validity = True. In that case, if True then raise an Exception (of appropriate type) if the structure is not valid, if False then log a hopefully helpful message.

  • exclude (tuple) – Attribute names to exclude from this generic serialization. This allows for child classes to provide specific serialization for special properties, after using this super method.

Returns:

The constructed dom element, already assigned to the parent element.

Return type:

ElementTree.Element

classmethod from_dict(input_dict)

For json deserialization, from dict instance.

Parameters:

input_dict (dict) – Appropriate parameters dict instance for deserialization

Return type:

Corresponding class instance

to_dict(check_validity=False, strict=False, exclude=())

For json serialization.

Parameters:

  • check_validity (bool) – Check whether the element is valid before serializing, by calling is_valid().

  • strict (bool) – Only used if check_validity = True. In that case, if True then raise an Exception (of appropriate type) if the structure is not valid, if False then log a hopefully helpful message.

  • exclude (tuple) – Attribute names to exclude from this generic serialization. This allows for child classes to provide specific serialization for special properties, after using this super method.

Returns:

dict representation of class instance appropriate for direct json serialization.

Return type:

OrderedDict

copy()

Create a deep copy.

to_xml_bytes(urn=None, tag=None, check_validity=False, strict=False)

Gets a bytes array, which corresponds to the xml string in utf-8 encoding, identified as using the namespace given by urn (if given).

Parameters:

  • urn (None|str|dict) – The xml namespace string or dictionary describing the xml namespace.

  • tag (None|str) – The root node tag to use. If not given, then the class name will be used.

  • check_validity (bool) – Check whether the element is valid before serializing, by calling is_valid().

  • strict (bool) – Only used if check_validity = True. In that case, if True then raise an Exception (of appropriate type) if the structure is not valid, if False then log a hopefully helpful message.

Returns:

bytes array from ElementTree.tostring() call.

Return type:

bytes

to_xml_string(urn=None, tag=None, check_validity=False, strict=False)

Gets a xml string with utf-8 encoding, identified as using the namespace given by urn (if given).

Parameters:

  • urn (None|str|dict) – The xml namespace or dictionary describing the xml namespace.

  • tag (None|str) – The root node tag to use. If not given, then the class name will be used.

  • check_validity (bool) – Check whether the element is valid before serializing, by calling is_valid().

  • strict (bool) – Only used if check_validity = True. In that case, if True then raise an Exception (of appropriate type) if the structure is not valid, if False then log a hopefully helpful message.

Returns:

xml string from ElementTree.tostring() call.

Return type:

str

class sarpy.io.xml.base.Arrayable

Bases: object

Abstract class specifying basic functionality for assigning from/to an array

classmethod from_array(array)

Create from an array type object.

Parameters:

array (numpy.ndarray|list|tuple)

Return type:

Arrayable

get_array(dtype=<class 'numpy.float64'>)

Gets an array representation of the class instance.

Parameters:

dtype (str|numpy.dtype|numpy.number) – numpy data type of the return

Return type:

numpy.ndarray