diff --git a/stubs/xmltodict/@tests/test_cases/check_parse.py b/stubs/xmltodict/@tests/test_cases/check_parse.py new file mode 100644 index 000000000000..afe44303085f --- /dev/null +++ b/stubs/xmltodict/@tests/test_cases/check_parse.py @@ -0,0 +1,33 @@ +from __future__ import annotations + +from typing import Any +from typing_extensions import assert_type + +import xmltodict +from xmltodict import _Item, _Path + +XML = "12" + +# Default mode returns the root element as a dict. +assert_type(xmltodict.parse(XML), dict[str, Any]) +assert_type(xmltodict.parse(XML, item_depth=0), dict[str, Any]) + + +# Streaming mode (item_depth > 0) calls item_callback for each item and returns None. +def on_item(_path: _Path, _item: _Item) -> bool: + return True + + +assert_type(xmltodict.parse(XML, item_depth=2, item_callback=on_item), dict[str, Any] | None) + + +# force_list and force_cdata callables receive the list of ancestors, not a single tuple. +def force_list(_path: _Path, key: str, _value: _Item) -> bool: + return key == "b" + + +def force_cdata(path: _Path, _key: str, _value: str) -> bool: + return len(path) > 1 + + +xmltodict.parse(XML, force_list=force_list, force_cdata=force_cdata) diff --git a/stubs/xmltodict/xmltodict.pyi b/stubs/xmltodict/xmltodict.pyi index d0e1237d3360..4068a07e9c58 100644 --- a/stubs/xmltodict/xmltodict.pyi +++ b/stubs/xmltodict/xmltodict.pyi @@ -1,12 +1,18 @@ from _typeshed import ReadableBuffer, SupportsRead, SupportsWrite from collections.abc import Callable, Container, Generator, Mapping -from typing import Any, TypeAlias, overload +from typing import Any, Literal, TypeAlias, overload class ParsingInterrupted(Exception): ... # dict as attribute value is exclusive to xmlns: https://github.com/bigpick/xmltodict/commit/22541b4874365cb8d2397f23087a866b3081fd9c _AttrValue: TypeAlias = str | dict[str, str] _AttrDict: TypeAlias = dict[str, _AttrValue] +_Path: TypeAlias = list[tuple[str, _AttrDict | None]] +# The value of a finished element: its text, a dict for elements with attributes/children, or None if empty. +_Item: TypeAlias = str | _AttrDict | None +# Called as `force_list(path, key, value)`, where `path` is the list of ancestors (without the element itself). +_ForceList: TypeAlias = bool | Container[str] | Callable[[_Path, str, _Item], bool] | None +_ForceCdata: TypeAlias = bool | Container[str] | Callable[[_Path, str, str], bool] class _DictSAXHandler: path: list[tuple[str, _AttrDict | None]] @@ -15,10 +21,10 @@ class _DictSAXHandler: item: _AttrDict | None item_depth: int xml_attribs: bool - item_callback: Callable[[list[tuple[str, _AttrDict | None]], str | _AttrDict | None], bool] + item_callback: Callable[[_Path, _Item], bool] attr_prefix: str cdata_key: str - force_cdata: bool | Container[str] | Callable[[tuple[str, _AttrDict | None], str, str], bool] + force_cdata: _ForceCdata cdata_separator: str postprocessor: Callable[[list[tuple[str, _AttrDict | None]], str, _AttrValue], tuple[str, _AttrValue]] | None dict_constructor: type @@ -26,23 +32,23 @@ class _DictSAXHandler: namespace_separator: str namespaces: Mapping[str, str | None] | None namespace_declarations: dict[str, str] - force_list: bool | Container[str] | Callable[[tuple[str, _AttrDict | None], str, str], bool] | None + force_list: _ForceList comment_key: str def __init__( self, item_depth: int = 0, - item_callback: Callable[[list[tuple[str, _AttrDict | None]], str | _AttrDict | None], bool] = ..., + item_callback: Callable[[_Path, _Item], bool] = ..., xml_attribs: bool = True, attr_prefix: str = "@", cdata_key: str = "#text", - force_cdata: bool | Container[str] | Callable[[tuple[str, _AttrDict | None], str, str], bool] = False, + force_cdata: _ForceCdata = False, cdata_separator: str = "", postprocessor: Callable[[list[tuple[str, _AttrDict | None]], str, _AttrValue], tuple[str, _AttrValue]] | None = None, dict_constructor: type = ..., strip_whitespace: bool = True, namespace_separator: str = ":", namespaces: Mapping[str, str | None] | None = None, - force_list: bool | Container[str] | Callable[[tuple[str, _AttrDict | None], str, str], bool] | None = None, + force_list: _ForceList = None, comment_key: str = "#comment", ) -> None: ... def startNamespaceDecl(self, prefix: str, uri: str) -> None: ... @@ -50,8 +56,9 @@ class _DictSAXHandler: def endElement(self, full_name: str) -> None: ... def characters(self, data: str) -> None: ... def comments(self, data: str) -> None: ... - def push_data(self, item: _AttrDict | None, key: str, data: str) -> _AttrDict: ... + def push_data(self, item: _AttrDict | None, key: str, data: _Item) -> _AttrDict: ... +@overload def parse( xml_input: str | ReadableBuffer | SupportsRead[bytes] | Generator[ReadableBuffer], encoding: str | None = None, @@ -61,20 +68,44 @@ def parse( disable_entities: bool = True, process_comments: bool = False, *, - item_depth: int = 0, - item_callback: Callable[[list[tuple[str, _AttrDict | None]], str | _AttrDict | None], bool] = ..., + item_depth: Literal[0] = 0, + item_callback: Callable[[_Path, _Item], bool] = ..., xml_attribs: bool = True, attr_prefix: str = "@", cdata_key: str = "#text", - force_cdata: bool | Container[str] | Callable[[tuple[str, _AttrDict | None], str, str], bool] = False, + force_cdata: _ForceCdata = False, cdata_separator: str = "", postprocessor: Callable[[list[tuple[str, _AttrDict | None]], str, _AttrValue], tuple[str, _AttrValue]] | None = None, dict_constructor: type = ..., strip_whitespace: bool = True, namespaces: Mapping[str, str | None] | None = None, - force_list: bool | Container[str] | Callable[[tuple[str, _AttrDict | None], str, str], bool] | None = None, + force_list: _ForceList = None, comment_key: str = "#comment", ) -> dict[str, Any]: ... +@overload +def parse( + xml_input: str | ReadableBuffer | SupportsRead[bytes] | Generator[ReadableBuffer], + encoding: str | None = None, + expat: Any = ..., + process_namespaces: bool = False, + namespace_separator: str = ":", + disable_entities: bool = True, + process_comments: bool = False, + *, + item_depth: int, + item_callback: Callable[[_Path, _Item], bool] = ..., + xml_attribs: bool = True, + attr_prefix: str = "@", + cdata_key: str = "#text", + force_cdata: _ForceCdata = False, + cdata_separator: str = "", + postprocessor: Callable[[list[tuple[str, _AttrDict | None]], str, _AttrValue], tuple[str, _AttrValue]] | None = None, + dict_constructor: type = ..., + strip_whitespace: bool = True, + namespaces: Mapping[str, str | None] | None = None, + force_list: _ForceList = None, + comment_key: str = "#comment", +) -> dict[str, Any] | None: ... @overload def unparse(