Submodule xml

class mscxyz.xml.XmlManipulator(element: _Element | None = None, file_path: str | Path | None = None, xml_markup: str | None = None)[source]

Bases: object

A wrapper around lxml.etree

file_path: str | Path | None
root: _Element
static parse_file(path: str | Path | TextIOWrapper) → _Element[source]

Read an XML file and return the root element.

Parameters:

path – The path to the XML file.

Returns:

The root element of the XML file.

static parse_string(xml_markup: str) → _Element[source]
tostring(element: _Element | _ElementTree | None = None) → str[source]

Convert the XML element or tree to a string.

Parameters:

element – The XML element or tree to write.

write(path: str | Path, element: _Element | _ElementTree | None = None) → None[source]

Write the XML element or tree to the specified file.

Parameters:

  • path – The path to the file.

  • element – The XML element or tree to write.

Returns:

None

static create_element(tag_name: str, attrib: _DictAnyStr | None = None) → _Element[source]

Create a new XML element.

Parameters:

  • tag_name – The name of the tag to create.

  • attrib – Optional dictionary of attributes for the element.

Returns:

The newly created XML element.

static create_sub_element(parent: _Element | str, tag_name: str, text: str | None = None, attrib: _DictAnyStr | None = None) → tuple[_Element, _Element][source]

Create a subelement and add it to a parent element.

Parameters:

  • parent – The parent XML element or tag name string. If a string is provided, a new element will be created.

  • tag_name – The name of the subelement tag to create.

  • text – Optional text content for the subelement.

  • attrib – Optional dictionary of attributes for the subelement.

Returns:

A tuple containing the parent element and the newly created subelement.

find(element_path: str, element: _Element | _ElementTree | None = None) → _Element | None[source]

Find the first element matching the element path expression.

Parameters:

  • element_path – A element path expression with limited XPath support, for example .//Note selects all <Note> elements.

  • element – The XML element to search within. Defaults to the root element.

Returns:

The first matching element or None if not found.

find_safe(element_path: str, element: _Element | _ElementTree | None = None) → _Element[source]

Find an element in the given XML element using the specified element path.

Parameters:

  • element_path –

    A element path expression with limited XPath support, for example .//Note selects all <Note> elements.

  • element – The XML element to search within.

Returns:

The found element.

Raises:

ValueError – If the element is not found.

findall(element_path: str, element: _Element | _ElementTree | None = None) → list[_Element][source]

Find all elements matching the element path expression.

Parameters:

  • element_path –

    A element path expression with limited XPath support, for example .//Note selects all <Note> elements.

  • element – The XML element to search within. Defaults to the root element.

Returns:

A list of all matching elements.

xpath(xpath: str, element: _Element | _ElementTree | None = None) → _Element | None[source]

Find the first matching element in the XML tree using XPath.

Parameters:

  • xpath – The XPath expression to search for.

  • element – The root element of the XML tree.

Returns:

The first matching element or None if no match is found.

xpath_safe(xpath: str, element: _Element | _ElementTree | None = None) → _Element[source]

Safely retrieves the first matching XML element using the given XPath expression.

Parameters:

  • xpath – The XPath expression to match elements.

  • element – The XML element to search within.

Returns:

The first matching XML element.XPath

Raises:

ValueError – If more than one element is found matching the XPath expression.

xpathall(xpath: str, element: _Element | _ElementTree | None = None) → list[_Element] | None[source]

Returns a list of elements matching the given XPath expression.

Parameters:

  • xpath – The XPath expression to match elements.

  • element – The XML element to search within.

Returns:

A list of elements matching the XPath expression, or None if no elements are found.

xpathall_safe(xpath: str, element: _Element | _ElementTree | None = None) → list[_Element][source]

Safely retrieves a list of elements matching the given XPath expression within the specified element.

Parameters:

  • xpath – The XPath expression to match elements.

  • element – The XML element to search within.

Returns:

A list of elements matching the XPath expression.

Raises:

ValueError – If the XPath expression is not found in the element.

get_text(element: _Element | _ElementTree | None = None) → str | None[source]

Get the text content of an XML element.

Parameters:

element – The XML element.

Returns:

The text content of the XML element, or None if the element is None.

get_text_safe(element: _Element | _ElementTree | None = None, element_path: str | None = None) → str[source]

Safely retrieves the text content from an XML element.

Parameters:

  • element – The XML element to retrieve the text from.

  • element_path –

    A element path expression with limited XPath support, for example .//Note selects all <Note> elements.

Returns:

The text content of the element.

Raises:

ValueError – If the element is None or has no text content.

set_text(element_path: str, value: str | int | float, element: _Element | _ElementTree | None = None) → XmlManipulator[source]

Set the text value of an XML element at the specified element path.

Parameters:

  • element_path –

    A element path expression with limited XPath support to locate the target element, for example .//Note selects all <Note> elements.

  • value – The new value to set for the element’s text.

  • element – The XML element to modify.

Returns:

The XmlManipulator instance for method chaining.

static replace(old: _Element, new: _Element) → None[source]

Replaces an element in its parent with a new element.

Parameters:

  • old – The element to be replaced.

  • new – The new element to replace the old element.

Returns:

None

static remove(element: _Element | None) → None[source]

Remove the given element from its parent.

Parameters:

element – The element to be removed.

remove_tags(*element_paths: str) → XmlManipulator[source]

Remove all elements matching the given element path expressions.

Parameters:

element_paths – Variable number of element path expressions <https://docs.python.org/3/library/xml.etree.elementtree.html#elementtree-xpath>`_ with limited XPath support to locate the target elements, for example .//Note selects all <Note> elements.

Returns:

The XmlManipulator instance for method chaining.