Quick Start¶

This guide walks you through the core features of pygixml: parsing, navigating, querying, and creating XML documents.

Parsing XML¶

From a string

import pygixml

xml = '''
<library>
    <book id="1" category="fiction">
        <title>The Great Gatsby</title>
        <author>F. Scott Fitzgerald</author>
        <year>1925</year>
    </book>
    <book id="2" category="fiction">
        <title>1984</title>
        <author>George Orwell</author>
        <year>1949</year>
    </book>
</library>
'''

doc = pygixml.parse_string(xml)

From a file

doc = pygixml.parse_file("data.xml")

Tip

Use ParseFlags to control parsing speed vs strictness. ParseFlags.MINIMAL skips escape processing and whitespace handling for maximum throughput. See Parse Flags for details.

Navigating the Tree¶

Every parsed document starts at its root element. From there you walk the tree with first_child(), child(), and sibling properties.

# Access the root element directly
root = doc.root
print(root.name)               # → library

# Get the first <book> child by name
book = root.child("book")
print(book.name)               # → book

# Read an attribute
book_id = book.attribute("id")
print(book_id.value)           # → 1

# Read text content
title = book.child("title")
print(title.text())            # → The Great Gatsby

Iterating¶

Depth-first traversal — the document itself is iterable:

for node in doc:
    print(f"{node.type:12s} {node.name}")

Walking children with siblings:

child = root.first_child()
while child:
    print(child.name)
    child = child.next_sibling

XPath Queries¶

Select multiple nodes or a single node with standard XPath 1.0 expressions:

# All <book> elements
books = root.select_nodes("book")
print(f"Found {len(books)} books")

# Fiction books via attribute filter
fiction = root.select_nodes("book[@category='fiction']")
for b in fiction:
    print(b.node.child("title").text())

# Single match
match = root.select_node("book[@id='2']")
if match:
    print(match.node.child("title").text())   # → 1984

Pre-compiled queries — reuse an XPathQuery for repeated evaluation:

query = pygixml.XPathQuery("book[year > 1950]")

# Node set
results = query.evaluate_node_set(root)

# Scalar results
avg_price = pygixml.XPathQuery(
    "sum(book/price) div count(book)"
).evaluate_number(root)

first_title = pygixml.XPathQuery(
    "book[1]/title"
).evaluate_string(root)

Creating XML from Scratch¶

doc = pygixml.XMLDocument()
root = doc.append_child("catalog")

product = root.append_child("product")
name = product.append_child("name")
name.set_value("Laptop")

price = product.append_child("price")
price.set_value("999.99")

doc.save_file("catalog.xml")

Tip

Attribute creation is not yet exposed in the Python API. When you need attributes, either parse a string or write the raw XML and load it:

doc = pygixml.parse_string(
    '<catalog><product id="1" name="Laptop"/></catalog>'
)

Modifying XML¶

doc = pygixml.parse_string('<item><name>Old</name></item>')
root = doc.root

# Change element text content
root.child("name").set_value("New")

# Rename an element
root.child("name").name = "title"

# Add a new child
root.append_child("price").set_value("29.99")

Error Handling¶

All parsing errors raise PygiXMLError:

try:
    doc = pygixml.parse_string("not xml")
except pygixml.PygiXMLError as e:
    print(f"Parse failed: {e}")

Next Steps¶

Dive into XPath capabilities
Browse the full API reference
See practical examples
Learn about performance