Skip to content

Commit 9257a4f

Browse files
danieleadesdaniel.eadesAA-Turner
authored
Improve type annotations with an 'extract_node' test utility (sphinx-doc#14151)
Co-authored-by: daniel.eades <daniel.eades@seebyte.com> Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
1 parent eb4d0da commit 9257a4f

18 files changed

+649
-408
lines changed

‎tests/test_builders/test_build.py‎

Lines changed: 26 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@
99

1010
from sphinx.errors import SphinxError
1111

12+
from tests.utils import extract_element, extract_node
13+
1214
if TYPE_CHECKING:
1315
from collections.abc import Callable
1416
from pathlib import Path
@@ -68,51 +70,51 @@ def test_image_glob(app: SphinxTestApp) -> None:
6870
doctree = app.env.get_doctree('index')
6971
assert isinstance(doctree[0], nodes.Element)
7072

71-
assert isinstance(doctree[0][1], nodes.image)
72-
assert doctree[0][1]['candidates'] == {'*': 'rimg.png'}
73-
assert doctree[0][1]['uri'] == 'rimg.png'
73+
assert isinstance(extract_node(doctree, 0, 1), nodes.image)
74+
assert extract_element(doctree, 0, 1)['candidates'] == {'*': 'rimg.png'}
75+
assert extract_element(doctree, 0, 1)['uri'] == 'rimg.png'
7476

75-
assert isinstance(doctree[0][2], nodes.figure)
76-
assert isinstance(doctree[0][2][0], nodes.image)
77-
assert doctree[0][2][0]['candidates'] == {'*': 'rimg.png'}
78-
assert doctree[0][2][0]['uri'] == 'rimg.png'
77+
assert isinstance(extract_node(doctree, 0, 2), nodes.figure)
78+
assert isinstance(extract_node(doctree, 0, 2, 0), nodes.image)
79+
assert extract_element(doctree, 0, 2, 0)['candidates'] == {'*': 'rimg.png'}
80+
assert extract_element(doctree, 0, 2, 0)['uri'] == 'rimg.png'
7981

80-
assert isinstance(doctree[0][3], nodes.image)
81-
assert doctree[0][3]['candidates'] == {
82+
assert isinstance(extract_node(doctree, 0, 3), nodes.image)
83+
assert extract_element(doctree, 0, 3)['candidates'] == {
8284
'application/pdf': 'img.pdf',
8385
'image/gif': 'img.gif',
8486
'image/png': 'img.png',
8587
}
86-
assert doctree[0][3]['uri'] == 'img.*'
88+
assert extract_element(doctree, 0, 3)['uri'] == 'img.*'
8789

88-
assert isinstance(doctree[0][4], nodes.figure)
89-
assert isinstance(doctree[0][4][0], nodes.image)
90-
assert doctree[0][4][0]['candidates'] == {
90+
assert isinstance(extract_node(doctree, 0, 4), nodes.figure)
91+
assert isinstance(extract_node(doctree, 0, 4, 0), nodes.image)
92+
assert extract_element(doctree, 0, 4, 0)['candidates'] == {
9193
'application/pdf': 'img.pdf',
9294
'image/gif': 'img.gif',
9395
'image/png': 'img.png',
9496
}
95-
assert doctree[0][4][0]['uri'] == 'img.*'
97+
assert extract_element(doctree, 0, 4, 0)['uri'] == 'img.*'
9698

9799
# subdir/index.rst
98100
doctree = app.env.get_doctree('subdir/index')
99101
assert isinstance(doctree[0], nodes.Element)
100102

101-
assert isinstance(doctree[0][1], nodes.image)
102-
assert doctree[0][1]['candidates'] == {'*': 'subdir/rimg.png'}
103-
assert doctree[0][1]['uri'] == 'subdir/rimg.png'
103+
assert isinstance(extract_node(doctree, 0, 1), nodes.image)
104+
assert extract_element(doctree, 0, 1)['candidates'] == {'*': 'subdir/rimg.png'}
105+
assert extract_element(doctree, 0, 1)['uri'] == 'subdir/rimg.png'
104106

105-
assert isinstance(doctree[0][2], nodes.image)
106-
assert doctree[0][2]['candidates'] == {
107+
assert isinstance(extract_node(doctree, 0, 2), nodes.image)
108+
assert extract_element(doctree, 0, 2)['candidates'] == {
107109
'application/pdf': 'subdir/svgimg.pdf',
108110
'image/svg+xml': 'subdir/svgimg.svg',
109111
}
110-
assert doctree[0][2]['uri'] == 'subdir/svgimg.*'
112+
assert extract_element(doctree, 0, 2)['uri'] == 'subdir/svgimg.*'
111113

112-
assert isinstance(doctree[0][3], nodes.figure)
113-
assert isinstance(doctree[0][3][0], nodes.image)
114-
assert doctree[0][3][0]['candidates'] == {
114+
assert isinstance(extract_node(doctree, 0, 3), nodes.figure)
115+
assert isinstance(extract_node(doctree, 0, 3, 0), nodes.image)
116+
assert extract_element(doctree, 0, 3, 0)['candidates'] == {
115117
'application/pdf': 'subdir/svgimg.pdf',
116118
'image/svg+xml': 'subdir/svgimg.svg',
117119
}
118-
assert doctree[0][3][0]['uri'] == 'subdir/svgimg.*'
120+
assert extract_element(doctree, 0, 3, 0)['uri'] == 'subdir/svgimg.*'

‎tests/test_directives/test_directive_object_description.py‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@
1212
from sphinx.testing import restructuredtext
1313
from sphinx.util.docutils import _parse_str_to_doctree
1414

15+
from tests.utils import extract_node
16+
1517
if TYPE_CHECKING:
1618
from sphinx.application import Sphinx
1719
from sphinx.environment import BuildEnvironment
@@ -58,13 +60,13 @@ def test_object_description_sections(app: SphinxTestApp) -> None:
5860

5961
assert isinstance(doctree[0], addnodes.index)
6062
assert isinstance(doctree[1], addnodes.desc)
61-
assert isinstance(doctree[1][0], addnodes.desc_signature)
62-
assert isinstance(doctree[1][1], addnodes.desc_content)
63-
assert isinstance(doctree[1][1][0], nodes.section)
64-
assert isinstance(doctree[1][1][0][0], nodes.title)
65-
assert doctree[1][1][0][0][0] == 'Overview'
66-
assert isinstance(doctree[1][1][0][1], nodes.paragraph)
67-
assert doctree[1][1][0][1][0] == 'Lorem ipsum dolar sit amet'
63+
assert isinstance(extract_node(doctree, 1, 0), addnodes.desc_signature)
64+
assert isinstance(extract_node(doctree, 1, 1), addnodes.desc_content)
65+
assert isinstance(extract_node(doctree, 1, 1, 0), nodes.section)
66+
assert isinstance(extract_node(doctree, 1, 1, 0, 0), nodes.title)
67+
assert extract_node(doctree, 1, 1, 0, 0, 0) == 'Overview'
68+
assert isinstance(extract_node(doctree, 1, 1, 0, 1), nodes.paragraph)
69+
assert extract_node(doctree, 1, 1, 0, 1, 0) == 'Lorem ipsum dolar sit amet'
6870

6971

7072
@pytest.mark.sphinx('html', testroot='_blank')

‎tests/test_directives/test_directive_other.py‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@
1212
from sphinx.testing import restructuredtext
1313
from sphinx.testing.util import assert_node
1414

15+
from tests.utils import extract_node
16+
1517
if TYPE_CHECKING:
1618
from sphinx.testing.util import SphinxTestApp
1719

@@ -24,7 +26,7 @@ def test_toctree(app):
2426
doctree = restructuredtext.parse(app, text, 'index')
2527
assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
2628
assert_node(
27-
doctree[0][0],
29+
extract_node(doctree, 0, 0),
2830
entries=[(None, 'foo'), (None, 'bar/index'), (None, 'baz')],
2931
includefiles=['foo', 'bar/index', 'baz'],
3032
)
@@ -38,7 +40,7 @@ def test_relative_toctree(app):
3840
doctree = restructuredtext.parse(app, text, 'bar/index')
3941
assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
4042
assert_node(
41-
doctree[0][0],
43+
extract_node(doctree, 0, 0),
4244
entries=[
4345
(None, 'bar/bar_1'),
4446
(None, 'bar/bar_2'),
@@ -63,7 +65,7 @@ def test_toctree_urls_and_titles(app):
6365
doctree = restructuredtext.parse(app, text, 'index')
6466
assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
6567
assert_node(
66-
doctree[0][0],
68+
extract_node(doctree, 0, 0),
6769
entries=[
6870
('Sphinx', 'https://www.sphinx-doc.org/'),
6971
(None, 'https://readthedocs.org/'),
@@ -81,7 +83,7 @@ def test_toctree_glob(app):
8183
doctree = restructuredtext.parse(app, text, 'index')
8284
assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
8385
assert_node(
84-
doctree[0][0],
86+
extract_node(doctree, 0, 0),
8587
entries=[(None, 'baz'), (None, 'foo'), (None, 'quux')],
8688
includefiles=['baz', 'foo', 'quux'],
8789
)
@@ -93,7 +95,7 @@ def test_toctree_glob(app):
9395
doctree = restructuredtext.parse(app, text, 'index')
9496
assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
9597
assert_node(
96-
doctree[0][0],
98+
extract_node(doctree, 0, 0),
9799
entries=[(None, 'foo'), (None, 'baz'), (None, 'quux')],
98100
includefiles=['foo', 'baz', 'quux'],
99101
)
@@ -105,7 +107,7 @@ def test_toctree_glob(app):
105107
doctree = restructuredtext.parse(app, text, 'index')
106108
assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
107109
assert_node(
108-
doctree[0][0],
110+
extract_node(doctree, 0, 0),
109111
entries=[(None, 'baz'), (None, 'foo'), (None, 'quux'), (None, 'foo')],
110112
includefiles=['baz', 'foo', 'quux', 'foo'],
111113
)
@@ -119,7 +121,7 @@ def test_toctree_glob_and_url(app):
119121
doctree = restructuredtext.parse(app, text, 'index')
120122
assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
121123
assert_node(
122-
doctree[0][0],
124+
extract_node(doctree, 0, 0),
123125
entries=[(None, 'https://example.com/?q=sphinx')],
124126
includefiles=[],
125127
)
@@ -133,7 +135,7 @@ def test_reversed_toctree(app):
133135
doctree = restructuredtext.parse(app, text, 'index')
134136
assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
135137
assert_node(
136-
doctree[0][0],
138+
extract_node(doctree, 0, 0),
137139
entries=[(None, 'baz'), (None, 'bar/index'), (None, 'foo')],
138140
includefiles=['baz', 'bar/index', 'foo'],
139141
)
@@ -156,7 +158,7 @@ def test_toctree_twice(app):
156158
doctree = restructuredtext.parse(app, text, 'index')
157159
assert_node(doctree, [nodes.document, nodes.compound, addnodes.toctree])
158160
assert_node(
159-
doctree[0][0],
161+
extract_node(doctree, 0, 0),
160162
entries=[(None, 'foo'), (None, 'foo')],
161163
includefiles=['foo', 'foo'],
162164
)

‎tests/test_domains/test_domain_c.py‎

Lines changed: 34 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@
3131
from sphinx.util.cfamily import DefinitionError
3232
from sphinx.writers.text import STDINDENT
3333

34+
from tests.utils import extract_node
35+
3436
if TYPE_CHECKING:
3537
from io import StringIO
3638

@@ -989,7 +991,7 @@ def test_cfunction_signature_with_c_maximum_signature_line_length_equal(app):
989991
no_index=False,
990992
)
991993
assert_node(
992-
doctree[1][0][0][3],
994+
extract_node(doctree, 1, 0, 0, 3),
993995
[
994996
desc_parameterlist,
995997
desc_parameter,
@@ -1001,7 +1003,9 @@ def test_cfunction_signature_with_c_maximum_signature_line_length_equal(app):
10011003
],
10021004
)
10031005
assert_node(
1004-
doctree[1][0][0][3], desc_parameterlist, multi_line_parameter_list=False
1006+
extract_node(doctree, 1, 0, 0, 3),
1007+
desc_parameterlist,
1008+
multi_line_parameter_list=False,
10051009
)
10061010

10071011

@@ -1050,7 +1054,7 @@ def test_cfunction_signature_with_c_maximum_signature_line_length_force_single(a
10501054
no_index=False,
10511055
)
10521056
assert_node(
1053-
doctree[1][0][0][3],
1057+
extract_node(doctree, 1, 0, 0, 3),
10541058
[
10551059
desc_parameterlist,
10561060
desc_parameter,
@@ -1062,7 +1066,9 @@ def test_cfunction_signature_with_c_maximum_signature_line_length_force_single(a
10621066
],
10631067
)
10641068
assert_node(
1065-
doctree[1][0][0][3], desc_parameterlist, multi_line_parameter_list=False
1069+
extract_node(doctree, 1, 0, 0, 3),
1070+
desc_parameterlist,
1071+
multi_line_parameter_list=False,
10661072
)
10671073

10681074

@@ -1111,7 +1117,7 @@ def test_cfunction_signature_with_c_maximum_signature_line_length_break(app):
11111117
no_index=False,
11121118
)
11131119
assert_node(
1114-
doctree[1][0][0][3],
1120+
extract_node(doctree, 1, 0, 0, 3),
11151121
[
11161122
desc_parameterlist,
11171123
desc_parameter,
@@ -1122,7 +1128,11 @@ def test_cfunction_signature_with_c_maximum_signature_line_length_break(app):
11221128
),
11231129
],
11241130
)
1125-
assert_node(doctree[1][0][0][3], desc_parameterlist, multi_line_parameter_list=True)
1131+
assert_node(
1132+
extract_node(doctree, 1, 0, 0, 3),
1133+
desc_parameterlist,
1134+
multi_line_parameter_list=True,
1135+
)
11261136

11271137

11281138
@pytest.mark.sphinx(
@@ -1170,7 +1180,7 @@ def test_cfunction_signature_with_maximum_signature_line_length_equal(app):
11701180
no_index=False,
11711181
)
11721182
assert_node(
1173-
doctree[1][0][0][3],
1183+
extract_node(doctree, 1, 0, 0, 3),
11741184
[
11751185
desc_parameterlist,
11761186
desc_parameter,
@@ -1182,7 +1192,9 @@ def test_cfunction_signature_with_maximum_signature_line_length_equal(app):
11821192
],
11831193
)
11841194
assert_node(
1185-
doctree[1][0][0][3], desc_parameterlist, multi_line_parameter_list=False
1195+
extract_node(doctree, 1, 0, 0, 3),
1196+
desc_parameterlist,
1197+
multi_line_parameter_list=False,
11861198
)
11871199

11881200

@@ -1231,7 +1243,7 @@ def test_cfunction_signature_with_maximum_signature_line_length_force_single(app
12311243
no_index=False,
12321244
)
12331245
assert_node(
1234-
doctree[1][0][0][3],
1246+
extract_node(doctree, 1, 0, 0, 3),
12351247
[
12361248
desc_parameterlist,
12371249
desc_parameter,
@@ -1243,7 +1255,9 @@ def test_cfunction_signature_with_maximum_signature_line_length_force_single(app
12431255
],
12441256
)
12451257
assert_node(
1246-
doctree[1][0][0][3], desc_parameterlist, multi_line_parameter_list=False
1258+
extract_node(doctree, 1, 0, 0, 3),
1259+
desc_parameterlist,
1260+
multi_line_parameter_list=False,
12471261
)
12481262

12491263

@@ -1292,7 +1306,7 @@ def test_cfunction_signature_with_maximum_signature_line_length_break(app):
12921306
no_index=False,
12931307
)
12941308
assert_node(
1295-
doctree[1][0][0][3],
1309+
extract_node(doctree, 1, 0, 0, 3),
12961310
[
12971311
desc_parameterlist,
12981312
desc_parameter,
@@ -1303,7 +1317,11 @@ def test_cfunction_signature_with_maximum_signature_line_length_break(app):
13031317
),
13041318
],
13051319
)
1306-
assert_node(doctree[1][0][0][3], desc_parameterlist, multi_line_parameter_list=True)
1320+
assert_node(
1321+
extract_node(doctree, 1, 0, 0, 3),
1322+
desc_parameterlist,
1323+
multi_line_parameter_list=True,
1324+
)
13071325

13081326

13091327
@pytest.mark.sphinx(
@@ -1350,7 +1368,7 @@ def test_c_maximum_signature_line_length_overrides_global(app):
13501368
no_index=False,
13511369
)
13521370
assert_node(
1353-
doctree[1][0][0][3],
1371+
extract_node(doctree, 1, 0, 0, 3),
13541372
[
13551373
desc_parameterlist,
13561374
desc_parameter,
@@ -1362,7 +1380,9 @@ def test_c_maximum_signature_line_length_overrides_global(app):
13621380
],
13631381
)
13641382
assert_node(
1365-
doctree[1][0][0][3], desc_parameterlist, multi_line_parameter_list=False
1383+
extract_node(doctree, 1, 0, 0, 3),
1384+
desc_parameterlist,
1385+
multi_line_parameter_list=False,
13661386
)
13671387

13681388

0 commit comments

Comments
 (0)