Major update for the xml module (#13349)

stdlib/xml/dom/NodeFilter.pyi

@@ -1,7 +1,10 @@
+from typing import Literal
+from xml.dom.minidom import Node
+
 class NodeFilter:
-    FILTER_ACCEPT: int
-    FILTER_REJECT: int
-    FILTER_SKIP: int
+    FILTER_ACCEPT: Literal[1]
+    FILTER_REJECT: Literal[2]
+    FILTER_SKIP: Literal[3]
 
     SHOW_ALL: int
     SHOW_ELEMENT: int
@@ -16,4 +19,4 @@ class NodeFilter:
     SHOW_DOCUMENT_TYPE: int
     SHOW_DOCUMENT_FRAGMENT: int
     SHOW_NOTATION: int
-    def acceptNode(self, node) -> int: ...
+    def acceptNode(self, node: Node) -> int: ...

stdlib/xml/dom/__init__.pyi

@@ -1,69 +1,100 @@
-from typing import Any, Final
+from typing import Any, Final, Literal
 
 from .domreg import getDOMImplementation as getDOMImplementation, registerDOMImplementation as registerDOMImplementation
 
 class Node:
-    ELEMENT_NODE: int
-    ATTRIBUTE_NODE: int
-    TEXT_NODE: int
-    CDATA_SECTION_NODE: int
-    ENTITY_REFERENCE_NODE: int
-    ENTITY_NODE: int
-    PROCESSING_INSTRUCTION_NODE: int
-    COMMENT_NODE: int
-    DOCUMENT_NODE: int
-    DOCUMENT_TYPE_NODE: int
-    DOCUMENT_FRAGMENT_NODE: int
-    NOTATION_NODE: int
+    ELEMENT_NODE: Literal[1]
+    ATTRIBUTE_NODE: Literal[2]
+    TEXT_NODE: Literal[3]
+    CDATA_SECTION_NODE: Literal[4]
+    ENTITY_REFERENCE_NODE: Literal[5]
+    ENTITY_NODE: Literal[6]
+    PROCESSING_INSTRUCTION_NODE: Literal[7]
+    COMMENT_NODE: Literal[8]
+    DOCUMENT_NODE: Literal[9]
+    DOCUMENT_TYPE_NODE: Literal[10]
+    DOCUMENT_FRAGMENT_NODE: Literal[11]
+    NOTATION_NODE: Literal[12]
 
 # ExceptionCode
-INDEX_SIZE_ERR: Final[int]
-DOMSTRING_SIZE_ERR: Final[int]
-HIERARCHY_REQUEST_ERR: Final[int]
-WRONG_DOCUMENT_ERR: Final[int]
-INVALID_CHARACTER_ERR: Final[int]
-NO_DATA_ALLOWED_ERR: Final[int]
-NO_MODIFICATION_ALLOWED_ERR: Final[int]
-NOT_FOUND_ERR: Final[int]
-NOT_SUPPORTED_ERR: Final[int]
-INUSE_ATTRIBUTE_ERR: Final[int]
-INVALID_STATE_ERR: Final[int]
-SYNTAX_ERR: Final[int]
-INVALID_MODIFICATION_ERR: Final[int]
-NAMESPACE_ERR: Final[int]
-INVALID_ACCESS_ERR: Final[int]
-VALIDATION_ERR: Final[int]
+INDEX_SIZE_ERR: Final = 1
+DOMSTRING_SIZE_ERR: Final = 2
+HIERARCHY_REQUEST_ERR: Final = 3
+WRONG_DOCUMENT_ERR: Final = 4
+INVALID_CHARACTER_ERR: Final = 5
+NO_DATA_ALLOWED_ERR: Final = 6
+NO_MODIFICATION_ALLOWED_ERR: Final = 7
+NOT_FOUND_ERR: Final = 8
+NOT_SUPPORTED_ERR: Final = 9
+INUSE_ATTRIBUTE_ERR: Final = 10
+INVALID_STATE_ERR: Final = 11
+SYNTAX_ERR: Final = 12
+INVALID_MODIFICATION_ERR: Final = 13
+NAMESPACE_ERR: Final = 14
+INVALID_ACCESS_ERR: Final = 15
+VALIDATION_ERR: Final = 16
 
 class DOMException(Exception):
     code: int
     def __init__(self, *args: Any, **kw: Any) -> None: ...
     def _get_code(self) -> int: ...
 
-class IndexSizeErr(DOMException): ...
-class DomstringSizeErr(DOMException): ...
-class HierarchyRequestErr(DOMException): ...
-class WrongDocumentErr(DOMException): ...
-class InvalidCharacterErr(DOMException): ...
-class NoDataAllowedErr(DOMException): ...
-class NoModificationAllowedErr(DOMException): ...
-class NotFoundErr(DOMException): ...
-class NotSupportedErr(DOMException): ...
-class InuseAttributeErr(DOMException): ...
-class InvalidStateErr(DOMException): ...
-class SyntaxErr(DOMException): ...
-class InvalidModificationErr(DOMException): ...
-class NamespaceErr(DOMException): ...
-class InvalidAccessErr(DOMException): ...
-class ValidationErr(DOMException): ...
+class IndexSizeErr(DOMException):
+    code: Literal[1]
+
+class DomstringSizeErr(DOMException):
+    code: Literal[2]
+
+class HierarchyRequestErr(DOMException):
+    code: Literal[3]
+
+class WrongDocumentErr(DOMException):
+    code: Literal[4]
+
+class InvalidCharacterErr(DOMException):
+    code: Literal[5]
+
+class NoDataAllowedErr(DOMException):
+    code: Literal[6]
+
+class NoModificationAllowedErr(DOMException):
+    code: Literal[7]
+
+class NotFoundErr(DOMException):
+    code: Literal[8]
+
+class NotSupportedErr(DOMException):
+    code: Literal[9]
+
+class InuseAttributeErr(DOMException):
+    code: Literal[10]
+
+class InvalidStateErr(DOMException):
+    code: Literal[11]
+
+class SyntaxErr(DOMException):
+    code: Literal[12]
+
+class InvalidModificationErr(DOMException):
+    code: Literal[13]
+
+class NamespaceErr(DOMException):
+    code: Literal[14]
+
+class InvalidAccessErr(DOMException):
+    code: Literal[15]
+
+class ValidationErr(DOMException):
+    code: Literal[16]
 
 class UserDataHandler:
-    NODE_CLONED: int
-    NODE_IMPORTED: int
-    NODE_DELETED: int
-    NODE_RENAMED: int
+    NODE_CLONED: Literal[1]
+    NODE_IMPORTED: Literal[2]
+    NODE_DELETED: Literal[3]
+    NODE_RENAMED: Literal[4]
 
-XML_NAMESPACE: Final[str]
-XMLNS_NAMESPACE: Final[str]
-XHTML_NAMESPACE: Final[str]
+XML_NAMESPACE: Final = "http://www.w3.org/XML/1998/namespace"
+XMLNS_NAMESPACE: Final = "http://www.w3.org/2000/xmlns/"
+XHTML_NAMESPACE: Final = "http://www.w3.org/1999/xhtml"
 EMPTY_NAMESPACE: Final[None]
 EMPTY_PREFIX: Final[None]

stdlib/xml/dom/expatbuilder.pyi

@@ -1,7 +1,11 @@
-from _typeshed import Incomplete, ReadableBuffer, SupportsRead
+from _typeshed import ReadableBuffer, SupportsRead
 from typing import Any, NoReturn
-from xml.dom.minidom import Document, DOMImplementation, Node, TypeInfo
+from typing_extensions import TypeAlias
+from xml.dom.minidom import Document, DocumentFragment, DOMImplementation, Element, Node, TypeInfo
 from xml.dom.xmlbuilder import DOMBuilderFilter, Options
+from xml.parsers.expat import XMLParserType
+
+_Model: TypeAlias = tuple[int, int, str | None, tuple[Any, ...]]  # same as in pyexpat
 
 TEXT_NODE = Node.TEXT_NODE
 CDATA_SECTION_NODE = Node.CDATA_SECTION_NODE
@@ -10,45 +14,56 @@ FILTER_ACCEPT = DOMBuilderFilter.FILTER_ACCEPT
 FILTER_REJECT = DOMBuilderFilter.FILTER_REJECT
 FILTER_SKIP = DOMBuilderFilter.FILTER_SKIP
 FILTER_INTERRUPT = DOMBuilderFilter.FILTER_INTERRUPT
-theDOMImplementation: DOMImplementation | None
+theDOMImplementation: DOMImplementation
 
 class ElementInfo:
-    tagName: Incomplete
-    def __init__(self, tagName, model: Incomplete | None = None) -> None: ...
-    def getAttributeType(self, aname) -> TypeInfo: ...
-    def getAttributeTypeNS(self, namespaceURI, localName) -> TypeInfo: ...
+    tagName: str
+    def __init__(self, tagName: str, model: _Model | None = None) -> None: ...
+    def getAttributeType(self, aname: str) -> TypeInfo: ...
+    def getAttributeTypeNS(self, namespaceURI: str | None, localName: str) -> TypeInfo: ...
     def isElementContent(self) -> bool: ...
     def isEmpty(self) -> bool: ...
-    def isId(self, aname) -> bool: ...
-    def isIdNS(self, euri, ename, auri, aname) -> bool: ...
+    def isId(self, aname: str) -> bool: ...
+    def isIdNS(self, euri: str, ename: str, auri: str, aname: str) -> bool: ...
 
 class ExpatBuilder:
     document: Document  # Created in self.reset()
-    curNode: Incomplete  # Created in self.reset()
+    curNode: DocumentFragment | Element | Document  # Created in self.reset()
     def __init__(self, options: Options | None = None) -> None: ...
-    def createParser(self): ...
-    def getParser(self): ...
+    def createParser(self) -> XMLParserType: ...
+    def getParser(self) -> XMLParserType: ...
     def reset(self) -> None: ...
-    def install(self, parser) -> None: ...
+    def install(self, parser: XMLParserType) -> None: ...
     def parseFile(self, file: SupportsRead[ReadableBuffer | str]) -> Document: ...
     def parseString(self, string: str | ReadableBuffer) -> Document: ...
-    def start_doctype_decl_handler(self, doctypeName, systemId, publicId, has_internal_subset) -> None: ...
+    def start_doctype_decl_handler(
+        self, doctypeName: str, systemId: str | None, publicId: str | None, has_internal_subset: bool
+    ) -> None: ...
     def end_doctype_decl_handler(self) -> None: ...
-    def pi_handler(self, target, data) -> None: ...
-    def character_data_handler_cdata(self, data) -> None: ...
-    def character_data_handler(self, data) -> None: ...
+    def pi_handler(self, target: str, data: str) -> None: ...
+    def character_data_handler_cdata(self, data: str) -> None: ...
+    def character_data_handler(self, data: str) -> None: ...
     def start_cdata_section_handler(self) -> None: ...
     def end_cdata_section_handler(self) -> None: ...
-    def entity_decl_handler(self, entityName, is_parameter_entity, value, base, systemId, publicId, notationName) -> None: ...
-    def notation_decl_handler(self, notationName, base, systemId, publicId) -> None: ...
-    def comment_handler(self, data) -> None: ...
-    def external_entity_ref_handler(self, context, base, systemId, publicId) -> int: ...
-    def first_element_handler(self, name, attributes) -> None: ...
-    def start_element_handler(self, name, attributes) -> None: ...
-    def end_element_handler(self, name) -> None: ...
-    def element_decl_handler(self, name, model) -> None: ...
-    def attlist_decl_handler(self, elem, name, type, default, required) -> None: ...
-    def xml_decl_handler(self, version, encoding, standalone) -> None: ...
+    def entity_decl_handler(
+        self,
+        entityName: str,
+        is_parameter_entity: bool,
+        value: str | None,
+        base: str | None,
+        systemId: str,
+        publicId: str | None,
+        notationName: str | None,
+    ) -> None: ...
+    def notation_decl_handler(self, notationName: str, base: str | None, systemId: str, publicId: str | None) -> None: ...
+    def comment_handler(self, data: str) -> None: ...
+    def external_entity_ref_handler(self, context: str, base: str | None, systemId: str | None, publicId: str | None) -> int: ...
+    def first_element_handler(self, name: str, attributes: list[str]) -> None: ...
+    def start_element_handler(self, name: str, attributes: list[str]) -> None: ...
+    def end_element_handler(self, name: str) -> None: ...
+    def element_decl_handler(self, name: str, model: _Model) -> None: ...
+    def attlist_decl_handler(self, elem: str, name: str, type: str, default: str | None, required: bool) -> None: ...
+    def xml_decl_handler(self, version: str, encoding: str | None, standalone: int) -> None: ...
 
 class FilterVisibilityController:
     filter: DOMBuilderFilter
@@ -57,7 +72,7 @@ class FilterVisibilityController:
     def acceptNode(self, node: Node) -> int: ...
 
 class FilterCrutch:
-    def __init__(self, builder) -> None: ...
+    def __init__(self, builder: ExpatBuilder) -> None: ...
 
 class Rejecter(FilterCrutch):
     def start_element_handler(self, *args: Any) -> None: ...
@@ -68,33 +83,39 @@ class Skipper(FilterCrutch):
     def end_element_handler(self, *args: Any) -> None: ...
 
 class FragmentBuilder(ExpatBuilder):
-    fragment: Incomplete | None
-    originalDocument: Incomplete
-    context: Incomplete
-    def __init__(self, context, options: Options | None = None) -> None: ...
+    fragment: DocumentFragment | None
+    originalDocument: Document
+    context: Node
+    def __init__(self, context: Node, options: Options | None = None) -> None: ...
+    def reset(self) -> None: ...
+    def parseFile(self, file: SupportsRead[ReadableBuffer | str]) -> DocumentFragment: ...  # type: ignore[override]
+    def parseString(self, string: ReadableBuffer | str) -> DocumentFragment: ...  # type: ignore[override]
+    def external_entity_ref_handler(self, context: str, base: str | None, systemId: str | None, publicId: str | None) -> int: ...
 
 class Namespaces:
-    def createParser(self): ...
-    def install(self, parser) -> None: ...
-    def start_namespace_decl_handler(self, prefix, uri) -> None: ...
-    def start_element_handler(self, name, attributes) -> None: ...
-    def end_element_handler(self, name) -> None: ...
+    def createParser(self) -> XMLParserType: ...
+    def install(self, parser: XMLParserType) -> None: ...
+    def start_namespace_decl_handler(self, prefix: str | None, uri: str) -> None: ...
+    def start_element_handler(self, name: str, attributes: list[str]) -> None: ...
+    def end_element_handler(self, name: str) -> None: ...  # only exists if __debug__
 
 class ExpatBuilderNS(Namespaces, ExpatBuilder): ...
 class FragmentBuilderNS(Namespaces, FragmentBuilder): ...
 class ParseEscape(Exception): ...
 
 class InternalSubsetExtractor(ExpatBuilder):
-    subset: Any | None
-    def getSubset(self) -> Any | None: ...
+    subset: str | list[str] | None = None
+    def getSubset(self) -> str: ...
     def parseFile(self, file: SupportsRead[ReadableBuffer | str]) -> None: ...  # type: ignore[override]
     def parseString(self, string: str | ReadableBuffer) -> None: ...  # type: ignore[override]
-    def start_doctype_decl_handler(self, name, publicId, systemId, has_internal_subset) -> None: ...  # type: ignore[override]
+    def start_doctype_decl_handler(  # type: ignore[override]
+        self, name: str, publicId: str | None, systemId: str | None, has_internal_subset: bool
+    ) -> None: ...
     def end_doctype_decl_handler(self) -> NoReturn: ...
-    def start_element_handler(self, name, attrs) -> NoReturn: ...
+    def start_element_handler(self, name: str, attrs: list[str]) -> NoReturn: ...
 
-def parse(file: str | SupportsRead[ReadableBuffer | str], namespaces: bool = True): ...
-def parseString(string: str | ReadableBuffer, namespaces: bool = True): ...
-def parseFragment(file, context, namespaces: bool = True): ...
-def parseFragmentString(string: str, context, namespaces: bool = True): ...
+def parse(file: str | SupportsRead[ReadableBuffer | str], namespaces: bool = True) -> Document: ...
+def parseString(string: str | ReadableBuffer, namespaces: bool = True) -> Document: ...
+def parseFragment(file: str | SupportsRead[ReadableBuffer | str], context: Node, namespaces: bool = True) -> DocumentFragment: ...
+def parseFragmentString(string: str | ReadableBuffer, context: Node, namespaces: bool = True) -> DocumentFragment: ...
 def makeBuilder(options: Options) -> ExpatBuilderNS | ExpatBuilder: ...

stdlib/xml/dom/minidom.pyi

@@ -1,33 +1,92 @@
 import sys
 import xml.dom
+from _collections_abc import dict_keys, dict_values
 from _typeshed import Incomplete, ReadableBuffer, SupportsRead, SupportsWrite
-from typing import ClassVar, Literal, NoReturn, TypeVar, overload
-from typing_extensions import Self
-from xml.dom.minicompat import NodeList
+from collections.abc import Iterable, Sequence
+from types import TracebackType
+from typing import Any, ClassVar, Generic, Literal, NoReturn, Protocol, TypeVar, overload
+from typing_extensions import Self, TypeAlias
+from xml.dom.minicompat import EmptyNodeList, NodeList
 from xml.dom.xmlbuilder import DocumentLS, DOMImplementationLS
 from xml.sax.xmlreader import XMLReader
 
+_NSName: TypeAlias = tuple[str | None, str]
+
+# Entity can also have children, but it's not implemented the same way as the
+# others, so is deliberately omitted here.
+_NodesWithChildren: TypeAlias = DocumentFragment | Attr | Element | Document
+_NodesThatAreChildren: TypeAlias = CDATASection | Comment | DocumentType | Element | Notation | ProcessingInstruction | Text
+
+_AttrChildren: TypeAlias = Text  # Also EntityReference, but we don't implement it
+_ElementChildren: TypeAlias = Element | ProcessingInstruction | Comment | Text | CDATASection
+_EntityChildren: TypeAlias = Text  # I think; documentation is a little unclear
+_DocumentFragmentChildren: TypeAlias = Element | Text | CDATASection | ProcessingInstruction | Comment | Notation
+_DocumentChildren: TypeAlias = Comment | DocumentType | Element | ProcessingInstruction
+
 _N = TypeVar("_N", bound=Node)
+_ChildNodeVar = TypeVar("_ChildNodeVar", bound=_NodesThatAreChildren)
+_ChildNodePlusFragmentVar = TypeVar("_ChildNodePlusFragmentVar", bound=_NodesThatAreChildren | DocumentFragment)
+_DocumentChildrenVar = TypeVar("_DocumentChildrenVar", bound=_DocumentChildren)
+_ImportableNodeVar = TypeVar(
+    "_ImportableNodeVar",
+    bound=DocumentFragment
+    | Attr
+    | Element
+    | ProcessingInstruction
+    | CharacterData
+    | Text
+    | Comment
+    | CDATASection
+    | Entity
+    | Notation,
+)
+
+class _DOMErrorHandler(Protocol):
+    def handleError(self, error: Exception) -> bool: ...
+
+class _UserDataHandler(Protocol):
+    def handle(self, operation: int, key: str, data: Any, src: Node, dst: Node) -> None: ...
 
 def parse(
     file: str | SupportsRead[ReadableBuffer | str], parser: XMLReader | None = None, bufsize: int | None = None
 ) -> Document: ...
 def parseString(string: str | ReadableBuffer, parser: XMLReader | None = None) -> Document: ...
-def getDOMImplementation(features=None) -> DOMImplementation | None: ...
+@overload
+def getDOMImplementation(features: None = None) -> DOMImplementation: ...
+@overload
+def getDOMImplementation(features: str | Iterable[tuple[str, str | None]]) -> DOMImplementation | None: ...
 
 class Node(xml.dom.Node):
-    namespaceURI: str | None
-    parentNode: Incomplete
-    ownerDocument: Incomplete
-    nextSibling: Incomplete
-    previousSibling: Incomplete
-    prefix: Incomplete
+    parentNode: _NodesWithChildren | Entity | None
+    ownerDocument: Document | None
+    nextSibling: _NodesThatAreChildren | None
+    previousSibling: _NodesThatAreChildren | None
+    namespaceURI: str | None  # non-null only for Element and Attr
+    prefix: str | None  # non-null only for NS Element and Attr
+
+    # These aren't defined on Node, but they exist on all Node subclasses
+    # and various methods of Node require them to exist.
+    childNodes: (
+        NodeList[_DocumentFragmentChildren]
+        | NodeList[_AttrChildren]
+        | NodeList[_ElementChildren]
+        | NodeList[_DocumentChildren]
+        | NodeList[_EntityChildren]
+        | EmptyNodeList
+    )
+    nodeType: ClassVar[Literal[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]]
+    nodeName: str | None  # only possibly None on DocumentType
+
+    # Not defined on Node, but exist on all Node subclasses.
+    nodeValue: str | None  # non-null for Attr, ProcessingInstruction, Text, Comment, and CDATASection
+    attributes: NamedNodeMap | None  # non-null only for Element
+
     @property
-    def firstChild(self) -> Node | None: ...
+    def firstChild(self) -> _NodesThatAreChildren | None: ...
     @property
-    def lastChild(self) -> Node | None: ...
+    def lastChild(self) -> _NodesThatAreChildren | None: ...
     @property
-    def localName(self) -> str | None: ...
+    def localName(self) -> str | None: ...  # non-null only for Element and Attr
     def __bool__(self) -> Literal[True]: ...
     if sys.version_info >= (3, 9):
         @overload
@@ -95,62 +154,125 @@ class Node(xml.dom.Node):
         ) -> bytes: ...
 
     def hasChildNodes(self) -> bool: ...
-    def insertBefore(self, newChild, refChild): ...
-    def appendChild(self, node: _N) -> _N: ...
-    def replaceChild(self, newChild, oldChild): ...
-    def removeChild(self, oldChild): ...
-    def normalize(self) -> None: ...
-    def cloneNode(self, deep): ...
-    def isSupported(self, feature, version): ...
-    def isSameNode(self, other): ...
-    def getInterface(self, feature): ...
-    def getUserData(self, key): ...
-    def setUserData(self, key, data, handler): ...
-    childNodes: Incomplete
+    def insertBefore(  # type: ignore[misc]
+        self: _NodesWithChildren,  # pyright: ignore[reportGeneralTypeIssues]
+        newChild: _ChildNodePlusFragmentVar,
+        refChild: _NodesThatAreChildren | None,
+    ) -> _ChildNodePlusFragmentVar: ...
+    def appendChild(  # type: ignore[misc]
+        self: _NodesWithChildren, node: _ChildNodePlusFragmentVar  # pyright: ignore[reportGeneralTypeIssues]
+    ) -> _ChildNodePlusFragmentVar: ...
+    @overload
+    def replaceChild(  # type: ignore[misc]
+        self: _NodesWithChildren, newChild: DocumentFragment, oldChild: _ChildNodeVar
+    ) -> _ChildNodeVar | DocumentFragment: ...
+    @overload
+    def replaceChild(  # type: ignore[misc]
+        self: _NodesWithChildren, newChild: _NodesThatAreChildren, oldChild: _ChildNodeVar
+    ) -> _ChildNodeVar | None: ...
+    def removeChild(self: _NodesWithChildren, oldChild: _ChildNodeVar) -> _ChildNodeVar: ...  # type: ignore[misc]  # pyright: ignore[reportGeneralTypeIssues]
+    def normalize(self: _NodesWithChildren) -> None: ...  # type: ignore[misc]  # pyright: ignore[reportGeneralTypeIssues]
+    def cloneNode(self, deep: bool) -> Self | None: ...
+    def isSupported(self, feature: str, version: str | None) -> bool: ...
+    def isSameNode(self, other: Node) -> bool: ...
+    def getInterface(self, feature: str) -> Self | None: ...
+    def getUserData(self, key: str) -> Any | None: ...
+    def setUserData(self, key: str, data: Any, handler: _UserDataHandler) -> Any: ...
     def unlink(self) -> None: ...
     def __enter__(self) -> Self: ...
-    def __exit__(self, et, ev, tb) -> None: ...
+    def __exit__(self, et: type[BaseException] | None, ev: BaseException | None, tb: TracebackType | None) -> None: ...
+
+_DFChildrenVar = TypeVar("_DFChildrenVar", bound=_DocumentFragmentChildren)
+_DFChildrenPlusFragment = TypeVar("_DFChildrenPlusFragment", bound=_DocumentFragmentChildren | DocumentFragment)
 
 class DocumentFragment(Node):
-    nodeType: int
-    nodeName: str
-    nodeValue: Incomplete
-    attributes: Incomplete
-    parentNode: Incomplete
-    childNodes: Incomplete
+    nodeType: ClassVar[Literal[11]]
+    nodeName: Literal["#document-fragment"]
+    nodeValue: None
+    attributes: None
+
+    parentNode: None
+    nextSibling: None
+    previousSibling: None
+    childNodes: NodeList[_DocumentFragmentChildren]
+    @property
+    def firstChild(self) -> _DocumentFragmentChildren | None: ...
+    @property
+    def lastChild(self) -> _DocumentFragmentChildren | None: ...
+
+    namespaceURI: None
+    prefix: None
+    @property
+    def localName(self) -> None: ...
     def __init__(self) -> None: ...
+    def insertBefore(  # type: ignore[override]
+        self, newChild: _DFChildrenPlusFragment, refChild: _DocumentFragmentChildren | None
+    ) -> _DFChildrenPlusFragment: ...
+    def appendChild(self, node: _DFChildrenPlusFragment) -> _DFChildrenPlusFragment: ...  # type: ignore[override]
+    @overload  # type: ignore[override]
+    def replaceChild(self, newChild: DocumentFragment, oldChild: _DFChildrenVar) -> _DFChildrenVar | DocumentFragment: ...
+    @overload
+    def replaceChild(self, newChild: _DocumentFragmentChildren, oldChild: _DFChildrenVar) -> _DFChildrenVar | None: ...  # type: ignore[override]
+    def removeChild(self, oldChild: _DFChildrenVar) -> _DFChildrenVar: ...  # type: ignore[override]
+
+_AttrChildrenVar = TypeVar("_AttrChildrenVar", bound=_AttrChildren)
+_AttrChildrenPlusFragment = TypeVar("_AttrChildrenPlusFragment", bound=_AttrChildren | DocumentFragment)
 
 class Attr(Node):
-    name: str
-    nodeType: int
-    attributes: Incomplete
-    specified: bool
-    ownerElement: Incomplete
+    nodeType: ClassVar[Literal[2]]
+    nodeName: str  # same as Attr.name
+    nodeValue: str  # same as Attr.value
+    attributes: None
+
+    parentNode: None
+    nextSibling: None
+    previousSibling: None
+    childNodes: NodeList[_AttrChildren]
+    @property
+    def firstChild(self) -> _AttrChildren | None: ...
+    @property
+    def lastChild(self) -> _AttrChildren | None: ...
+
     namespaceURI: str | None
-    childNodes: Incomplete
-    nodeName: Incomplete
-    nodeValue: str
+    prefix: str | None
+    @property
+    def localName(self) -> str: ...
+
+    name: str
     value: str
-    prefix: Incomplete
+    specified: bool
+    ownerElement: Element | None
+
     def __init__(
-        self, qName: str, namespaceURI: str | None = None, localName: str | None = None, prefix: Incomplete | None = None
+        self, qName: str, namespaceURI: str | None = None, localName: str | None = None, prefix: str | None = None
     ) -> None: ...
     def unlink(self) -> None: ...
     @property
     def isId(self) -> bool: ...
     @property
-    def schemaType(self): ...
+    def schemaType(self) -> TypeInfo: ...
+    def insertBefore(self, newChild: _AttrChildrenPlusFragment, refChild: _AttrChildren | None) -> _AttrChildrenPlusFragment: ...  # type: ignore[override]
+    def appendChild(self, node: _AttrChildrenPlusFragment) -> _AttrChildrenPlusFragment: ...  # type: ignore[override]
+    @overload  # type: ignore[override]
+    def replaceChild(self, newChild: DocumentFragment, oldChild: _AttrChildrenVar) -> _AttrChildrenVar | DocumentFragment: ...
+    @overload
+    def replaceChild(self, newChild: _AttrChildren, oldChild: _AttrChildrenVar) -> _AttrChildrenVar | None: ...  # type: ignore[override]
+    def removeChild(self, oldChild: _AttrChildrenVar) -> _AttrChildrenVar: ...  # type: ignore[override]
 
+# In the DOM, this interface isn't specific to Attr, but our implementation is
+# because that's the only place we use it.
 class NamedNodeMap:
-    def __init__(self, attrs, attrsNS, ownerElement) -> None: ...
-    def item(self, index): ...
-    def items(self): ...
-    def itemsNS(self): ...
-    def __contains__(self, key): ...
-    def keys(self): ...
-    def keysNS(self): ...
-    def values(self): ...
-    def get(self, name: str, value: Incomplete | None = None): ...
+    def __init__(self, attrs: dict[str, Attr], attrsNS: dict[_NSName, Attr], ownerElement: Element) -> None: ...
+    @property
+    def length(self) -> int: ...
+    def item(self, index: int) -> Node | None: ...
+    def items(self) -> list[tuple[str, str]]: ...
+    def itemsNS(self) -> list[tuple[_NSName, str]]: ...
+    def __contains__(self, key: str | _NSName) -> bool: ...
+    def keys(self) -> dict_keys[str, Attr]: ...
+    def keysNS(self) -> dict_keys[_NSName, Attr]: ...
+    def values(self) -> dict_values[str, Attr]: ...
+    def get(self, name: str, value: Attr | None = None) -> Attr | None: ...
     __hash__: ClassVar[None]  # type: ignore[assignment]
     def __len__(self) -> int: ...
     def __eq__(self, other: object) -> bool: ...
@@ -158,135 +280,227 @@ class NamedNodeMap:
     def __gt__(self, other: NamedNodeMap) -> bool: ...
     def __le__(self, other: NamedNodeMap) -> bool: ...
     def __lt__(self, other: NamedNodeMap) -> bool: ...
-    def __getitem__(self, attname_or_tuple: tuple[str, str | None] | str): ...
+    def __getitem__(self, attname_or_tuple: _NSName | str) -> Attr: ...
     def __setitem__(self, attname: str, value: Attr | str) -> None: ...
     def getNamedItem(self, name: str) -> Attr | None: ...
-    def getNamedItemNS(self, namespaceURI: str, localName: str | None) -> Attr | None: ...
+    def getNamedItemNS(self, namespaceURI: str | None, localName: str) -> Attr | None: ...
     def removeNamedItem(self, name: str) -> Attr: ...
-    def removeNamedItemNS(self, namespaceURI: str, localName: str | None): ...
-    def setNamedItem(self, node: Attr) -> Attr: ...
-    def setNamedItemNS(self, node: Attr) -> Attr: ...
-    def __delitem__(self, attname_or_tuple: tuple[str, str | None] | str) -> None: ...
-    @property
-    def length(self) -> int: ...
+    def removeNamedItemNS(self, namespaceURI: str | None, localName: str) -> Attr: ...
+    def setNamedItem(self, node: Attr) -> Attr | None: ...
+    def setNamedItemNS(self, node: Attr) -> Attr | None: ...
+    def __delitem__(self, attname_or_tuple: _NSName | str) -> None: ...
 
 AttributeList = NamedNodeMap
 
 class TypeInfo:
-    namespace: Incomplete | None
-    name: str
-    def __init__(self, namespace: Incomplete | None, name: str) -> None: ...
+    namespace: str | None
+    name: str | None
+    def __init__(self, namespace: Incomplete | None, name: str | None) -> None: ...
+
+_ElementChildrenVar = TypeVar("_ElementChildrenVar", bound=_ElementChildren)
+_ElementChildrenPlusFragment = TypeVar("_ElementChildrenPlusFragment", bound=_ElementChildren | DocumentFragment)
 
 class Element(Node):
-    nodeType: int
-    nodeValue: Incomplete
-    schemaType: Incomplete
-    parentNode: Incomplete
-    tagName: str
-    nodeName: str
-    prefix: Incomplete
+    nodeType: ClassVar[Literal[1]]
+    nodeName: str  # same as Element.tagName
+    nodeValue: None
+    @property
+    def attributes(self) -> NamedNodeMap: ...  # type: ignore[override]
+
+    parentNode: Document | Element | DocumentFragment | None
+    nextSibling: _DocumentChildren | _ElementChildren | _DocumentFragmentChildren | None
+    previousSibling: _DocumentChildren | _ElementChildren | _DocumentFragmentChildren | None
+    childNodes: NodeList[_ElementChildren]
+    @property
+    def firstChild(self) -> _ElementChildren | None: ...
+    @property
+    def lastChild(self) -> _ElementChildren | None: ...
+
     namespaceURI: str | None
-    childNodes: Incomplete
-    nextSibling: Incomplete
+    prefix: str | None
+    @property
+    def localName(self) -> str: ...
+
+    schemaType: TypeInfo
+    tagName: str
+
     def __init__(
-        self, tagName, namespaceURI: str | None = None, prefix: Incomplete | None = None, localName: Incomplete | None = None
+        self, tagName: str, namespaceURI: str | None = None, prefix: str | None = None, localName: str | None = None
     ) -> None: ...
     def unlink(self) -> None: ...
     def getAttribute(self, attname: str) -> str: ...
-    def getAttributeNS(self, namespaceURI: str, localName): ...
+    def getAttributeNS(self, namespaceURI: str | None, localName: str) -> str: ...
     def setAttribute(self, attname: str, value: str) -> None: ...
-    def setAttributeNS(self, namespaceURI: str, qualifiedName: str, value) -> None: ...
-    def getAttributeNode(self, attrname: str): ...
-    def getAttributeNodeNS(self, namespaceURI: str, localName): ...
-    def setAttributeNode(self, attr): ...
-    setAttributeNodeNS: Incomplete
+    def setAttributeNS(self, namespaceURI: str | None, qualifiedName: str, value: str) -> None: ...
+    def getAttributeNode(self, attrname: str) -> Attr | None: ...
+    def getAttributeNodeNS(self, namespaceURI: str | None, localName: str) -> Attr | None: ...
+    def setAttributeNode(self, attr: Attr) -> Attr | None: ...
+    setAttributeNodeNS = setAttributeNode
     def removeAttribute(self, name: str) -> None: ...
-    def removeAttributeNS(self, namespaceURI: str, localName) -> None: ...
-    def removeAttributeNode(self, node): ...
-    removeAttributeNodeNS: Incomplete
+    def removeAttributeNS(self, namespaceURI: str | None, localName: str) -> None: ...
+    def removeAttributeNode(self, node: Attr) -> Attr: ...
+    removeAttributeNodeNS = removeAttributeNode
     def hasAttribute(self, name: str) -> bool: ...
-    def hasAttributeNS(self, namespaceURI: str, localName) -> bool: ...
+    def hasAttributeNS(self, namespaceURI: str | None, localName: str) -> bool: ...
     def getElementsByTagName(self, name: str) -> NodeList[Element]: ...
-    def getElementsByTagNameNS(self, namespaceURI: str, localName: str) -> NodeList[Element]: ...
+    def getElementsByTagNameNS(self, namespaceURI: str | None, localName: str) -> NodeList[Element]: ...
     def writexml(self, writer: SupportsWrite[str], indent: str = "", addindent: str = "", newl: str = "") -> None: ...
     def hasAttributes(self) -> bool: ...
-    def setIdAttribute(self, name) -> None: ...
-    def setIdAttributeNS(self, namespaceURI: str, localName) -> None: ...
-    def setIdAttributeNode(self, idAttr) -> None: ...
-    @property
-    def attributes(self) -> NamedNodeMap: ...
+    def setIdAttribute(self, name: str) -> None: ...
+    def setIdAttributeNS(self, namespaceURI: str | None, localName: str) -> None: ...
+    def setIdAttributeNode(self, idAttr: Attr) -> None: ...
+    def insertBefore(  # type: ignore[override]
+        self, newChild: _ElementChildrenPlusFragment, refChild: _ElementChildren | None
+    ) -> _ElementChildrenPlusFragment: ...
+    def appendChild(self, node: _ElementChildrenPlusFragment) -> _ElementChildrenPlusFragment: ...  # type: ignore[override]
+    @overload  # type: ignore[override]
+    def replaceChild(
+        self, newChild: DocumentFragment, oldChild: _ElementChildrenVar
+    ) -> _ElementChildrenVar | DocumentFragment: ...
+    @overload
+    def replaceChild(self, newChild: _ElementChildren, oldChild: _ElementChildrenVar) -> _ElementChildrenVar | None: ...  # type: ignore[override]
+    def removeChild(self, oldChild: _ElementChildrenVar) -> _ElementChildrenVar: ...  # type: ignore[override]
 
 class Childless:
-    attributes: Incomplete
-    childNodes: Incomplete
-    firstChild: Incomplete
-    lastChild: Incomplete
-    def appendChild(self, node) -> NoReturn: ...
-    def hasChildNodes(self) -> bool: ...
-    def insertBefore(self, newChild, refChild) -> NoReturn: ...
-    def removeChild(self, oldChild) -> NoReturn: ...
+    attributes: None
+    childNodes: EmptyNodeList
+    @property
+    def firstChild(self) -> None: ...
+    @property
+    def lastChild(self) -> None: ...
+    def appendChild(self, node: _NodesThatAreChildren | DocumentFragment) -> NoReturn: ...
+    def hasChildNodes(self) -> Literal[False]: ...
+    def insertBefore(
+        self, newChild: _NodesThatAreChildren | DocumentFragment, refChild: _NodesThatAreChildren | None
+    ) -> NoReturn: ...
+    def removeChild(self, oldChild: _NodesThatAreChildren) -> NoReturn: ...
     def normalize(self) -> None: ...
-    def replaceChild(self, newChild, oldChild) -> NoReturn: ...
+    def replaceChild(self, newChild: _NodesThatAreChildren | DocumentFragment, oldChild: _NodesThatAreChildren) -> NoReturn: ...
 
 class ProcessingInstruction(Childless, Node):
-    nodeType: int
-    target: Incomplete
-    data: Incomplete
-    def __init__(self, target, data) -> None: ...
-    nodeValue: Incomplete
-    nodeName: Incomplete
+    nodeType: ClassVar[Literal[7]]
+    nodeName: str  # same as ProcessingInstruction.target
+    nodeValue: str  # same as ProcessingInstruction.data
+    attributes: None
+
+    parentNode: Document | Element | DocumentFragment | None
+    nextSibling: _DocumentChildren | _ElementChildren | _DocumentFragmentChildren | None
+    previousSibling: _DocumentChildren | _ElementChildren | _DocumentFragmentChildren | None
+    childNodes: EmptyNodeList
+    @property
+    def firstChild(self) -> None: ...
+    @property
+    def lastChild(self) -> None: ...
+
+    namespaceURI: None
+    prefix: None
+    @property
+    def localName(self) -> None: ...
+
+    target: str
+    data: str
+
+    def __init__(self, target: str, data: str) -> None: ...
     def writexml(self, writer: SupportsWrite[str], indent: str = "", addindent: str = "", newl: str = "") -> None: ...
 
 class CharacterData(Childless, Node):
-    ownerDocument: Incomplete
-    previousSibling: Incomplete
-    def __init__(self) -> None: ...
-    def __len__(self) -> int: ...
+    nodeValue: str
+    attributes: None
+
+    childNodes: EmptyNodeList
+    nextSibling: _NodesThatAreChildren | None
+    previousSibling: _NodesThatAreChildren | None
+
+    @property
+    def localName(self) -> None: ...
+
+    ownerDocument: Document | None
     data: str
-    nodeValue: Incomplete
+
+    def __init__(self) -> None: ...
+    @property
+    def length(self) -> int: ...
+    def __len__(self) -> int: ...
     def substringData(self, offset: int, count: int) -> str: ...
     def appendData(self, arg: str) -> None: ...
     def insertData(self, offset: int, arg: str) -> None: ...
     def deleteData(self, offset: int, count: int) -> None: ...
     def replaceData(self, offset: int, count: int, arg: str) -> None: ...
-    @property
-    def length(self) -> int: ...
 
 class Text(CharacterData):
-    nodeType: int
-    nodeName: str
-    attributes: Incomplete
-    data: Incomplete
+    nodeType: ClassVar[Literal[3]]
+    nodeName: Literal["#text"]
+    nodeValue: str  # same as CharacterData.data, the content of the text node
+    attributes: None
+
+    parentNode: Attr | Element | DocumentFragment | None
+    nextSibling: _DocumentFragmentChildren | _ElementChildren | _AttrChildren | None
+    previousSibling: _DocumentFragmentChildren | _ElementChildren | _AttrChildren | None
+    childNodes: EmptyNodeList
+    @property
+    def firstChild(self) -> None: ...
+    @property
+    def lastChild(self) -> None: ...
+
+    namespaceURI: None
+    prefix: None
+    @property
+    def localName(self) -> None: ...
+
+    data: str
     def splitText(self, offset: int) -> Self: ...
     def writexml(self, writer: SupportsWrite[str], indent: str = "", addindent: str = "", newl: str = "") -> None: ...
-    def replaceWholeText(self, content) -> Self | None: ...
+    def replaceWholeText(self, content: str) -> Self | None: ...
     @property
     def isWhitespaceInElementContent(self) -> bool: ...
     @property
     def wholeText(self) -> str: ...
 
 class Comment(CharacterData):
-    nodeType: int
-    nodeName: str
-    def __init__(self, data) -> None: ...
+    nodeType: ClassVar[Literal[8]]
+    nodeName: Literal["#comment"]
+    nodeValue: str  # same as CharacterData.data, the content of the comment
+    attributes: None
+
+    parentNode: Document | Element | DocumentFragment | None
+    nextSibling: _DocumentChildren | _ElementChildren | _DocumentFragmentChildren | None
+    previousSibling: _DocumentChildren | _ElementChildren | _DocumentFragmentChildren | None
+    childNodes: EmptyNodeList
+    @property
+    def firstChild(self) -> None: ...
+    @property
+    def lastChild(self) -> None: ...
+
+    namespaceURI: None
+    prefix: None
+    @property
+    def localName(self) -> None: ...
+    def __init__(self, data: str) -> None: ...
     def writexml(self, writer: SupportsWrite[str], indent: str = "", addindent: str = "", newl: str = "") -> None: ...
 
 class CDATASection(Text):
-    nodeType: int
-    nodeName: str
+    nodeType: ClassVar[Literal[4]]  # type: ignore[assignment]
+    nodeName: Literal["#cdata-section"]  # type: ignore[assignment]
+    nodeValue: str  # same as CharacterData.data, the content of the CDATA Section
+    attributes: None
+
+    parentNode: Element | DocumentFragment | None
+    nextSibling: _DocumentFragmentChildren | _ElementChildren | None
+    previousSibling: _DocumentFragmentChildren | _ElementChildren | None
+
     def writexml(self, writer: SupportsWrite[str], indent: str = "", addindent: str = "", newl: str = "") -> None: ...
 
-class ReadOnlySequentialNamedNodeMap:
-    def __init__(self, seq=()) -> None: ...
+class ReadOnlySequentialNamedNodeMap(Generic[_N]):
+    def __init__(self, seq: Sequence[_N] = ()) -> None: ...
     def __len__(self) -> int: ...
-    def getNamedItem(self, name): ...
-    def getNamedItemNS(self, namespaceURI: str, localName): ...
-    def __getitem__(self, name_or_tuple): ...
-    def item(self, index): ...
-    def removeNamedItem(self, name) -> None: ...
-    def removeNamedItemNS(self, namespaceURI: str, localName) -> None: ...
-    def setNamedItem(self, node) -> None: ...
-    def setNamedItemNS(self, node) -> None: ...
+    def getNamedItem(self, name: str) -> _N | None: ...
+    def getNamedItemNS(self, namespaceURI: str | None, localName: str) -> _N | None: ...
+    def __getitem__(self, name_or_tuple: str | _NSName) -> _N | None: ...
+    def item(self, index: int) -> _N | None: ...
+    def removeNamedItem(self, name: str) -> NoReturn: ...
+    def removeNamedItemNS(self, namespaceURI: str | None, localName: str) -> NoReturn: ...
+    def setNamedItem(self, node: Node) -> NoReturn: ...
+    def setNamedItemNS(self, node: Node) -> NoReturn: ...
     @property
     def length(self) -> int: ...
 
@@ -295,38 +509,85 @@ class Identified:
     systemId: str | None
 
 class DocumentType(Identified, Childless, Node):
-    nodeType: int
-    nodeValue: Incomplete
-    name: Incomplete
-    internalSubset: Incomplete
-    entities: Incomplete
-    notations: Incomplete
-    nodeName: Incomplete
-    def __init__(self, qualifiedName: str) -> None: ...
-    def cloneNode(self, deep): ...
+    nodeType: ClassVar[Literal[10]]
+    nodeName: str | None  # same as DocumentType.name
+    nodeValue: None
+    attributes: None
+
+    parentNode: Document | None
+    nextSibling: _DocumentChildren | None
+    previousSibling: _DocumentChildren | None
+    childNodes: EmptyNodeList
+    @property
+    def firstChild(self) -> None: ...
+    @property
+    def lastChild(self) -> None: ...
+
+    namespaceURI: None
+    prefix: None
+    @property
+    def localName(self) -> None: ...
+
+    name: str | None
+    internalSubset: str | None
+    entities: ReadOnlySequentialNamedNodeMap[Entity]
+    notations: ReadOnlySequentialNamedNodeMap[Notation]
+
+    def __init__(self, qualifiedName: str | None) -> None: ...
+    def cloneNode(self, deep: bool) -> DocumentType | None: ...
     def writexml(self, writer: SupportsWrite[str], indent: str = "", addindent: str = "", newl: str = "") -> None: ...
 
 class Entity(Identified, Node):
-    attributes: Incomplete
-    nodeType: int
-    nodeValue: Incomplete
-    actualEncoding: Incomplete
-    encoding: Incomplete
-    version: Incomplete
-    nodeName: Incomplete
-    notationName: Incomplete
-    childNodes: Incomplete
-    def __init__(self, name, publicId, systemId, notation) -> None: ...
-    def appendChild(self, newChild) -> NoReturn: ...
-    def insertBefore(self, newChild, refChild) -> NoReturn: ...
-    def removeChild(self, oldChild) -> NoReturn: ...
-    def replaceChild(self, newChild, oldChild) -> NoReturn: ...
+    nodeType: ClassVar[Literal[6]]
+    nodeName: str  # entity name
+    nodeValue: None
+    attributes: None
+
+    parentNode: None
+    nextSibling: None
+    previousSibling: None
+    childNodes: NodeList[_EntityChildren]
+    @property
+    def firstChild(self) -> _EntityChildren | None: ...
+    @property
+    def lastChild(self) -> _EntityChildren | None: ...
+
+    namespaceURI: None
+    prefix: None
+    @property
+    def localName(self) -> None: ...
+
+    actualEncoding: str | None
+    encoding: str | None
+    version: str | None
+    notationName: str | None
+
+    def __init__(self, name: str, publicId: str | None, systemId: str | None, notation: str | None) -> None: ...
+    def appendChild(self, newChild: _EntityChildren) -> NoReturn: ...  # type: ignore[override]
+    def insertBefore(self, newChild: _EntityChildren, refChild: _EntityChildren | None) -> NoReturn: ...  # type: ignore[override]
+    def removeChild(self, oldChild: _EntityChildren) -> NoReturn: ...  # type: ignore[override]
+    def replaceChild(self, newChild: _EntityChildren, oldChild: _EntityChildren) -> NoReturn: ...  # type: ignore[override]
 
 class Notation(Identified, Childless, Node):
-    nodeType: int
-    nodeValue: Incomplete
-    nodeName: Incomplete
-    def __init__(self, name, publicId, systemId) -> None: ...
+    nodeType: ClassVar[Literal[12]]
+    nodeName: str  # notation name
+    nodeValue: None
+    attributes: None
+
+    parentNode: DocumentFragment | None
+    nextSibling: _DocumentFragmentChildren | None
+    previousSibling: _DocumentFragmentChildren | None
+    childNodes: EmptyNodeList
+    @property
+    def firstChild(self) -> None: ...
+    @property
+    def lastChild(self) -> None: ...
+
+    namespaceURI: None
+    prefix: None
+    @property
+    def localName(self) -> None: ...
+    def __init__(self, name: str, publicId: str | None, systemId: str | None) -> None: ...
 
 class DOMImplementation(DOMImplementationLS):
     def hasFeature(self, feature: str, version: str | None) -> bool: ...
@@ -335,53 +596,67 @@ class DOMImplementation(DOMImplementationLS):
     def getInterface(self, feature: str) -> Self | None: ...
 
 class ElementInfo:
-    tagName: Incomplete
-    def __init__(self, name) -> None: ...
-    def getAttributeType(self, aname): ...
-    def getAttributeTypeNS(self, namespaceURI: str, localName): ...
-    def isElementContent(self): ...
-    def isEmpty(self): ...
-    def isId(self, aname): ...
-    def isIdNS(self, namespaceURI: str, localName): ...
+    tagName: str
+    def __init__(self, name: str) -> None: ...
+    def getAttributeType(self, aname: str) -> TypeInfo: ...
+    def getAttributeTypeNS(self, namespaceURI: str | None, localName: str) -> TypeInfo: ...
+    def isElementContent(self) -> bool: ...
+    def isEmpty(self) -> bool: ...
+    def isId(self, aname: str) -> bool: ...
+    def isIdNS(self, namespaceURI: str | None, localName: str) -> bool: ...
+
+_DocumentChildrenPlusFragment = TypeVar("_DocumentChildrenPlusFragment", bound=_DocumentChildren | DocumentFragment)
 
 class Document(Node, DocumentLS):
-    implementation: Incomplete
-    nodeType: int
-    nodeName: str
-    nodeValue: Incomplete
-    attributes: Incomplete
-    parentNode: Incomplete
-    previousSibling: Incomplete
-    nextSibling: Incomplete
-    actualEncoding: Incomplete
+    nodeType: ClassVar[Literal[9]]
+    nodeName: Literal["#document"]
+    nodeValue: None
+    attributes: None
+
+    parentNode: None
+    previousSibling: None
+    nextSibling: None
+    childNodes: NodeList[_DocumentChildren]
+    @property
+    def firstChild(self) -> _DocumentChildren | None: ...
+    @property
+    def lastChild(self) -> _DocumentChildren | None: ...
+
+    namespaceURI: None
+    prefix: None
+    @property
+    def localName(self) -> None: ...
+
+    implementation: DOMImplementation
+    actualEncoding: str | None
     encoding: str | None
     standalone: bool | None
-    version: Incomplete
+    version: str | None
     strictErrorChecking: bool
-    errorHandler: Incomplete
-    documentURI: Incomplete
+    errorHandler: _DOMErrorHandler | None
+    documentURI: str | None
     doctype: DocumentType | None
-    childNodes: Incomplete
+    documentElement: Element | None
+
     def __init__(self) -> None: ...
-    def appendChild(self, node: _N) -> _N: ...
-    documentElement: Incomplete
-    def removeChild(self, oldChild): ...
+    def appendChild(self, node: _DocumentChildrenVar) -> _DocumentChildrenVar: ...  # type: ignore[override]
+    def removeChild(self, oldChild: _DocumentChildrenVar) -> _DocumentChildrenVar: ...  # type: ignore[override]
     def unlink(self) -> None: ...
-    def cloneNode(self, deep): ...
+    def cloneNode(self, deep: bool) -> Document | None: ...
     def createDocumentFragment(self) -> DocumentFragment: ...
     def createElement(self, tagName: str) -> Element: ...
     def createTextNode(self, data: str) -> Text: ...
     def createCDATASection(self, data: str) -> CDATASection: ...
     def createComment(self, data: str) -> Comment: ...
-    def createProcessingInstruction(self, target, data): ...
-    def createAttribute(self, qName) -> Attr: ...
-    def createElementNS(self, namespaceURI: str, qualifiedName: str): ...
-    def createAttributeNS(self, namespaceURI: str, qualifiedName: str) -> Attr: ...
+    def createProcessingInstruction(self, target: str, data: str) -> ProcessingInstruction: ...
+    def createAttribute(self, qName: str) -> Attr: ...
+    def createElementNS(self, namespaceURI: str | None, qualifiedName: str) -> Element: ...
+    def createAttributeNS(self, namespaceURI: str | None, qualifiedName: str) -> Attr: ...
     def getElementById(self, id: str) -> Element | None: ...
     def getElementsByTagName(self, name: str) -> NodeList[Element]: ...
-    def getElementsByTagNameNS(self, namespaceURI: str, localName: str) -> NodeList[Element]: ...
+    def getElementsByTagNameNS(self, namespaceURI: str | None, localName: str) -> NodeList[Element]: ...
     def isSupported(self, feature: str, version: str | None) -> bool: ...
-    def importNode(self, node, deep): ...
+    def importNode(self, node: _ImportableNodeVar, deep: bool) -> _ImportableNodeVar: ...
     if sys.version_info >= (3, 9):
         def writexml(
             self,
@@ -402,4 +677,18 @@ class Document(Node, DocumentLS):
             encoding: Incomplete | None = None,
         ) -> None: ...
 
-    def renameNode(self, n, namespaceURI: str, name): ...
+    @overload
+    def renameNode(self, n: Element, namespaceURI: str, name: str) -> Element: ...
+    @overload
+    def renameNode(self, n: Attr, namespaceURI: str, name: str) -> Attr: ...
+    @overload
+    def renameNode(self, n: Element | Attr, namespaceURI: str, name: str) -> Element | Attr: ...
+    def insertBefore(
+        self, newChild: _DocumentChildrenPlusFragment, refChild: _DocumentChildren | None  # type: ignore[override]
+    ) -> _DocumentChildrenPlusFragment: ...
+    @overload  # type: ignore[override]
+    def replaceChild(
+        self, newChild: DocumentFragment, oldChild: _DocumentChildrenVar
+    ) -> _DocumentChildrenVar | DocumentFragment: ...
+    @overload
+    def replaceChild(self, newChild: _DocumentChildren, oldChild: _DocumentChildrenVar) -> _DocumentChildrenVar | None: ...

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: ...

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: