docutils: add nodes.General; make Element iterable (#10099)

Co-authored-by: Alex Waygood <[email protected]>

Author: danieleades

stubs/docutils/@tests/stubtest_allowlist.txt

@@ -10,6 +10,7 @@ docutils.nodes.Element.__getattr__
 docutils.nodes.NodeVisitor.__getattr__
 docutils.nodes.document.__getattr__
 docutils.nodes.document.__init__
+docutils.nodes.Element.__iter__ # doesn't exist at runtime, but the class is iterable due to __getitem__
 docutils.parsers.rst.Directive.__getattr__
 docutils.transforms.Transform.__getattr__
 docutils.transforms.Transformer.__getattr__

stubs/docutils/docutils/nodes.pyi

@@ -1,7 +1,7 @@
 import xml.dom.minidom
 from _typeshed import Incomplete
 from abc import abstractmethod
-from collections.abc import Callable, Generator, Iterable, Sequence
+from collections.abc import Callable, Generator, Iterable, Iterator, Sequence
 from typing import Any, ClassVar, Protocol, TypeVar, overload
 from typing_extensions import Literal, Self
 
@@ -82,6 +82,9 @@ class Element(Node):
     def __init__(self, rawsource: str = "", *children: Node, **attributes): ...
     def __len__(self) -> int: ...
     def __contains__(self, key: str | Node) -> bool: ...
+    # '__iter__' is added as workaround, since mypy doesn't support classes that are iterable via '__getitem__'
+    # see https://github.com/python/typeshed/pull/10099#issuecomment-1528789395
+    def __iter__(self) -> Iterator[Node]: ...
     @overload
     def __getitem__(self, key: str) -> Any: ...
     @overload
@@ -120,6 +123,8 @@ class Text(Node, str):
     def lstrip(self, chars: str | None = None) -> str: ...
 
 class Structural: ...
+class Body: ...
+class General(Body): ...
 class Root: ...
 
 class document(Root, Structural, Element):