jxmlease

Common errors

• KeyError: 'attribute_name'

  cause Attempting to access an XML attribute directly using `node.get_xml_attr('attribute_name')` when the attribute does not exist on the node, and no default value was provided.
  fix Use `node.get_xml_attr('attribute_name', default_value)` to provide a fallback, or check for attribute existence before accessing: `if 'attribute_name' in node.xml_attrs: ...`.

• AttributeError: If the node is out of date.

  cause Trying to modify an `XMLNodeBase` instance (e.g., `append_cdata()`, `delete_xml_attr()`, `set_xml_attr()`) that is no longer a valid, current reference within the parsed XML tree, typically after other structural modifications have occurred.
  fix Always operate on the most recently returned or explicitly retrieved `XMLNodeBase` object. If modifications are intertwined, use `node.get_current_node()` to ensure you have an up-to-date reference before applying further changes.

Warnings

• gotcha Standard library's ElementTree does not maintain original XML namespace identifiers. If namespace fidelity is critical during parsing and iteration, consider installing `lxml`.
  Fix: Install `lxml` (`pip install lxml`) and `jxmlease` will automatically leverage its advanced functionality for improved namespace handling.
• gotcha When parsing XML with mixed element types that are expected to maintain a specific order (e.g., `<foo><a>one</a><b>two</b><a>three</a></foo>`), `jxmlease` might reorder siblings of different tags during conversion to Python dicts, leading to incorrect XML output if re-emitted. This is due to its dictionary-centric representation.
  Fix: For applications where child order of mixed tags is strictly semantic, `jxmlease` might require post-processing of the Python structure or a different XML library. Or, ensure consistent tag usage for siblings if order is important.
• gotcha XML output generated from Python data structures with explicit namespaces (e.g., `{'soapenv:Envelope xmlns:foo':'...'}`) may incorrectly include namespace declarations on *both* opening and closing tags, which is not standard compliant and can break other XML parsers.
  Fix: This is an open issue. For critical use cases requiring perfectly formatted namespace output, manual post-processing of the XML string may be necessary, or consider alternatives for XML emission if this behavior is observed.

Install

• pip install jxmlease Install latest version

Imports

• parse
  wrong:

  import jxmlease; jxmlease.Parser().parse(xml_string)

  correct:

  from jxmlease import parse

  The top-level `parse` function is a convenient shortcut for `jxmlease.Parser().parse()`.
• emit_xml
  wrong:

  import jxmlease; jxmlease.XMLDictNode(data_structure).emit_xml()

  correct:

  from jxmlease import emit_xml

  The top-level `emit_xml` function was introduced in v1.0.1 for direct conversion from Python data structures to XML, simplifying output.
• XMLDictNode

  from jxmlease import XMLDictNode

  Used for converting Python dictionaries to jxmlease's intelligent XML dictionary nodes for more control.

Quickstart

This quickstart demonstrates parsing an XML string into a Python data structure, accessing elements and attributes, and converting a Python dictionary back into an XML string using the `parse` and `emit_xml` top-level functions. For more granular control over XML node creation, `XMLDictNode` and `XMLListNode` can be used directly.

import jxmlease

xml_string = """<root><item id="1">Value 1</item><item id="2">Value 2</item></root>"""

# Parse XML to Python data structure
data_structure = jxmlease.parse(xml_string)
print("Parsed Data Structure:")
print(data_structure.prettyprint())

# Accessing data and attributes
print(f"\nFirst item value: {data_structure['root']['item'][0].value}")
print(f"First item ID: {data_structure['root']['item'][0].get_xml_attr('id')}")

# Convert Python data structure to XML
python_data = {
    'catalog': {
        'book': [
            {'@id': 'bk101', 'author': 'Gambardella, Matthew', 'title': 'XML Developer's Guide'},
            {'@id': 'bk102', 'author': 'Ralls, Kim', 'title': 'Midnight Rain'}
        ]
    }
}

# Using emit_xml (available since v1.0.1)
output_xml = jxmlease.emit_xml(python_data)
print("\nEmitted XML:")
print(output_xml)