XmlLoader

loader.format.XmlLoader(
    principal_tags=None,
    *,
    sep='.',
    include_text=True,
    propagate_ancestors=True,
)

Configurable XML normaliser producing flat pa.Table objects.

XmlLoader parses one or more XML files and normalises their nested element structures into flat PyArrow tables stored in a timetoalign.storage.store.DictStore.

Principal tags determine which element types become tables:

• If principal_tags is given (a list of tag names), only elements with those tags are collected and normalised.
• If principal_tags is None (the default), tags appearing at least twice in the document are auto-detected as principal.

Each element’s attributes become fields. Nested child elements are flattened with dot-separated field names. Ancestor attributes are propagated downward with parent_<tag>_<attr> prefixes.

Follows the standard two-phase pattern:

1. loader.load(*sources) – parse XML files.
2. loader.get_table(tag) – retrieve a normalised table.

Parameters

Name	Type	Description	Default
principal_tags	list[str] | None	List of element tags to normalise. None for auto-detect.	None
sep	str	Separator for flattened nested key names. Default ".".	'.'
include_text	bool	Whether to include element text as _text field. Default True.	True
propagate_ancestors	bool	Whether to propagate ancestor attributes. Default True.	True

Examples

Auto-detect all repeated tags::

loader = XmlLoader()
loader.load("data.xml")
for tag in loader.store.keys():
    print(tag, loader.get_table(tag).num_rows)

Specify principal tags::

loader = XmlLoader(principal_tags=["Signal", "Audio"])
loader.load("manifest.xml")
assert loader.get_table("Signal").num_rows > 0

See Also

timetoalign.storage.store.DictStore timetoalign.loader.base.Loader timetoalign.loader.format.json.JsonLoader

Attributes

Name	Description
file_metadata	Metadata from the root element’s attributes.
raw_root	The raw parsed XML root element from the last loaded file.
store	The DictStore containing all normalised tables.
tables	Dict mapping tag names to normalised pa.Table objects.

Methods

Name	Description
clear	Clear all loaded data.
get_table	Retrieve a normalised table by element tag.
keys	Return the list of available table tag names.
load	Load one or more XML files.
load_element	Load from an already-parsed Element tree.
load_string	Load from an XML string.

clear

loader.format.XmlLoader.clear()

Clear all loaded data.

get_table

loader.format.XmlLoader.get_table(tag)

Retrieve a normalised table by element tag.

Parameters

Name	Type	Description	Default
tag	str	The principal tag name.	required

Returns

Name	Type	Description
	pa.Table	A pa.Table with one row per element.

Raises

Name	Type	Description
	KeyError	If tag was not normalised.

keys

loader.format.XmlLoader.keys()

Return the list of available table tag names.

load

loader.format.XmlLoader.load(*sources)

Load one or more XML files.

For multiple files the tables are concatenated (same tags) or added (new tags).

Parameters

Name	Type	Description	Default
*sources	Path | str	Paths to XML files.	()

Returns

Name	Type	Description
	Self	Self, for method chaining.

load_element

loader.format.XmlLoader.load_element(root)

Load from an already-parsed Element tree.

Convenient for programmatic use or testing.

Parameters

Name	Type	Description	Default
root	ET.Element	An XML Element.	required

Returns

Name	Type	Description
	Self	Self, for method chaining.

load_string

loader.format.XmlLoader.load_string(xml_string)

Load from an XML string.

Convenient for programmatic use or testing.

Parameters

Name	Type	Description	Default
xml_string	str	A valid XML string.	required

Returns

Name	Type	Description
	Self	Self, for method chaining.