Welcome to xmlasdict’s documentation!

Indices and tables

API Docs

xmlasdict

xmlasdict

class xmlasdict.IterWrapper(node_list)

Wraps a list of elements; and as such does smart things to make the whole navigating experience as py-natural as possible. So, some clever ‘list-like’ behaviour is added onto what the base Wrapper -class already provides.

As a list-like beast this representation of the nested XML content is not subscriptable by str (name of child-element or @attribute) but instead by int or slice.

dumps()

Returns the joined outerXML of the various contained wrappers.

property tag

Returns the list of tags of the contained wrappers.

unpack(tag: Optional[str] = None)

Returns self, as by nature the IterWrapper is the level not to be further unpacked.

unwrap()

Turns the content into a native py representation (list).

class xmlasdict.Wrapper(node: xml.etree.ElementTree.Element)

The core of the xmlasdict solution is a wrapper around etree nodes that fake some dict like look on their content. This is the basic return-type of the function parse(). Do not instantiate this objects yourself, instead use parse() or (if you must) the static build().

The dict-like behaviour of this object reflects the fact that one can use wrapper[key] notation to navigate the XML tree. At each stage in that traversal a similar Wrapper will be returned allowing further navigation. Repeated child-elements with the same tag-name will be returned (in order) as list-like objects using the IterWrapper.

Additionally, like a dict one can naturally iterate its keys in a “for k in wrapper:”-loop. The set of these can also be explicitly requested through keys().

Note that this set of keys will also list the associated attributes through the xpath-like '@attribute_name' notation. Naturally this means that these can be used in the wrapper['@attribute_name'] notation to retrieve their string content.

While behaving like a dict, the Wrapper also supports some standard type conversions:

  • str(wrapper) will produce the (inner) XML content of the current node. (respecting whitespace and mixed-content)

  • bool(wrapper) will produce False if the XML element at this level is <empty />

Beyond the expected dict[key] access these Wrapper objects also allow for path-like accessor-calls. e.g. wrapper[‘.//x’] will not only return the direct children, but (depth-first or xml-document-order) all descendants. The allowed syntax for these paths follow the ElementTree.node.findall support.

static build(node, force_list: bool = False)

Actually “builds” a Wrapper or IterWrapper by introspecting the passed node Normally one avoids using this to build your own wrappers in favour of just using the parse() method.

Parameters

  • node – can be a Wrapper that doesn’t need further wrapping or an ElementTree.node or a list of those

  • force_list – enforce returning a list of nodes (i.e an IterWrapper)

copy()

Turns the content into a native py representation (dict for Wrapper and list for IterWrapper)

dumps()

Dumps the full xml representation of the current node as a string. wrapper.dumps() is distinct to str(wrapper) in that will include the wrapping tag (i.e. the outerXML) rather than only the nested content (innerXML).

keys()

Returns a set of nested items (= attributes (@ prefixed) and nested unique tags).

property tag

Returns the tag-name of the current level in the XML tree.

unpack(tag: Optional[str] = None)

Retrieves the highest-level row content down from a chain of (un-useful) single wrapper_nodes. This is a convenience method allowing one to easily descend down into any single-wrapping tags down to the actual repeated content.

Parameters

tag – stop unwrapping if the tag-name matches

unwrap()

Turns the content into a native py representation (dict).

xmlasdict.parse(input: str)

Parses the xml into a xmlasdict structure that allows approaching the wrapped emltree as a (somewhat) regular dict.

Parameters

input (str) – actual XML content, or a file-path to an xml file to read

Returns

the dict-like object to access the content of the parsed XML file

Return type

Wrapper