Typing stubs for defusedxml

Warnings

• gotcha Stub-only package: `types-defusedxml` is solely for static type checking and contains no runtime code. To utilize `defusedxml` functionality, the `defusedxml` package must also be installed in your environment (`pip install defusedxml`).
  Fix: Ensure both `types-defusedxml` and `defusedxml` are installed: `pip install types-defusedxml defusedxml`.
• gotcha Version Mismatches: Type stubs in typeshed are updated frequently. While `types-defusedxml` aims to provide accurate annotations for `defusedxml==0.7.*`, mismatches between the stub version and the runtime `defusedxml` version can lead to incorrect type-checking results, especially if `defusedxml`'s API changes.
  Fix: It is recommended to pin the stub package version (e.g., `types-defusedxml==0.7.0.YYYYMMDD`) or align its version bounds with your `defusedxml` installation to ensure compatibility: `pip install 'types-defusedxml~=X.Y'` where `X.Y` matches your `defusedxml` version.
• deprecated The `defusedxml.lxml` module is deprecated within `defusedxml` and is slated for removal in future releases. `lxml` itself has built-in mitigations for many XML attacks (e.g., billion laughs, quadratic blowup).
  Fix: Users of `defusedxml.lxml` should migrate to using `lxml`'s native secure parsing options, such as `lxml.etree.XMLParser(resolve_entities=False)` for explicit control over entity resolution.
• breaking Changes from Typeshed: Although typeshed strives to minimize breaking changes, any update to stub packages can potentially introduce changes that might cause your code to fail type-checking. This can occur if the underlying library's API has changed or if the stubs become more restrictive in their type definitions.
  Fix: Review type checker errors after updating and adjust your code or explicitly pin the `types-defusedxml` version to a known compatible one. Consider using tools like Dependabot or Renovate for managing stub version updates.

Install

• pip install types-defusedxml Install types-defusedxml
• pip install defusedxml Install runtime dependency (required for execution)

Imports

• ElementTree

  import defusedxml.ElementTree as ET

• fromstring

  from defusedxml.ElementTree import fromstring

• parse

  from defusedxml.ElementTree import parse

• minidom

  import defusedxml.minidom as minidom

• sax

  import defusedxml.sax as sax

• lxml

  import defusedxml.lxml

  `defusedxml.lxml` is deprecated and should generally be avoided; use lxml's native secure parsing instead.

Quickstart

Demonstrates how to use `defusedxml.ElementTree.fromstring` to parse XML data securely, including handling potential XML entity expansion attacks. The `types-defusedxml` package provides the necessary type hints for `defusedxml` components, allowing static analysis tools to verify type correctness and anticipate exceptions like `EntitiesForbidden`.

import defusedxml.ElementTree as ET
from typing import Dict, Any

xml_data_safe = "<root><item>safe_data</item></root>"
xml_data_malicious = """
<!DOCTYPE foo [
<!ELEMENT foo ANY >
<!ENTITY xxe SYSTEM \"file:///non_existent_path\" >
]>
<foo>&xxe;</foo>
"""

def parse_xml_safely(xml_string: str) -> Dict[str, Any]:
    try:
        # types-defusedxml provides type hints for ET.fromstring
        root = ET.fromstring(xml_string)
        result = {child.tag: child.text for child in root}
        print(f"Successfully parsed: {result}")
        return result
    except ET.EntitiesForbidden as e:
        print(f"Caught an XML entity expansion attempt: {e}")
        return {"error": "Entities Forbidden"}
    except ET.ParseError as e:
        print(f"Caught a general XML parsing error: {e}")
        return {"error": "Parse Error"}

# Example usage with safe data
parse_xml_safely(xml_data_safe)

# Example usage with malicious data (XXE attempt) 
# This should be blocked by defusedxml, with stubs informing type checkers 
# about the EntitiesForbidden exception.
parse_xml_safely(xml_data_malicious)