{"id":3846,"library":"types-xmltodict","title":"Typing stubs for xmltodict","description":"This package provides static type annotations for the `xmltodict` library, enabling type checkers like MyPy, Pyright, or PyCharm to validate code that uses `xmltodict`. It is part of the `typeshed` project, a community-maintained repository for Python library stubs, and is automatically released to PyPI. The current version is 1.0.1.20260408, with `typeshed` typically releasing updates daily.","status":"active","version":"1.0.1.20260408","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","xml","xmltodict","type-checking","typeshed"],"install":[{"cmd":"pip install types-xmltodict xmltodict","lang":"bash","label":"Install stubs and runtime library"}],"dependencies":[{"reason":"This package provides type stubs for `xmltodict`. The runtime library must be installed separately for your code to execute. The stub package `1.0.1.20260408` aims to provide accurate annotations for `xmltodict~=1.0.1`.","package":"xmltodict","optional":false}],"imports":[{"note":"The `types-xmltodict` package provides type hints for the functions directly available from the `xmltodict` module.","symbol":"parse","correct":"import xmltodict\nxmltodict.parse(...)"},{"note":"The `types-xmltodict` package provides type hints for the functions directly available from the `xmltodict` module.","symbol":"unparse","correct":"import xmltodict\nxmltodict.unparse(...)"}],"quickstart":{"code":"import xmltodict\n\n# Example XML string\nxml_string = \"\"\"\n<person>\n    <name>John Doe</name>\n    <age>30</age>\n    <city>New York</city>\n</person>\n\"\"\"\n\n# Parse XML to a Python dictionary (type-checked by types-xmltodict)\ndata_dict = xmltodict.parse(xml_string)\nprint(f\"Parsed Dictionary: {data_dict}\")\n\n# Access data (type-checked)\nname = data_dict['person']['name']\nprint(f\"Name: {name}\")\n\n# Modify data\ndata_dict['person']['age'] = 31\n\n# Unparse dictionary back to XML (type-checked)\nmodified_xml = xmltodict.unparse(data_dict, pretty=True, indent='  ')\nprint(f\"\\nModified XML:\\n{modified_xml}\")\n","lang":"python","description":"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."},"warnings":[{"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`).","message":"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`).","severity":"breaking","affected_versions":"xmltodict<1.0.0"},{"fix":"Always install `xmltodict` alongside `types-xmltodict` using `pip install xmltodict types-xmltodict`.","message":"`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.","severity":"gotcha","affected_versions":"All"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Be aware of these limitations when parsing and unparsing. If these nuances are critical, evaluate alternative XML parsing libraries.","message":"`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`.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All"},{"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.","message":"`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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}