basedpyright 1.28.3 → 1.28.4

package/dist/typeshed-fallback/stdlib/xml/dom/pulldom.pyi

@@ -1,11 +1,12 @@
 import sys
-from _typeshed import Incomplete, SupportsRead
-from collections.abc import Sequence
-from typing import Final, Literal
-from typing_extensions import TypeAlias
-from xml.dom.minidom import Document, DOMImplementation, Element, Text
+from _typeshed import Incomplete, Unused
+from collections.abc import MutableSequence, Sequence
+from typing import Final, Literal, NoReturn
+from typing_extensions import Self, TypeAlias
+from xml.dom.minidom import Comment, Document, DOMImplementation, Element, ProcessingInstruction, Text
+from xml.sax import _SupportsReadClose
 from xml.sax.handler import ContentHandler
-from xml.sax.xmlreader import XMLReader
+from xml.sax.xmlreader import AttributesImpl, AttributesNSImpl, Locator, XMLReader
 
 START_ELEMENT: Final = "START_ELEMENT"
 END_ELEMENT: Final = "END_ELEMENT"
@@ -16,79 +17,93 @@ PROCESSING_INSTRUCTION: Final = "PROCESSING_INSTRUCTION"
 IGNORABLE_WHITESPACE: Final = "IGNORABLE_WHITESPACE"
 CHARACTERS: Final = "CHARACTERS"
 
+_NSName: TypeAlias = tuple[str | None, str]
 _DocumentFactory: TypeAlias = DOMImplementation | None
-_Node: TypeAlias = Document | Element | Text
 
-_Event: TypeAlias = tuple[
-    Literal[
-        Literal["START_ELEMENT"],
-        Literal["END_ELEMENT"],
-        Literal["COMMENT"],
-        Literal["START_DOCUMENT"],
-        Literal["END_DOCUMENT"],
-        Literal["PROCESSING_INSTRUCTION"],
-        Literal["IGNORABLE_WHITESPACE"],
-        Literal["CHARACTERS"],
-    ],
-    _Node,
-]
+_Event: TypeAlias = (
+    tuple[Literal["START_ELEMENT"], Element]
+    | tuple[Literal["END_ELEMENT"], Element]
+    | tuple[Literal["COMMENT"], Comment]
+    | tuple[Literal["START_DOCUMENT"], Document]
+    | tuple[Literal["END_DOCUMENT"], Document]
+    | tuple[Literal["PROCESSING_INSTRUCTION"], ProcessingInstruction]
+    | tuple[Literal["IGNORABLE_WHITESPACE"], Text]
+    | tuple[Literal["CHARACTERS"], Text]
+)
 
 class PullDOM(ContentHandler):
     document: Document | None
     documentFactory: _DocumentFactory
-    firstEvent: Incomplete
-    lastEvent: Incomplete
-    elementStack: Sequence[Incomplete]
-    pending_events: Sequence[Incomplete]
+
+    # firstEvent is a list of length 2
+    # firstEvent[0] is always None
+    # firstEvent[1] is None prior to any events, after which it's a
+    # list of length 2, where the first item is of type _Event
+    # and the second item is None.
+    firstEvent: list[Incomplete]
+
+    # lastEvent is also a list of length 2. The second item is always None,
+    # and the first item is of type _Event
+    # This is a slight lie: The second item is sometimes temporarily what was just
+    # described for the type of lastEvent, after which lastEvent is always updated
+    # with `self.lastEvent = self.lastEvent[1]`.
+    lastEvent: list[Incomplete]
+
+    elementStack: MutableSequence[Element | Document]
+    pending_events: (
+        list[Sequence[tuple[Literal["COMMENT"], str] | tuple[Literal["PROCESSING_INSTRUCTION"], str, str] | None]] | None
+    )
     def __init__(self, documentFactory: _DocumentFactory = None) -> None: ...
-    def pop(self) -> Element: ...
-    def setDocumentLocator(self, locator) -> None: ...
-    def startPrefixMapping(self, prefix, uri) -> None: ...
-    def endPrefixMapping(self, prefix) -> None: ...
-    def startElementNS(self, name, tagName, attrs) -> None: ...
-    def endElementNS(self, name, tagName) -> None: ...
-    def startElement(self, name, attrs) -> None: ...
-    def endElement(self, name) -> None: ...
-    def comment(self, s) -> None: ...
-    def processingInstruction(self, target, data) -> None: ...
-    def ignorableWhitespace(self, chars) -> None: ...
-    def characters(self, chars) -> None: ...
+    def pop(self) -> Element | Document: ...
+    def setDocumentLocator(self, locator: Locator) -> None: ...
+    def startPrefixMapping(self, prefix: str | None, uri: str) -> None: ...
+    def endPrefixMapping(self, prefix: str | None) -> None: ...
+    def startElementNS(self, name: _NSName, tagName: str | None, attrs: AttributesNSImpl) -> None: ...
+    def endElementNS(self, name: _NSName, tagName: str | None) -> None: ...
+    def startElement(self, name: str, attrs: AttributesImpl) -> None: ...
+    def endElement(self, name: str) -> None: ...
+    def comment(self, s: str) -> None: ...
+    def processingInstruction(self, target: str, data: str) -> None: ...
+    def ignorableWhitespace(self, chars: str) -> None: ...
+    def characters(self, chars: str) -> None: ...
     def startDocument(self) -> None: ...
-    def buildDocument(self, uri, tagname): ...
+    def buildDocument(self, uri: str | None, tagname: str | None) -> Element: ...
     def endDocument(self) -> None: ...
     def clear(self) -> None: ...
 
 class ErrorHandler:
-    def warning(self, exception) -> None: ...
-    def error(self, exception) -> None: ...
-    def fatalError(self, exception) -> None: ...
+    def warning(self, exception: BaseException) -> None: ...
+    def error(self, exception: BaseException) -> NoReturn: ...
+    def fatalError(self, exception: BaseException) -> NoReturn: ...
 
 class DOMEventStream:
-    stream: SupportsRead[bytes] | SupportsRead[str]
-    parser: XMLReader
+    stream: _SupportsReadClose[bytes] | _SupportsReadClose[str]
+    parser: XMLReader  # Set to none after .clear() is called
     bufsize: int
-    def __init__(self, stream: SupportsRead[bytes] | SupportsRead[str], parser: XMLReader, bufsize: int) -> None: ...
-    pulldom: Incomplete
+    pulldom: PullDOM
+    def __init__(self, stream: _SupportsReadClose[bytes] | _SupportsReadClose[str], parser: XMLReader, bufsize: int) -> None: ...
     if sys.version_info < (3, 11):
-        def __getitem__(self, pos): ...
+        def __getitem__(self, pos: Unused) -> _Event: ...
 
-    def __next__(self): ...
-    def __iter__(self): ...
-    def getEvent(self) -> _Event: ...
-    def expandNode(self, node: _Node) -> None: ...
+    def __next__(self) -> _Event: ...
+    def __iter__(self) -> Self: ...
+    def getEvent(self) -> _Event | None: ...
+    def expandNode(self, node: Document) -> None: ...
     def reset(self) -> None: ...
     def clear(self) -> None: ...
 
 class SAX2DOM(PullDOM):
-    def startElementNS(self, name, tagName, attrs) -> None: ...
-    def startElement(self, name, attrs) -> None: ...
-    def processingInstruction(self, target, data) -> None: ...
-    def ignorableWhitespace(self, chars) -> None: ...
-    def characters(self, chars) -> None: ...
+    def startElementNS(self, name: _NSName, tagName: str | None, attrs: AttributesNSImpl) -> None: ...
+    def startElement(self, name: str, attrs: AttributesImpl) -> None: ...
+    def processingInstruction(self, target: str, data: str) -> None: ...
+    def ignorableWhitespace(self, chars: str) -> None: ...
+    def characters(self, chars: str) -> None: ...
 
 default_bufsize: int
 
 def parse(
-    stream_or_string: str | SupportsRead[bytes] | SupportsRead[str], parser: XMLReader | None = None, bufsize: int | None = None
+    stream_or_string: str | _SupportsReadClose[bytes] | _SupportsReadClose[str],
+    parser: XMLReader | None = None,
+    bufsize: int | None = None,
 ) -> DOMEventStream: ...
 def parseString(string: str, parser: XMLReader | None = None) -> DOMEventStream: ...

package/dist/typeshed-fallback/stdlib/xml/dom/xmlbuilder.pyi

@@ -1,32 +1,9 @@
-from _typeshed import Incomplete, Unused
+from _typeshed import SupportsRead
 from typing import Any, Literal, NoReturn
-from typing_extensions import TypeAlias
-from urllib.request import OpenerDirector
-from xml.dom.expatbuilder import ExpatBuilder, ExpatBuilderNS
-from xml.dom.minidom import Node
+from xml.dom.minidom import Document, Node, _DOMErrorHandler
 
 __all__ = ["DOMBuilder", "DOMEntityResolver", "DOMInputSource"]
 
-# UNKNOWN TYPES:
-# - `Options.errorHandler`.
-#       The same as `_DOMBuilderErrorHandlerType`?
-#       Maybe `xml.sax.handler.ErrorHandler`?
-# - Return type of DOMBuilder.getFeature().
-#       We could get rid of the `Incomplete` if we knew more
-#       about `Options.errorHandler`.
-
-# ALIASES REPRESENTING MORE UNKNOWN TYPES:
-
-# probably the same as `Options.errorHandler`?
-# Maybe `xml.sax.handler.ErrorHandler`?
-_DOMBuilderErrorHandlerType: TypeAlias = Incomplete | None
-# probably some kind of IO...
-_DOMInputSourceCharacterStreamType: TypeAlias = Incomplete | None
-# probably a string??
-_DOMInputSourceStringDataType: TypeAlias = Incomplete | None
-# probably a string??
-_DOMInputSourceEncodingType: TypeAlias = Incomplete | None
-
 class Options:
     namespaces: int
     namespace_declarations: bool
@@ -45,37 +22,35 @@ class Options:
     charset_overrides_xml_encoding: bool
     infoset: bool
     supported_mediatypes_only: bool
-    errorHandler: Any | None
-    filter: DOMBuilderFilter | None  # a guess, but seems likely
+    errorHandler: _DOMErrorHandler | None
+    filter: DOMBuilderFilter | None
 
 class DOMBuilder:
-    entityResolver: DOMEntityResolver | None  # a guess, but seems likely
-    errorHandler: _DOMBuilderErrorHandlerType
-    filter: DOMBuilderFilter | None  # a guess, but seems likely
+    entityResolver: DOMEntityResolver | None
+    errorHandler: _DOMErrorHandler | None
+    filter: DOMBuilderFilter | None
     ACTION_REPLACE: Literal[1]
     ACTION_APPEND_AS_CHILDREN: Literal[2]
     ACTION_INSERT_AFTER: Literal[3]
     ACTION_INSERT_BEFORE: Literal[4]
+    def __init__(self) -> None: ...
     def setFeature(self, name: str, state: int) -> None: ...
     def supportsFeature(self, name: str) -> bool: ...
-    def canSetFeature(self, name: str, state: int) -> bool: ...
+    def canSetFeature(self, name: str, state: Literal[1, 0]) -> bool: ...
     # getFeature could return any attribute from an instance of `Options`
     def getFeature(self, name: str) -> Any: ...
-    def parseURI(self, uri: str) -> ExpatBuilder | ExpatBuilderNS: ...
-    def parse(self, input: DOMInputSource) -> ExpatBuilder | ExpatBuilderNS: ...
-    # `input` and `cnode` argtypes for `parseWithContext` are unknowable
-    # as the function does nothing with them, and always raises an exception.
-    # But `input` is *probably* `DOMInputSource`?
-    def parseWithContext(self, input: Unused, cnode: Unused, action: Literal[1, 2, 3, 4]) -> NoReturn: ...
+    def parseURI(self, uri: str) -> Document: ...
+    def parse(self, input: DOMInputSource) -> Document: ...
+    def parseWithContext(self, input: DOMInputSource, cnode: Node, action: Literal[1, 2, 3, 4]) -> NoReturn: ...
 
 class DOMEntityResolver:
     def resolveEntity(self, publicId: str | None, systemId: str) -> DOMInputSource: ...
 
 class DOMInputSource:
-    byteStream: OpenerDirector | None
-    characterStream: _DOMInputSourceCharacterStreamType
-    stringData: _DOMInputSourceStringDataType
-    encoding: _DOMInputSourceEncodingType
+    byteStream: SupportsRead[bytes] | None
+    characterStream: SupportsRead[str] | None
+    stringData: str | None
+    encoding: str | None
     publicId: str | None
     systemId: str | None
     baseURI: str | None
@@ -86,18 +61,14 @@ class DOMBuilderFilter:
     FILTER_SKIP: Literal[3]
     FILTER_INTERRUPT: Literal[4]
     whatToShow: int
-    def acceptNode(self, element: Unused) -> Literal[1]: ...
-    def startContainer(self, element: Unused) -> Literal[1]: ...
+    def acceptNode(self, element: Node) -> Literal[1, 2, 3, 4]: ...
+    def startContainer(self, element: Node) -> Literal[1, 2, 3, 4]: ...
 
 class DocumentLS:
     async_: bool
     def abort(self) -> NoReturn: ...
-    # `load()` and `loadXML()` always raise exceptions
-    # so the argtypes of `uri` and `source` are unknowable.
-    # `source` is *probably* `DOMInputSource`?
-    # `uri` is *probably* a str? (see DOMBuilder.parseURI())
-    def load(self, uri: Unused) -> NoReturn: ...
-    def loadXML(self, source: Unused) -> NoReturn: ...
+    def load(self, uri: str) -> NoReturn: ...
+    def loadXML(self, source: str) -> NoReturn: ...
     def saveXML(self, snode: Node | None) -> str: ...
 
 class DOMImplementationLS:

package/dist/typeshed-fallback/stdlib/xml/etree/ElementInclude.pyi

@@ -1,9 +1,14 @@
 import sys
 from _typeshed import FileDescriptorOrPath
-from collections.abc import Callable
-from typing import Final
+from typing import Final, Literal, Protocol, overload
 from xml.etree.ElementTree import Element
 
+class _Loader(Protocol):
+    @overload
+    def __call__(self, href: FileDescriptorOrPath, parse: Literal["xml"], encoding: str | None = None) -> Element: ...
+    @overload
+    def __call__(self, href: FileDescriptorOrPath, parse: Literal["text"], encoding: str | None = None) -> str: ...
+
 XINCLUDE: Final[str]
 XINCLUDE_INCLUDE: Final[str]
 XINCLUDE_FALLBACK: Final[str]
@@ -13,17 +18,15 @@ if sys.version_info >= (3, 9):
 
 class FatalIncludeError(SyntaxError): ...
 
-def default_loader(href: FileDescriptorOrPath, parse: str, encoding: str | None = None) -> str | Element: ...
+@overload
+def default_loader(href: FileDescriptorOrPath, parse: Literal["xml"], encoding: str | None = None) -> Element: ...
+@overload
+def default_loader(href: FileDescriptorOrPath, parse: Literal["text"], encoding: str | None = None) -> str: ...
 
-# TODO: loader is of type default_loader ie it takes a callable that has the
-# same signature as default_loader. But default_loader has a keyword argument
-# Which can't be represented using Callable...
 if sys.version_info >= (3, 9):
-    def include(
-        elem: Element, loader: Callable[..., str | Element] | None = None, base_url: str | None = None, max_depth: int | None = 6
-    ) -> None: ...
+    def include(elem: Element, loader: _Loader | None = None, base_url: str | None = None, max_depth: int | None = 6) -> None: ...
 
     class LimitedRecursiveIncludeError(FatalIncludeError): ...
 
 else:
-    def include(elem: Element, loader: Callable[..., str | Element] | None = None) -> None: ...
+    def include(elem: Element, loader: _Loader | None = None) -> None: ...

package/dist/typeshed-fallback/stdlib/xml/etree/ElementPath.pyi

@@ -1,6 +1,6 @@
-from collections.abc import Callable, Generator
+from collections.abc import Callable, Generator, Iterable
 from re import Pattern
-from typing import TypeVar
+from typing import Any, Literal, TypeVar, overload
 from typing_extensions import TypeAlias
 from xml.etree.ElementTree import Element
 
@@ -8,27 +8,34 @@ xpath_tokenizer_re: Pattern[str]
 
 _Token: TypeAlias = tuple[str, str]
 _Next: TypeAlias = Callable[[], _Token]
-_Callback: TypeAlias = Callable[[_SelectorContext, list[Element]], Generator[Element, None, None]]
+_Callback: TypeAlias = Callable[[_SelectorContext, Iterable[Element]], Generator[Element, None, None]]
+_T = TypeVar("_T")
 
 def xpath_tokenizer(pattern: str, namespaces: dict[str, str] | None = None) -> Generator[_Token, None, None]: ...
 def get_parent_map(context: _SelectorContext) -> dict[Element, Element]: ...
 def prepare_child(next: _Next, token: _Token) -> _Callback: ...
 def prepare_star(next: _Next, token: _Token) -> _Callback: ...
 def prepare_self(next: _Next, token: _Token) -> _Callback: ...
-def prepare_descendant(next: _Next, token: _Token) -> _Callback: ...
+def prepare_descendant(next: _Next, token: _Token) -> _Callback | None: ...
 def prepare_parent(next: _Next, token: _Token) -> _Callback: ...
-def prepare_predicate(next: _Next, token: _Token) -> _Callback: ...
+def prepare_predicate(next: _Next, token: _Token) -> _Callback | None: ...
 
-ops: dict[str, Callable[[_Next, _Token], _Callback]]
+ops: dict[str, Callable[[_Next, _Token], _Callback | None]]
 
 class _SelectorContext:
     parent_map: dict[Element, Element] | None
     root: Element
     def __init__(self, root: Element) -> None: ...
 
-_T = TypeVar("_T")
-
-def iterfind(elem: Element, path: str, namespaces: dict[str, str] | None = None) -> Generator[Element, None, None]: ...
-def find(elem: Element, path: str, namespaces: dict[str, str] | None = None) -> Element | None: ...
-def findall(elem: Element, path: str, namespaces: dict[str, str] | None = None) -> list[Element]: ...
-def findtext(elem: Element, path: str, default: _T | None = None, namespaces: dict[str, str] | None = None) -> _T | str: ...
+@overload
+def iterfind(  # type: ignore[overload-overlap]
+    elem: Element[Any], path: Literal[""], namespaces: dict[str, str] | None = None
+) -> None: ...
+@overload
+def iterfind(elem: Element[Any], path: str, namespaces: dict[str, str] | None = None) -> Generator[Element, None, None]: ...
+def find(elem: Element[Any], path: str, namespaces: dict[str, str] | None = None) -> Element | None: ...
+def findall(elem: Element[Any], path: str, namespaces: dict[str, str] | None = None) -> list[Element]: ...
+@overload
+def findtext(elem: Element[Any], path: str, default: None = None, namespaces: dict[str, str] | None = None) -> str | None: ...
+@overload
+def findtext(elem: Element[Any], path: str, default: _T, namespaces: dict[str, str] | None = None) -> _T | str: ...

package/dist/typeshed-fallback/stdlib/xml/etree/ElementTree.pyi

@@ -2,8 +2,9 @@ import sys
 from _collections_abc import dict_keys
 from _typeshed import FileDescriptorOrPath, ReadableBuffer, SupportsRead, SupportsWrite
 from collections.abc import Callable, Generator, ItemsView, Iterable, Iterator, Mapping, Sequence
-from typing import Any, Final, Literal, SupportsIndex, TypeVar, overload
+from typing import Any, Final, Generic, Literal, Protocol, SupportsIndex, TypeVar, overload, type_check_only
 from typing_extensions import TypeAlias, TypeGuard, deprecated
+from xml.parsers.expat import XMLParserType
 
 __all__ = [
     "C14NWriterTarget",
@@ -78,13 +79,22 @@ def canonicalize(
     exclude_tags: Iterable[str] | None = None,
 ) -> None: ...
 
-class Element:
-    tag: str
+# The tag for Element can be set to the Comment or ProcessingInstruction
+# functions defined in this module. _ElementCallable could be a recursive
+# type, but defining it that way uncovered a bug in pytype.
+_ElementCallable: TypeAlias = Callable[..., Element[Any]]
+_CallableElement: TypeAlias = Element[_ElementCallable]
+
+_Tag = TypeVar("_Tag", default=str, bound=str | _ElementCallable)
+_OtherTag = TypeVar("_OtherTag", default=str, bound=str | _ElementCallable)
+
+class Element(Generic[_Tag]):
+    tag: _Tag
     attrib: dict[str, str]
     text: str | None
     tail: str | None
-    def __init__(self, tag: str, attrib: dict[str, str] = ..., **extra: str) -> None: ...
-    def append(self, subelement: Element, /) -> None: ...
+    def __init__(self, tag: _Tag, attrib: dict[str, str] = {}, **extra: str) -> None: ...
+    def append(self, subelement: Element[Any], /) -> None: ...
     def clear(self) -> None: ...
     def extend(self, elements: Iterable[Element], /) -> None: ...
     def find(self, path: str, namespaces: dict[str, str] | None = None) -> Element | None: ...
@@ -100,14 +110,17 @@ class Element:
     def insert(self, index: int, subelement: Element, /) -> None: ...
     def items(self) -> ItemsView[str, str]: ...
     def iter(self, tag: str | None = None) -> Generator[Element, None, None]: ...
+    @overload
+    def iterfind(self, path: Literal[""], namespaces: dict[str, str] | None = None) -> None: ...  # type: ignore[overload-overlap]
+    @overload
     def iterfind(self, path: str, namespaces: dict[str, str] | None = None) -> Generator[Element, None, None]: ...
     def itertext(self) -> Generator[str, None, None]: ...
     def keys(self) -> dict_keys[str, str]: ...
     # makeelement returns the type of self in Python impl, but not in C impl
-    def makeelement(self, tag: str, attrib: dict[str, str], /) -> Element: ...
+    def makeelement(self, tag: _OtherTag, attrib: dict[str, str], /) -> Element[_OtherTag]: ...
     def remove(self, subelement: Element, /) -> None: ...
     def set(self, key: str, value: str, /) -> None: ...
-    def __copy__(self) -> Element: ...  # returns the type of self in Python impl, but not in C impl
+    def __copy__(self) -> Element[_Tag]: ...  # returns the type of self in Python impl, but not in C impl
     def __deepcopy__(self, memo: Any, /) -> Element: ...  # Only exists in C impl
     def __delitem__(self, key: SupportsIndex | slice, /) -> None:
         """Delete self[key]."""
@@ -144,8 +157,8 @@ class Element:
         def getiterator(self, tag: str | None = None) -> list[Element]: ...
 
 def SubElement(parent: Element, tag: str, attrib: dict[str, str] = ..., **extra: str) -> Element: ...
-def Comment(text: str | None = None) -> Element: ...
-def ProcessingInstruction(target: str, text: str | None = None) -> Element: ...
+def Comment(text: str | None = None) -> _CallableElement: ...
+def ProcessingInstruction(target: str, text: str | None = None) -> _CallableElement: ...
 
 PI = ProcessingInstruction
 
@@ -159,9 +172,11 @@ class QName:
     def __eq__(self, other: object) -> bool: ...
     def __hash__(self) -> int: ...
 
-class ElementTree:
+_Root = TypeVar("_Root", Element, Element | None, default=Element | None)
+
+class ElementTree(Generic[_Root]):
     def __init__(self, element: Element | None = None, file: _FileRead | None = None) -> None: ...
-    def getroot(self) -> Element | Any: ...
+    def getroot(self) -> _Root: ...
     def parse(self, source: _FileRead, parser: XMLParser | None = None) -> Element: ...
     def iter(self, tag: str | None = None) -> Generator[Element, None, None]: ...
     if sys.version_info < (3, 9):
@@ -173,6 +188,9 @@ class ElementTree:
     @overload
     def findtext(self, path: str, default: _T, namespaces: dict[str, str] | None = None) -> _T | str: ...
     def findall(self, path: str, namespaces: dict[str, str] | None = None) -> list[Element]: ...
+    @overload
+    def iterfind(self, path: Literal[""], namespaces: dict[str, str] | None = None) -> None: ...  # type: ignore[overload-overlap]
+    @overload
     def iterfind(self, path: str, namespaces: dict[str, str] | None = None) -> Generator[Element, None, None]: ...
     def write(
         self,
@@ -180,18 +198,20 @@ class ElementTree:
         encoding: str | None = None,
         xml_declaration: bool | None = None,
         default_namespace: str | None = None,
-        method: str | None = None,
+        method: Literal["xml", "html", "text", "c14n"] | None = None,
         *,
         short_empty_elements: bool = True,
     ) -> None: ...
     def write_c14n(self, file: _FileWriteC14N) -> None: ...
 
+HTML_EMPTY: set[str]
+
 def register_namespace(prefix: str, uri: str) -> None: ...
 @overload
 def tostring(
     element: Element,
     encoding: None = None,
-    method: str | None = None,
+    method: Literal["xml", "html", "text", "c14n"] | None = None,
     *,
     xml_declaration: bool | None = None,
     default_namespace: str | None = None,
@@ -201,7 +221,7 @@ def tostring(
 def tostring(
     element: Element,
     encoding: Literal["unicode"],
-    method: str | None = None,
+    method: Literal["xml", "html", "text", "c14n"] | None = None,
     *,
     xml_declaration: bool | None = None,
     default_namespace: str | None = None,
@@ -211,7 +231,7 @@ def tostring(
 def tostring(
     element: Element,
     encoding: str,
-    method: str | None = None,
+    method: Literal["xml", "html", "text", "c14n"] | None = None,
     *,
     xml_declaration: bool | None = None,
     default_namespace: str | None = None,
@@ -221,7 +241,7 @@ def tostring(
 def tostringlist(
     element: Element,
     encoding: None = None,
-    method: str | None = None,
+    method: Literal["xml", "html", "text", "c14n"] | None = None,
     *,
     xml_declaration: bool | None = None,
     default_namespace: str | None = None,
@@ -231,7 +251,7 @@ def tostringlist(
 def tostringlist(
     element: Element,
     encoding: Literal["unicode"],
-    method: str | None = None,
+    method: Literal["xml", "html", "text", "c14n"] | None = None,
     *,
     xml_declaration: bool | None = None,
     default_namespace: str | None = None,
@@ -241,21 +261,23 @@ def tostringlist(
 def tostringlist(
     element: Element,
     encoding: str,
-    method: str | None = None,
+    method: Literal["xml", "html", "text", "c14n"] | None = None,
     *,
     xml_declaration: bool | None = None,
     default_namespace: str | None = None,
     short_empty_elements: bool = True,
 ) -> list[Any]: ...
-def dump(elem: Element) -> None: ...
+def dump(elem: Element | ElementTree[Any]) -> None: ...
 
 if sys.version_info >= (3, 9):
-    def indent(tree: Element | ElementTree, space: str = "  ", level: int = 0) -> None: ...
+    def indent(tree: Element | ElementTree[Any], space: str = "  ", level: int = 0) -> None: ...
 
-def parse(source: _FileRead, parser: XMLParser | None = None) -> ElementTree: ...
+def parse(source: _FileRead, parser: XMLParser[Any] | None = None) -> ElementTree[Element]: ...
 
-class _IterParseIterator(Iterator[tuple[str, Any]]):
-    def __next__(self) -> tuple[str, Any]: ...
+# This class is defined inside the body of iterparse
+@type_check_only
+class _IterParseIterator(Iterator[tuple[str, Element]], Protocol):
+    def __next__(self) -> tuple[str, Element]: ...
     if sys.version_info >= (3, 13):
         def close(self) -> None: ...
     if sys.version_info >= (3, 11):
@@ -263,13 +285,13 @@ class _IterParseIterator(Iterator[tuple[str, Any]]):
 
 def iterparse(source: _FileRead, events: Sequence[str] | None = None, parser: XMLParser | None = None) -> _IterParseIterator: ...
 
-class XMLPullParser:
-    def __init__(self, events: Sequence[str] | None = None, *, _parser: XMLParser | None = None) -> None: ...
+_EventQueue: TypeAlias = tuple[str] | tuple[str, tuple[str, str]] | tuple[str, None]
+
+class XMLPullParser(Generic[_E]):
+    def __init__(self, events: Sequence[str] | None = None, *, _parser: XMLParser[_E] | None = None) -> None: ...
     def feed(self, data: str | ReadableBuffer) -> None: ...
     def close(self) -> None: ...
-    # Second element in the tuple could be `Element`, `tuple[str, str]` or `None`.
-    # Use `Any` to avoid false-positive errors.
-    def read_events(self) -> Iterator[tuple[str, Any]]: ...
+    def read_events(self) -> Iterator[_EventQueue | tuple[str, _E]]: ...
     def flush(self) -> None: ...
 
 def XML(text: str | ReadableBuffer, parser: XMLParser | None = None) -> Element: ...
@@ -295,12 +317,12 @@ class TreeBuilder:
     # comment_factory can take None because passing None to Comment is not an error
     def __init__(
         self,
-        element_factory: _ElementFactory | None = ...,
+        element_factory: _ElementFactory | None = None,
         *,
-        comment_factory: Callable[[str | None], Element] | None = ...,
-        pi_factory: Callable[[str, str | None], Element] | None = ...,
-        insert_comments: bool = ...,
-        insert_pis: bool = ...,
+        comment_factory: Callable[[str | None], Element[Any]] | None = None,
+        pi_factory: Callable[[str, str | None], Element[Any]] | None = None,
+        insert_comments: bool = False,
+        insert_pis: bool = False,
     ) -> None: ...
     insert_comments: bool
     insert_pis: bool
@@ -312,8 +334,8 @@ class TreeBuilder:
     def start(self, tag: Any, attrs: dict[Any, Any], /) -> Element: ...
     def end(self, tag: str, /) -> Element: ...
     # These two methods have pos-only parameters in the C implementation
-    def comment(self, text: str | None, /) -> Element: ...
-    def pi(self, target: str, text: str | None = None, /) -> Element: ...
+    def comment(self, text: str | None, /) -> Element[Any]: ...
+    def pi(self, target: str, text: str | None = None, /) -> Element[Any]: ...
 
 class C14NWriterTarget:
     def __init__(
@@ -335,13 +357,33 @@ class C14NWriterTarget:
     def comment(self, text: str) -> None: ...
     def pi(self, target: str, data: str) -> None: ...
 
-class XMLParser:
-    parser: Any
-    target: Any
+# The target type is tricky, because the implementation doesn't
+# require any particular attribute to be present. This documents the attributes
+# that can be present, but uncommenting any of them would require them.
+class _Target(Protocol):
+    # start: Callable[str, dict[str, str], Any] | None
+    # end: Callable[[str], Any] | None
+    # start_ns: Callable[[str, str], Any] | None
+    # end_ns: Callable[[str], Any] | None
+    # data: Callable[[str], Any] | None
+    # comment: Callable[[str], Any]
+    # pi: Callable[[str, str], Any] | None
+    # close: Callable[[], Any] | None
+    ...
+
+_E = TypeVar("_E", default=Element)
+
+# This is generic because the return type of close() depends on the target.
+# The default target is TreeBuilder, which returns Element.
+# C14NWriterTarget does not implement a close method, so using it results
+# in a type of XMLParser[None].
+class XMLParser(Generic[_E]):
+    parser: XMLParserType
+    target: _Target
     # TODO-what is entity used for???
-    entity: Any
+    entity: dict[str, str]
     version: str
-    def __init__(self, *, target: Any = ..., encoding: str | None = ...) -> None: ...
-    def close(self) -> Any: ...
+    def __init__(self, *, target: _Target | None = None, encoding: str | None = None) -> None: ...
+    def close(self) -> _E: ...
     def feed(self, data: str | ReadableBuffer, /) -> None: ...
     def flush(self) -> None: ...

package/dist/typeshed-fallback/stdlib/xml/sax/_exceptions.pyi

@@ -4,15 +4,15 @@ from xml.sax.xmlreader import Locator
 class SAXException(Exception):
     def __init__(self, msg: str, exception: Exception | None = None) -> None: ...
     def getMessage(self) -> str: ...
-    def getException(self) -> Exception: ...
+    def getException(self) -> Exception | None: ...
     def __getitem__(self, ix: object) -> NoReturn: ...
 
 class SAXParseException(SAXException):
     def __init__(self, msg: str, exception: Exception | None, locator: Locator) -> None: ...
-    def getColumnNumber(self) -> int: ...
-    def getLineNumber(self) -> int: ...
-    def getPublicId(self): ...
-    def getSystemId(self): ...
+    def getColumnNumber(self) -> int | None: ...
+    def getLineNumber(self) -> int | None: ...
+    def getPublicId(self) -> str | None: ...
+    def getSystemId(self) -> str | None: ...
 
 class SAXNotRecognizedException(SAXException): ...
 class SAXNotSupportedException(SAXException): ...