add docutils.nodes.General stub

[danieleades]

this is a trivial change, but will remove type errors from sphinx extension examples where docutils.nodes.General is subclassed

[danieleades]

Diff from mypy_primer, showing the effect of this PR on open source code:

sphinx (https://github.com/sphinx-doc/sphinx)
+ sphinx/util/docfields.py: note: In member "transform_all" of class "DocFieldTransformer":
+ sphinx/util/docfields.py:246:22: error: "desc_content" has no attribute "__iter__" (not iterable)  [attr-defined]

this is an interesting one. a docutils nodes.Element is iterable, according to its docs (and i use it this way in my own libraries) but I can't for the life of me see where it's implemented. Not surprised mypy is complaining. Perhaps the __iter__ and __next__ attributes are set dynamically at runtime? but if they are, it's not clear to me what the mechanism is

edit: I found this helpful - https://stackoverflow.com/questions/926574/why-does-defining-getitem-on-a-class-make-it-iterable-in-python

so having a __get_item__ method is enough to make nodes.Element iterable, but mypy isn't assuming that the subclasses are iterable. see python/mypy#13485

[JelleZijlstra]

As a workaround, we could lie and add an __iter__ method to Element.

[AlexWaygood]

As a workaround, we could lie and add an __iter__ method to Element.

Agreed. I'm supportive of improving mypy here, but I don't know when or if that mypy PR will get merged. There's a number of other classes where we invent fake iter methods in typeshed, and it's an okay workaround:

typeshed/tests/stubtest_allowlists/py3_common.txt

Lines 606 to 613 in f42f665

	# Iterable classes that don't define __iter__ at runtime (usually iterable via __getitem__)
	# These would ideally be special-cased by type checkers; see https://github.com/python/mypy/issues/2220
	ctypes.Array.__iter__
	mmap.mmap.__iter__
	mmap.mmap.__contains__
	xml.etree.ElementTree.Element.__iter__
	xml.etree.cElementTree.Element.__iter__
	typing.IO.__iter__ # See https://github.com/python/typeshed/commit/97bc450acd60c1bcdafef3ce8fbe3b95a9c0cac3

[danieleades]

note: unused allowlist entry docutils.nodes.Element.__iter__

@AlexWaygood where am i going wrong?

[AlexWaygood]

note: unused allowlist entry docutils.nodes.Element.__iter__

@AlexWaygood where am i going wrong?

#10099 (comment)

[AlexWaygood]

Thanks!

[github-actions]

Diff from mypy_primer, showing the effect of this PR on open source code:

sphinx (https://github.com/sphinx-doc/sphinx)
- sphinx/domains/std.py: note: In member "get_numfig_title" of class "StandardDomain":
- sphinx/domains/std.py:1027:32: error: "Element" has no attribute "__iter__" (not iterable)  [attr-defined]
- sphinx/domains/std.py: note: In function "get_enumerable_node_type":
- sphinx/domains/std.py:1036:60: error: "Element" has no attribute "__iter__" (not iterable)  [attr-defined]
- sphinx/domains/python.py: note: In function "filter_meta_fields":
- sphinx/domains/python.py:1117:17: error: "Element" has no attribute "__iter__" (not iterable)  [attr-defined]
- sphinx/builders/_epub_base.py: note: In member "get_refnodes" of class "EpubBuilder":
- sphinx/builders/_epub_base.py:205:25: error: "Element" has no attribute "__iter__" (not iterable)  [attr-defined]
- sphinx/writers/latex.py: note: In member "_visit_signature_line" of class "LaTeXTranslator":
- sphinx/writers/latex.py:703:22: error: "Element" has no attribute "__iter__" (not iterable)  [attr-defined]
- sphinx/writers/latex.py: note: In member "visit_figure" of class "LaTeXTranslator":
- sphinx/writers/latex.py:1351:66: error: "Element" has no attribute "__iter__" (not iterable)  [attr-defined]
- sphinx/writers/latex.py:1375:66: error: "Element" has no attribute "__iter__" (not iterable)  [attr-defined]
- sphinx/ext/autodoc/typehints.py:58:35: error: "Element" has no attribute "__iter__" (not iterable)  [attr-defined]
- sphinx/ext/autodoc/typehints.py: note: In function "insert_field_list":
- sphinx/ext/autodoc/typehints.py:81:24: error: "Element" has no attribute "__iter__" (not iterable)  [attr-defined]
- sphinx/environment/collectors/toctree.py:67:32: error: Item "Element" of "Union[Element, Sequence[Element]]" has no attribute "__iter__" (not iterable)  [union-attr]
- sphinx/writers/texinfo.py: note: In function "find_subsections":
- sphinx/writers/texinfo.py:86:18: error: "Element" has no attribute "__iter__" (not iterable)  [attr-defined]

[AlexWaygood]

Diff from mypy_primer, showing the effect of this PR on open source code:

sphinx (https://github.com/sphinx-doc/sphinx)
- sphinx/domains/std.py: note: In member "get_numfig_title" of class "StandardDomain":
- sphinx/domains/std.py:1027:32: error: "Element" has no attribute "__iter__" (not iterable)  [attr-defined]
- sphinx/domains/std.py: note: In function "get_enumerable_node_type":
- sphinx/domains/std.py:1036:60: error: "Element" has no attribute "__iter__" (not iterable)  [attr-defined]
- sphinx/domains/python.py: note: In function "filter_meta_fields":
- sphinx/domains/python.py:1117:17: error: "Element" has no attribute "__iter__" (not iterable)  [attr-defined]
- sphinx/builders/_epub_base.py: note: In member "get_refnodes" of class "EpubBuilder":
- sphinx/builders/_epub_base.py:205:25: error: "Element" has no attribute "__iter__" (not iterable)  [attr-defined]
- sphinx/writers/latex.py: note: In member "_visit_signature_line" of class "LaTeXTranslator":
- sphinx/writers/latex.py:703:22: error: "Element" has no attribute "__iter__" (not iterable)  [attr-defined]
- sphinx/writers/latex.py: note: In member "visit_figure" of class "LaTeXTranslator":
- sphinx/writers/latex.py:1351:66: error: "Element" has no attribute "__iter__" (not iterable)  [attr-defined]
- sphinx/writers/latex.py:1375:66: error: "Element" has no attribute "__iter__" (not iterable)  [attr-defined]
- sphinx/ext/autodoc/typehints.py:58:35: error: "Element" has no attribute "__iter__" (not iterable)  [attr-defined]
- sphinx/ext/autodoc/typehints.py: note: In function "insert_field_list":
- sphinx/ext/autodoc/typehints.py:81:24: error: "Element" has no attribute "__iter__" (not iterable)  [attr-defined]
- sphinx/environment/collectors/toctree.py:67:32: error: Item "Element" of "Union[Element, Sequence[Element]]" has no attribute "__iter__" (not iterable)  [union-attr]
- sphinx/writers/texinfo.py: note: In function "find_subsections":
- sphinx/writers/texinfo.py:86:18: error: "Element" has no attribute "__iter__" (not iterable)  [attr-defined]

That's a good sign!