Typing stubs for xmltodict

Warnings

• breaking The `xmltodict` library (which `types-xmltodict` stubs) introduced breaking changes in version 1.0.0, primarily by modernizing for Python 3.9+ and dropping legacy compatibility paths. Ensure your `xmltodict` runtime version matches the expectations of the `types-xmltodict` stubs (e.g., `xmltodict~=1.0.1` for `types-xmltodict==1.0.1.x`).
  Fix: Upgrade `xmltodict` to version 1.0.0 or higher. If encountering type checking errors, align your `types-xmltodict` version with the major/minor version of `xmltodict` (e.g., `types-xmltodict~=1.0.x` for `xmltodict~=1.0.x`).
• gotcha `types-xmltodict` is a stub-only package and does not contain any runtime code. It provides only type annotations for static analysis. You must install the `xmltodict` runtime library separately for your Python code to execute successfully.
  Fix: Always install `xmltodict` alongside `types-xmltodict` using `pip install xmltodict types-xmltodict`.
• gotcha The version numbering for `types-xmltodict` (e.g., `1.0.1.20260408`) indicates that it targets `xmltodict~=1.0.1`. Using a `types-xmltodict` version that is incompatible with your installed `xmltodict` runtime version (e.g., `types-xmltodict` for `1.0.x` with `xmltodict` `0.15.x`) can lead to incorrect or misleading type checking results.
  Fix: Ensure the major and minor versions of `types-xmltodict` align with your `xmltodict` installation. For example, `pip install xmltodict~=1.0 types-xmltodict~=1.0`.
• gotcha `xmltodict` prioritizes convenience for common XML-to-JSON-like conversions and does not guarantee perfect round-tripping of every XML nuance, such as attribute order, mixed content ordering, or the exact order of multiple top-level comments. For exact fidelity, consider a full XML library like `lxml`.
  Fix: Be aware of these limitations when parsing and unparsing. If these nuances are critical, evaluate alternative XML parsing libraries.
• gotcha A disputed CVE (CVE-2025-9375) was filed against `xmltodict` concerning potential XML injection due to underlying limitations in Python's `xml.sax.saxutils.XMLGenerator`. While `xmltodict` has added internal validations, users processing untrusted XML inputs should be aware of these security considerations.
  Fix: Keep `xmltodict` updated to the latest version. Do not disable `disable_entities=True` (the default) unless you fully understand the implications. Carefully validate and sanitize untrusted XML inputs before parsing.
• gotcha When using `xmltodict.unparse()` to convert a Python dictionary back to XML, the input dictionary must contain a single root element. If the dictionary represents multiple top-level XML elements, `unparse` will raise a `ValueError`.
  Fix: Ensure the dictionary passed to `xmltodict.unparse()` always has a single top-level key representing the XML root element. Wrap multi-root data in a single dictionary if necessary.
• gotcha `xmltodict`'s default behavior for elements that might appear once or multiple times is inconsistent: a single occurrence might be a direct value, while multiple occurrences become a list. The `force_list` parameter (e.g., `xmltodict.parse(xml_input, force_list=('elements',))`) is crucial for consistent handling, especially with deeply nested structures.
  Fix: Always use the `force_list` parameter when parsing XML where an element might appear zero, one, or many times to ensure consistent list-based access in the resulting dictionary.

Install

• pip install types-xmltodict xmltodict Install stubs and runtime library

Imports

• parse

  import xmltodict
  xmltodict.parse(...)

  The `types-xmltodict` package provides type hints for the functions directly available from the `xmltodict` module.
• unparse

  import xmltodict
  xmltodict.unparse(...)

  The `types-xmltodict` package provides type hints for the functions directly available from the `xmltodict` module.

Quickstart

This quickstart demonstrates the core functionality of `xmltodict`: parsing an XML string into a Python dictionary and then unparsing a dictionary back into an XML string. With `types-xmltodict` installed, a type checker would ensure that the dictionary keys, values, and function arguments/returns conform to the expected types.

import xmltodict

# Example XML string
xml_string = """
<person>
    <name>John Doe</name>
    <age>30</age>
    <city>New York</city>
</person>
"""

# Parse XML to a Python dictionary (type-checked by types-xmltodict)
data_dict = xmltodict.parse(xml_string)
print(f"Parsed Dictionary: {data_dict}")

# Access data (type-checked)
name = data_dict['person']['name']
print(f"Name: {name}")

# Modify data
data_dict['person']['age'] = 31

# Unparse dictionary back to XML (type-checked)
modified_xml = xmltodict.unparse(data_dict, pretty=True, indent='  ')
print(f"\nModified XML:\n{modified_xml}")