style: improve type annotations with an 'extract_node' test utility

pyproject.toml

@@ -230,7 +230,6 @@ module = [
     "tests.test_domains.test_domain_py_fields",
     "tests.test_domains.test_domain_py_pyfunction",
     "tests.test_domains.test_domain_py_pyobject",
-    "tests.test_domains.test_domain_rst",
     "tests.test_domains.test_domain_std",
     # tests/test_environment
     "tests.test_environment.test_environment_toctree",

tests/test_builders/test_build.py

@@ -9,6 +9,8 @@
 
 from sphinx.errors import SphinxError
 
+from tests.utils import extract_element, extract_node
+
 if TYPE_CHECKING:
     from collections.abc import Callable
     from pathlib import Path
@@ -68,51 +70,51 @@ def test_image_glob(app: SphinxTestApp) -> None:
     doctree = app.env.get_doctree('index')
     assert isinstance(doctree[0], nodes.Element)
 
-    assert isinstance(doctree[0][1], nodes.image)
-    assert doctree[0][1]['candidates'] == {'*': 'rimg.png'}
-    assert doctree[0][1]['uri'] == 'rimg.png'
+    assert isinstance(extract_node(doctree, 0, 1), nodes.image)
+    assert extract_element(doctree, 0, 1)['candidates'] == {'*': 'rimg.png'}
+    assert extract_element(doctree, 0, 1)['uri'] == 'rimg.png'
 
-    assert isinstance(doctree[0][2], nodes.figure)
-    assert isinstance(doctree[0][2][0], nodes.image)
-    assert doctree[0][2][0]['candidates'] == {'*': 'rimg.png'}
-    assert doctree[0][2][0]['uri'] == 'rimg.png'
+    assert isinstance(extract_node(doctree, 0, 2), nodes.figure)
+    assert isinstance(extract_node(doctree, 0, 2, 0), nodes.image)
+    assert extract_element(doctree, 0, 2, 0)['candidates'] == {'*': 'rimg.png'}
+    assert extract_element(doctree, 0, 2, 0)['uri'] == 'rimg.png'
 
-    assert isinstance(doctree[0][3], nodes.image)
-    assert doctree[0][3]['candidates'] == {
+    assert isinstance(extract_node(doctree, 0, 3), nodes.image)
+    assert extract_element(doctree, 0, 3)['candidates'] == {
         'application/pdf': 'img.pdf',
         'image/gif': 'img.gif',
         'image/png': 'img.png',
     }
-    assert doctree[0][3]['uri'] == 'img.*'
+    assert extract_element(doctree, 0, 3)['uri'] == 'img.*'
 
-    assert isinstance(doctree[0][4], nodes.figure)
-    assert isinstance(doctree[0][4][0], nodes.image)
-    assert doctree[0][4][0]['candidates'] == {
+    assert isinstance(extract_node(doctree, 0, 4), nodes.figure)
+    assert isinstance(extract_node(doctree, 0, 4, 0), nodes.image)
+    assert extract_element(doctree, 0, 4, 0)['candidates'] == {
         'application/pdf': 'img.pdf',
         'image/gif': 'img.gif',
         'image/png': 'img.png',
     }
-    assert doctree[0][4][0]['uri'] == 'img.*'
+    assert extract_element(doctree, 0, 4, 0)['uri'] == 'img.*'
 
     # subdir/index.rst
     doctree = app.env.get_doctree('subdir/index')
     assert isinstance(doctree[0], nodes.Element)
 
-    assert isinstance(doctree[0][1], nodes.image)
-    assert doctree[0][1]['candidates'] == {'*': 'subdir/rimg.png'}
-    assert doctree[0][1]['uri'] == 'subdir/rimg.png'
+    assert isinstance(extract_node(doctree, 0, 1), nodes.image)
+    assert extract_element(doctree, 0, 1)['candidates'] == {'*': 'subdir/rimg.png'}
+    assert extract_element(doctree, 0, 1)['uri'] == 'subdir/rimg.png'
 
-    assert isinstance(doctree[0][2], nodes.image)
-    assert doctree[0][2]['candidates'] == {
+    assert isinstance(extract_node(doctree, 0, 2), nodes.image)
+    assert extract_element(doctree, 0, 2)['candidates'] == {
         'application/pdf': 'subdir/svgimg.pdf',
         'image/svg+xml': 'subdir/svgimg.svg',
     }
-    assert doctree[0][2]['uri'] == 'subdir/svgimg.*'
+    assert extract_element(doctree, 0, 2)['uri'] == 'subdir/svgimg.*'
 
-    assert isinstance(doctree[0][3], nodes.figure)
-    assert isinstance(doctree[0][3][0], nodes.image)
-    assert doctree[0][3][0]['candidates'] == {
+    assert isinstance(extract_node(doctree, 0, 3), nodes.figure)
+    assert isinstance(extract_node(doctree, 0, 3, 0), nodes.image)
+    assert extract_element(doctree, 0, 3, 0)['candidates'] == {
         'application/pdf': 'subdir/svgimg.pdf',
         'image/svg+xml': 'subdir/svgimg.svg',
     }
-    assert doctree[0][3][0]['uri'] == 'subdir/svgimg.*'
+    assert extract_element(doctree, 0, 3, 0)['uri'] == 'subdir/svgimg.*'

tests/test_directives/test_directive_object_description.py

@@ -12,6 +12,8 @@
 from sphinx.testing import restructuredtext
 from sphinx.util.docutils import _parse_str_to_doctree
 
+from tests.utils import extract_node
+
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
     from sphinx.environment import BuildEnvironment
@@ -58,13 +60,13 @@ def test_object_description_sections(app: SphinxTestApp) -> None:
 
     assert isinstance(doctree[0], addnodes.index)
     assert isinstance(doctree[1], addnodes.desc)
-    assert isinstance(doctree[1][0], addnodes.desc_signature)
-    assert isinstance(doctree[1][1], addnodes.desc_content)
-    assert isinstance(doctree[1][1][0], nodes.section)
-    assert isinstance(doctree[1][1][0][0], nodes.title)
-    assert doctree[1][1][0][0][0] == 'Overview'
-    assert isinstance(doctree[1][1][0][1], nodes.paragraph)
-    assert doctree[1][1][0][1][0] == 'Lorem ipsum dolar sit amet'
+    assert isinstance(extract_node(doctree, 1, 0), addnodes.desc_signature)
+    assert isinstance(extract_node(doctree, 1, 1), addnodes.desc_content)
+    assert isinstance(extract_node(doctree, 1, 1, 0), nodes.section)
+    assert isinstance(extract_node(doctree, 1, 1, 0, 0), nodes.title)
+    assert extract_node(doctree, 1, 1, 0, 0, 0) == 'Overview'
+    assert isinstance(extract_node(doctree, 1, 1, 0, 1), nodes.paragraph)
+    assert extract_node(doctree, 1, 1, 0, 1, 0) == 'Lorem ipsum dolar sit amet'
 
 
 @pytest.mark.sphinx('html', testroot='_blank')

tests/test_directives/test_directive_other.py

@@ -12,6 +12,8 @@
 from sphinx.testing import restructuredtext
 from sphinx.testing.util import assert_node
 
+from tests.utils import extract_node
+
 if TYPE_CHECKING:
     from sphinx.testing.util import SphinxTestApp
 
@@ -24,7 +26,7 @@ def test_toctree(app):
     doctree = restructuredtext.parse(app, text, 'index')
     assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
     assert_node(
-        doctree[0][0],
+        extract_node(doctree, 0, 0),
         entries=[(None, 'foo'), (None, 'bar/index'), (None, 'baz')],
         includefiles=['foo', 'bar/index', 'baz'],
     )
@@ -38,7 +40,7 @@ def test_relative_toctree(app):
     doctree = restructuredtext.parse(app, text, 'bar/index')
     assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
     assert_node(
-        doctree[0][0],
+        extract_node(doctree, 0, 0),
         entries=[
             (None, 'bar/bar_1'),
             (None, 'bar/bar_2'),
@@ -63,7 +65,7 @@ def test_toctree_urls_and_titles(app):
     doctree = restructuredtext.parse(app, text, 'index')
     assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
     assert_node(
-        doctree[0][0],
+        extract_node(doctree, 0, 0),
         entries=[
             ('Sphinx', 'https://www.sphinx-doc.org/'),
             (None, 'https://readthedocs.org/'),
@@ -81,7 +83,7 @@ def test_toctree_glob(app):
     doctree = restructuredtext.parse(app, text, 'index')
     assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
     assert_node(
-        doctree[0][0],
+        extract_node(doctree, 0, 0),
         entries=[(None, 'baz'), (None, 'foo'), (None, 'quux')],
         includefiles=['baz', 'foo', 'quux'],
     )
@@ -93,7 +95,7 @@ def test_toctree_glob(app):
     doctree = restructuredtext.parse(app, text, 'index')
     assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
     assert_node(
-        doctree[0][0],
+        extract_node(doctree, 0, 0),
         entries=[(None, 'foo'), (None, 'baz'), (None, 'quux')],
         includefiles=['foo', 'baz', 'quux'],
     )
@@ -105,7 +107,7 @@ def test_toctree_glob(app):
     doctree = restructuredtext.parse(app, text, 'index')
     assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
     assert_node(
-        doctree[0][0],
+        extract_node(doctree, 0, 0),
         entries=[(None, 'baz'), (None, 'foo'), (None, 'quux'), (None, 'foo')],
         includefiles=['baz', 'foo', 'quux', 'foo'],
     )
@@ -119,7 +121,7 @@ def test_toctree_glob_and_url(app):
     doctree = restructuredtext.parse(app, text, 'index')
     assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
     assert_node(
-        doctree[0][0],
+        extract_node(doctree, 0, 0),
         entries=[(None, 'https://example.com/?q=sphinx')],
         includefiles=[],
     )
@@ -133,7 +135,7 @@ def test_reversed_toctree(app):
     doctree = restructuredtext.parse(app, text, 'index')
     assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
     assert_node(
-        doctree[0][0],
+        extract_node(doctree, 0, 0),
         entries=[(None, 'baz'), (None, 'bar/index'), (None, 'foo')],
         includefiles=['baz', 'bar/index', 'foo'],
     )
@@ -156,7 +158,7 @@ def test_toctree_twice(app):
     doctree = restructuredtext.parse(app, text, 'index')
     assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
     assert_node(
-        doctree[0][0],
+        extract_node(doctree, 0, 0),
         entries=[(None, 'foo'), (None, 'foo')],
         includefiles=['foo', 'foo'],
     )

tests/test_domains/test_domain_c.py

@@ -31,6 +31,8 @@
 from sphinx.util.cfamily import DefinitionError
 from sphinx.writers.text import STDINDENT
 
+from tests.utils import extract_node
+
 if TYPE_CHECKING:
     from io import StringIO
 
@@ -989,7 +991,7 @@ def test_cfunction_signature_with_c_maximum_signature_line_length_equal(app):
         no_index=False,
     )
     assert_node(
-        doctree[1][0][0][3],
+        extract_node(doctree, 1, 0, 0, 3),
         [
             desc_parameterlist,
             desc_parameter,
@@ -1001,7 +1003,9 @@ def test_cfunction_signature_with_c_maximum_signature_line_length_equal(app):
         ],
     )
     assert_node(
-        doctree[1][0][0][3], desc_parameterlist, multi_line_parameter_list=False
+        extract_node(doctree, 1, 0, 0, 3),
+        desc_parameterlist,
+        multi_line_parameter_list=False,
     )
 
 
@@ -1050,7 +1054,7 @@ def test_cfunction_signature_with_c_maximum_signature_line_length_force_single(a
         no_index=False,
     )
     assert_node(
-        doctree[1][0][0][3],
+        extract_node(doctree, 1, 0, 0, 3),
         [
             desc_parameterlist,
             desc_parameter,
@@ -1062,7 +1066,9 @@ def test_cfunction_signature_with_c_maximum_signature_line_length_force_single(a
         ],
     )
     assert_node(
-        doctree[1][0][0][3], desc_parameterlist, multi_line_parameter_list=False
+        extract_node(doctree, 1, 0, 0, 3),
+        desc_parameterlist,
+        multi_line_parameter_list=False,
     )
 
 
@@ -1111,7 +1117,7 @@ def test_cfunction_signature_with_c_maximum_signature_line_length_break(app):
         no_index=False,
     )
     assert_node(
-        doctree[1][0][0][3],
+        extract_node(doctree, 1, 0, 0, 3),
         [
             desc_parameterlist,
             desc_parameter,
@@ -1122,7 +1128,11 @@ def test_cfunction_signature_with_c_maximum_signature_line_length_break(app):
             ),
         ],
     )
-    assert_node(doctree[1][0][0][3], desc_parameterlist, multi_line_parameter_list=True)
+    assert_node(
+        extract_node(doctree, 1, 0, 0, 3),
+        desc_parameterlist,
+        multi_line_parameter_list=True,
+    )
 
 
 @pytest.mark.sphinx(
@@ -1170,7 +1180,7 @@ def test_cfunction_signature_with_maximum_signature_line_length_equal(app):
         no_index=False,
     )
     assert_node(
-        doctree[1][0][0][3],
+        extract_node(doctree, 1, 0, 0, 3),
         [
             desc_parameterlist,
             desc_parameter,
@@ -1182,7 +1192,9 @@ def test_cfunction_signature_with_maximum_signature_line_length_equal(app):
         ],
     )
     assert_node(
-        doctree[1][0][0][3], desc_parameterlist, multi_line_parameter_list=False
+        extract_node(doctree, 1, 0, 0, 3),
+        desc_parameterlist,
+        multi_line_parameter_list=False,
     )
 
 
@@ -1231,7 +1243,7 @@ def test_cfunction_signature_with_maximum_signature_line_length_force_single(app
         no_index=False,
     )
     assert_node(
-        doctree[1][0][0][3],
+        extract_node(doctree, 1, 0, 0, 3),
         [
             desc_parameterlist,
             desc_parameter,
@@ -1243,7 +1255,9 @@ def test_cfunction_signature_with_maximum_signature_line_length_force_single(app
         ],
     )
     assert_node(
-        doctree[1][0][0][3], desc_parameterlist, multi_line_parameter_list=False
+        extract_node(doctree, 1, 0, 0, 3),
+        desc_parameterlist,
+        multi_line_parameter_list=False,
     )
 
 
@@ -1292,7 +1306,7 @@ def test_cfunction_signature_with_maximum_signature_line_length_break(app):
         no_index=False,
     )
     assert_node(
-        doctree[1][0][0][3],
+        extract_node(doctree, 1, 0, 0, 3),
         [
             desc_parameterlist,
             desc_parameter,
@@ -1303,7 +1317,11 @@ def test_cfunction_signature_with_maximum_signature_line_length_break(app):
             ),
         ],
     )
-    assert_node(doctree[1][0][0][3], desc_parameterlist, multi_line_parameter_list=True)
+    assert_node(
+        extract_node(doctree, 1, 0, 0, 3),
+        desc_parameterlist,
+        multi_line_parameter_list=True,
+    )
 
 
 @pytest.mark.sphinx(
@@ -1350,7 +1368,7 @@ def test_c_maximum_signature_line_length_overrides_global(app):
         no_index=False,
     )
     assert_node(
-        doctree[1][0][0][3],
+        extract_node(doctree, 1, 0, 0, 3),
         [
             desc_parameterlist,
             desc_parameter,
@@ -1362,7 +1380,9 @@ def test_c_maximum_signature_line_length_overrides_global(app):
         ],
     )
     assert_node(
-        doctree[1][0][0][3], desc_parameterlist, multi_line_parameter_list=False
+        extract_node(doctree, 1, 0, 0, 3),
+        desc_parameterlist,
+        multi_line_parameter_list=False,
     )