basedpyright 1.28.3 → 1.28.4

package/dist/typeshed-fallback/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:
         """First child node, or None."""
         ...
     @property
-    def lastChild(self) -> Node | None:
+    def lastChild(self) -> _NodesThatAreChildren | None:
         """Last child node, or None."""
         ...
     @property
@@ -101,45 +160,109 @@ 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:
+        """First child node, or None."""
+        ...
+    @property
+    def lastChild(self) -> _DocumentFragmentChildren | None:
+        """Last child node, or None."""
+        ...
+
+    namespaceURI: None
+    prefix: None
+    @property
+    def localName(self) -> None:
+        """Namespace-local name of this node."""
+        ...
     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:
+        """First child node, or None."""
+        ...
+    @property
+    def lastChild(self) -> _AttrChildren | None:
+        """Last child node, or None."""
+        ...
+
     namespaceURI: str | None
-    childNodes: Incomplete
-    nodeName: Incomplete
-    nodeValue: str
+    prefix: str | None
+    @property
+    def localName(self) -> str:
+        """Namespace-local name of this attribute."""
+        ...
+
+    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
@@ -147,20 +270,33 @@ class Attr(Node):
         """True if this attribute is an ID."""
         ...
     @property
-    def schemaType(self):
+    def schemaType(self) -> TypeInfo:
         """Schema type for this attribute."""
         ...
+    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:
+        """Number of nodes in the NamedNodeMap."""
+        ...
+    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: ...
@@ -168,114 +304,193 @@ 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:
-        """Number of nodes in the NamedNodeMap."""
-        ...
+    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:
+        """NamedNodeMap of attributes on the element."""
+        ...
+
+    parentNode: Document | Element | DocumentFragment | None
+    nextSibling: _DocumentChildren | _ElementChildren | _DocumentFragmentChildren | None
+    previousSibling: _DocumentChildren | _ElementChildren | _DocumentFragmentChildren | None
+    childNodes: NodeList[_ElementChildren]
+    @property
+    def firstChild(self) -> _ElementChildren | None:
+        """First child node, or None."""
+        ...
+    @property
+    def lastChild(self) -> _ElementChildren | None:
+        """Last child node, or None."""
+        ...
+
     namespaceURI: str | None
-    childNodes: Incomplete
-    nextSibling: Incomplete
+    prefix: str | None
+    @property
+    def localName(self) -> str:
+        """Namespace-local name of this element."""
+        ...
+
+    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:
-        """NamedNodeMap of attributes on the element."""
-        ...
+    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:
+        """Namespace-local name of this node."""
+        ...
+
+    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
+    nodeValue: str
+    attributes: None
+
+    childNodes: EmptyNodeList
+    nextSibling: _NodesThatAreChildren | None
+    previousSibling: _NodesThatAreChildren | None
+
+    @property
+    def localName(self) -> None:
+        """Namespace-local name of this node."""
+        ...
+
+    ownerDocument: Document | None
+    data: str
+
     def __init__(self) -> None: ...
+    @property
+    def length(self) -> int:
+        """Length of the string data."""
+        ...
     def __len__(self) -> int: ...
-    data: str
-    nodeValue: Incomplete
     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: ...
+
+class Text(CharacterData):
+    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 length(self) -> int:
-        """Length of the string data."""
+    def firstChild(self) -> None: ...
+    @property
+    def lastChild(self) -> None: ...
+
+    namespaceURI: None
+    prefix: None
+    @property
+    def localName(self) -> None:
+        """Namespace-local name of this node."""
         ...
 
-class Text(CharacterData):
-    nodeType: int
-    nodeName: str
-    attributes: Incomplete
-    data: Incomplete
+    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:
         """True iff this text node contains only whitespace and is in element content."""
@@ -286,27 +501,52 @@ class Text(CharacterData):
         ...
 
 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:
+        """Namespace-local name of this node."""
+        ...
+    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:
         """Number of entries in the NamedNodeMap."""
@@ -317,38 +557,95 @@ 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:
+        """Namespace-local name of this node."""
+        ...
+
+    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:
+        """First child node, or None."""
+        ...
+    @property
+    def lastChild(self) -> _EntityChildren | None:
+        """Last child node, or None."""
+        ...
+
+    namespaceURI: None
+    prefix: None
+    @property
+    def localName(self) -> None:
+        """Namespace-local name of this node."""
+        ...
+
+    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:
+        """Namespace-local name of this node."""
+        ...
+    def __init__(self, name: str, publicId: str | None, systemId: str | None) -> None: ...
 
 class DOMImplementation(DOMImplementationLS):
     def hasFeature(self, feature: str, version: str | None) -> bool: ...
@@ -357,53 +654,73 @@ 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:
+        """First child node, or None."""
+        ...
+    @property
+    def lastChild(self) -> _DocumentChildren | None:
+        """Last child node, or None."""
+        ...
+
+    namespaceURI: None
+    prefix: None
+    @property
+    def localName(self) -> None:
+        """Namespace-local name of this node."""
+        ...
+
+    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,
@@ -424,4 +741,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: ...