API Reference¶

This page provides detailed API documentation for all classes and functions in pygixml.

Convenience Functions¶

parse_string(xml_string)¶

Parse XML from string and return XMLDocument.

Parameters:: xml_string (str) – XML content as string
Returns:: Parsed XML document
Return type:: XMLDocument
Raises:: PygiXMLError – If parsing fails

Example:

import pygixml
doc = pygixml.parse_string('<root>content</root>')
print(doc.first_child().name)  # 'root'

parse_file(file_path)¶

Parse XML from file and return XMLDocument.

Parameters:: file_path (str) – Path to XML file
Returns:: Parsed XML document
Return type:: XMLDocument
Raises:: PygiXMLError – If parsing fails

Example:

import pygixml
doc = pygixml.parse_file('data.xml')
print(doc.first_child().name)  # 'root'

XMLDocument Class¶

class XMLDocument¶

XML document wrapper providing document-level operations.

This class represents an XML document and provides methods for loading, saving, and manipulating the document structure.

Methods:

load_string(content)¶

Load XML from string.

Parameters:: content (str) – XML content as string
Returns:: True if parsing succeeded, False otherwise
Return type:: bool

Example:

doc = pygixml.XMLDocument()
success = doc.load_string('<root>content</root>')
print(success)  # True

load_file(path)¶

Load XML from file.

Parameters:: path (str) – Path to XML file
Returns:: True if loading succeeded, False otherwise
Return type:: bool

Example:

doc = pygixml.XMLDocument()
success = doc.load_file('data.xml')
print(success)  # True

save_file(path, indent=' ')¶

Save XML to file.

Parameters:

path (str) – Path where to save the file
indent (str) – Indentation string (default: two spaces)

Example:

doc = pygixml.parse_string('<root>content</root>')
doc.save_file('output.xml', indent='    ')

reset()¶

Reset the document to empty state.

Clears all content and resets the document to its initial state.

Example:

doc = pygixml.parse_string('<root>content</root>')
doc.reset()  # Document is now empty

append_child(name)¶

Append a child node to the document.

Parameters:: name (str) – Name of the new element
Returns:: The newly created node
Return type:: XMLNode

Example:

doc = pygixml.XMLDocument()
root = doc.append_child('root')
item = root.append_child('item')

first_child()¶

Get first child node of the document.

Returns:: First child node or None if no children
Return type:: XMLNode or None

Example:

doc = pygixml.parse_string('<root><child/></root>')
first = doc.first_child()
print(first.name)  # 'root'

child(name)¶

Get child node by name.

Parameters:: name (str) – Name of the child element to find
Returns:: Child node with specified name or None if not found
Return type:: XMLNode or None

Example:

doc = pygixml.parse_string('<root><item>value</item></root>')
item = doc.child('item')
print(item.text())  # 'value'

to_string(indent=' ')¶

Serialize the document to XML string with custom indentation.

Parameters:: indent (str|int) – Indentation string or number of spaces (default: two spaces)
Returns:: XML content as string
Return type:: str

Example:

doc = pygixml.parse_string('<root><item>value</item></root>')
# Default indentation (2 spaces)
xml_string = doc.to_string()
# Custom string indentation
xml_string = doc.to_string('    ')
# Number of spaces
xml_string = doc.to_string(4)

__iter__()¶

Iterate over all nodes in the document.

Returns:: Iterator of XMLNode objects in depth-first order
Return type:: iterator

Example:

doc = pygixml.parse_string('<root><a><b/></a></root>')
for node in doc:
    print(node.name)
# Output: root, a, b

Example:

doc = pygixml.XMLDocument()
root = doc.append_child("root")
doc.save_file("output.xml")

XMLNode Class¶

class XMLNode¶

XML node wrapper providing node-level operations.

This class represents an XML node and provides methods for accessing and manipulating node properties, children, attributes, and text content.

Properties:

name¶

Get node name.

Returns:: Node name or None if no name
Return type:: str or None

Example:

node = doc.first_child()
print(node.name)  # 'root'

value¶

Get node value.

Returns:: Node value or None if no value
Return type:: str or None

Example:

text_node = node.first_child()
print(text_node.value)  # 'text content'

next_sibling¶

Get next sibling node.

Returns:: Next sibling XMLNode or None if no more siblings
Return type:: XMLNode or None

previous_sibling¶

Get previous sibling node.

Returns:: Previous sibling XMLNode or None if no previous sibling
Return type:: XMLNode or None

next_element_sibling¶

Get next sibling that is an element node.

Returns:: Next element sibling or None if no more element siblings
Return type:: XMLNode or None

previous_element_sibling¶

Get previous sibling that is an element node.

Returns:: Previous element sibling or None if no previous element sibling
Return type:: XMLNode or None

parent¶

Get parent node.

Returns:: Parent XMLNode or None if no parent
Return type:: XMLNode or None

xpath¶

Get the absolute XPath of this node.

Returns:: XPath string (e.g., ‘/root/item[1]/name[1]’)
Return type:: str

Example:

node = doc.select_node('//item')
print(node.xpath)  # '/root/item[1]'

xml¶

Get XML representation with default indent (two spaces).

Returns:: XML content as string
Return type:: str

mem_id¶

Get memory identifier for this node.

Returns:: Memory address as integer
Return type:: int

Methods:

set_name(name)¶

Set node name.

Parameters:: name (str) – New name for the node
Returns:: True if successful, False if node is null or invalid
Return type:: bool

Example:

success = node.set_name('new_name')
print(success)  # True

set_value(value)¶

Set node value.

Parameters:: value (str) – New value for the node
Returns:: True if successful, False if node is null or invalid
Return type:: bool

Example:

success = node.set_value('new value')
print(success)  # True

first_child()¶

Get first child node.

Returns:: First child node or None if no children
Return type:: XMLNode or None

Example:

root = doc.first_child()
first_child = root.first_child()
print(first_child.name)  # 'child'

child(name)¶

Get child node by name.

Parameters:: name (str) – Name of the child element to find
Returns:: Child node with specified name or None if not found
Return type:: XMLNode or None

Example:

root = doc.first_child()
item = root.child('item')
print(item.text())  # 'value'

append_child(name)¶

Append a child node.

Parameters:: name (str) – Name of the new child element
Returns:: The newly created child node
Return type:: XMLNode

Example:

root = doc.first_child()
new_child = root.append_child('new_element')

child_value(name=None)¶

Get child value.

Parameters:: name (str) – Optional name of specific child element. If None, returns direct text content.
Returns:: Text content or None if no content
Return type:: str or None

Example:

# Get direct text content
text = node.child_value()
# Get text from specific child
title = node.child_value('title')

first_attribute()¶

Get first attribute.

Returns:: First XMLAttribute or None if no attributes
Return type:: XMLAttribute or None

attribute(name)¶

Get attribute by name.

Parameters:: name (str) – Attribute name
Returns:: XMLAttribute or None if not found
Return type:: XMLAttribute or None

select_nodes(query)¶

Select nodes using XPath query.

Parameters:: query (str) – XPath query string
Returns:: XPathNodeSet containing matching nodes
Return type:: XPathNodeSet

select_node(query)¶

Select single node using XPath query.

Parameters:: query (str) – XPath query string
Returns:: XPathNode or None if not found
Return type:: XPathNode or None

is_null()¶

Check if this node is null.

Returns:: True if node is null
Return type:: bool

to_string(indent=' ')¶

Serialize this node to XML string with custom indentation.

Parameters:: indent (str|int) – Indentation string or number of spaces (default: two spaces)
Returns:: XML content as string
Return type:: str

Example:

node = doc.first_child()
# Default indentation (2 spaces)
xml_string = node.to_string()
# Custom string indentation
xml_string = node.to_string('    ')
# Number of spaces
xml_string = node.to_string(4)

text(recursive=True, join='\n')¶

Get the text content of this node.

Parameters:

recursive (bool) – If True, get text from all descendants (default: True)
join (str) – String to join multiple text nodes (default: newline)

Returns:

Text content as string

Return type:

str

Example:

# Get direct text content only
text = node.text(recursive=False)
# Get all text content with custom separator
text = node.text(join=' ')

find_mem_id(mem_id)¶

Find node by memory identifier.

Parameters:: mem_id (int) – Memory identifier
Returns:: XMLNode with matching memory identifier or None if not found
Return type:: XMLNode or None

__iter__()¶

Iterate over all descendant nodes in DFS preorder.

Returns:: Iterator of XMLNode objects
Return type:: iterator

Example:

for descendant in node:
    print(descendant.name)

__bool__()¶

Check if node is not null.

Returns:: True if node is not null
Return type:: bool

__eq__(other)¶

Compare two nodes for equality.

Parameters:: other (XMLNode) – Other node to compare
Returns:: True if nodes are equal
Return type:: bool

Example:

import pygixml
doc = pygixml.parse_string('<root><item>value</item></root>')
root = doc.first_child()
item = root.child('item')
print(item.text())  # 'value'

XMLAttribute Class¶

class XMLAttribute¶

XML attribute wrapper providing attribute operations.

This class represents an XML attribute and provides methods for accessing and manipulating attribute properties.

Properties:

name¶

Get attribute name.

Returns:: Attribute name or None if no name
Return type:: str or None

Example:

attr = node.attribute('id')
print(attr.name)  # 'id'

value¶

Get attribute value.

Returns:: Attribute value or None if no value
Return type:: str or None

Example:

attr = node.attribute('id')
print(attr.value)  # '123'

Methods:

set_name(name)¶

Set attribute name.

Parameters:: name (str) – New name for the attribute
Returns:: True if successful, False if attribute is null or invalid
Return type:: bool

Example:

success = attr.set_name('new_name')
print(success)  # True

set_value(value)¶

Set attribute value.

Parameters:: value (str) – New value for the attribute
Returns:: True if successful, False if attribute is null or invalid
Return type:: bool

Example:

success = attr.set_value('new_value')
print(success)  # True

next_attribute()¶

Get next attribute.

Returns:: Next XMLAttribute or None if no more attributes
Return type:: XMLAttribute or None

previous_attribute()¶

Get previous attribute.

Returns:: Previous XMLAttribute or None if no previous attribute
Return type:: XMLAttribute or None

Example:

import pygixml
doc = pygixml.parse_string('<root id="123" name="test"/>')
root = doc.first_child()
attr = root.attribute('id')
print(attr.value)  # '123'

XPath Classes¶

XPathQuery Class¶

class XPathQuery(query)¶

Compiled XPath query for efficient repeated execution.

Parameters:: query (str) – XPath query string

Methods:

evaluate_node_set(context_node)¶

Evaluate query and return node set.

Parameters:: context_node (XMLNode) – Context node for evaluation
Returns:: XPathNodeSet containing matching nodes
Return type:: XPathNodeSet

evaluate_node(context_node)¶

Evaluate query and return first node.

Parameters:: context_node (XMLNode) – Context node for evaluation
Returns:: XPathNode or None if not found
Return type:: XPathNode or None

evaluate_boolean(context_node)¶

Evaluate query and return boolean result.

Parameters:: context_node (XMLNode) – Context node for evaluation
Returns:: Boolean result
Return type:: bool

evaluate_number(context_node)¶

Evaluate query and return numeric result.

Parameters:: context_node (XMLNode) – Context node for evaluation
Returns:: Numeric result
Return type:: float

evaluate_string(context_node)¶

Evaluate query and return string result.

Parameters:: context_node (XMLNode) – Context node for evaluation
Returns:: String result or None if empty
Return type:: str or None

Example:

query = pygixml.XPathQuery("book[@category='fiction']")
results = query.evaluate_node_set(root)

XPathNode Class¶

class XPathNode¶

Result of XPath query, representing a node or attribute.

Methods:

node()¶

Get XML node from XPath node.

Returns:: XMLNode or None if no node
Return type:: XMLNode or None

attribute()¶

Get XML attribute from XPath node.

Returns:: XMLAttribute or None if no attribute
Return type:: XMLAttribute or None

parent()¶

Get parent node.

Returns:: Parent XMLNode or None if no parent
Return type:: XMLNode or None

Example:

xpath_node = root.select_node("book[1]")
if xpath_node:
    book_node = xpath_node.node()

XPathNodeSet Class¶

class XPathNodeSet¶

Collection of XPath query results.

Methods and Properties:

__len__()¶

Get number of nodes in the set.

Returns:: Number of nodes
Return type:: int

__getitem__(index)¶

Get node at specified index.

Parameters:: index (int) – Index of node to retrieve
Returns:: XPathNode at specified index
Return type:: XPathNode
Raises:: IndexError – If index out of range

__iter__()¶

Iterate over nodes in the set.

Returns:: Iterator of XPathNode objects
Return type:: iterator

Example:

node_set = root.select_nodes("book")
print(f"Found {len(node_set)} books")
for node in node_set:
    book = node.node()
    print(book.child("title").child_value())

Node Types¶

The following node types are available as constants:

node_null = 0¶: Null node

node_document = 1¶: Document node

node_element = 2¶: Element node

node_pcdata = 3¶: PCDATA node

node_cdata = 4¶: CDATA node

node_comment = 5¶: Comment node

node_pi = 6¶: Processing instruction node

node_declaration = 7¶: Declaration node

node_doctype = 8¶: DOCTYPE node

Example:

import pygixml
node_type = node.node_type()
if node_type == pygixml.node_element:
    print("This is an element node")

Error Handling¶

All methods that can fail will return appropriate values (like None or False) rather than throwing exceptions for expected error conditions. However, some operations may raise exceptions:

parse_string() and parse_file() raise PygiXMLError for invalid XML
save_file() may raise exceptions for file system errors
Indexing operations on XPathNodeSet raise IndexError for out-of-range access
Property setters (name and value) raise PygiXMLError for null or invalid nodes/attributes

Best Practices¶

Check return values: Always check if nodes/attributes exist before using them
Use context managers: For file operations, use try/except blocks
Reuse XPathQuery: For repeated queries, compile once and reuse
Iterate efficiently: Use the iterator pattern for large node sets

Example of proper error handling:

try:
    doc = pygixml.parse_string(xml_string)
except ValueError as e:
    print(f"Failed to parse XML: {e}")
    return

root = doc.first_child()
if not root:
    print("Empty document")
    return

book = root.child("book")
if book:
    title = book.child("title")
    if title:
        print(f"Title: {title.child_value()}")