1"""
2    test_ext_autodoc_autoattribute
3    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4
5    Test the autodoc extension.  This tests mainly the Documenters; the auto
6    directives are tested in a test source file translated by test_build.
7
8    :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
9    :license: BSD, see LICENSE for details.
10"""
11
12import sys
13
14import pytest
15
16from .test_ext_autodoc import do_autodoc
17
18
19@pytest.mark.sphinx('html', testroot='ext-autodoc')
20def test_autoattribute(app):
21    actual = do_autodoc(app, 'attribute', 'target.Class.attr')
22    assert list(actual) == [
23        '',
24        '.. py:attribute:: Class.attr',
25        '   :module: target',
26        "   :value: 'bar'",
27        '',
28        '   should be documented -- süß',
29        '',
30    ]
31
32
33@pytest.mark.sphinx('html', testroot='ext-autodoc')
34def test_autoattribute_novalue(app):
35    options = {'no-value': True}
36    actual = do_autodoc(app, 'attribute', 'target.Class.attr', options)
37    assert list(actual) == [
38        '',
39        '.. py:attribute:: Class.attr',
40        '   :module: target',
41        '',
42        '   should be documented -- süß',
43        '',
44    ]
45
46
47@pytest.mark.skipif(sys.version_info < (3, 6), reason='python 3.6+ is required.')
48@pytest.mark.sphinx('html', testroot='ext-autodoc')
49def test_autoattribute_typed_variable(app):
50    actual = do_autodoc(app, 'attribute', 'target.typed_vars.Class.attr2')
51    assert list(actual) == [
52        '',
53        '.. py:attribute:: Class.attr2',
54        '   :module: target.typed_vars',
55        '   :type: int',
56        '',
57    ]
58
59
60@pytest.mark.skipif(sys.version_info < (3, 6), reason='python 3.6+ is required.')
61@pytest.mark.sphinx('html', testroot='ext-autodoc')
62def test_autoattribute_typed_variable_in_alias(app):
63    actual = do_autodoc(app, 'attribute', 'target.typed_vars.Alias.attr2')
64    assert list(actual) == [
65        '',
66        '.. py:attribute:: Alias.attr2',
67        '   :module: target.typed_vars',
68        '   :type: int',
69        '',
70    ]
71
72
73@pytest.mark.skipif(sys.version_info < (3, 6), reason='python 3.6+ is required.')
74@pytest.mark.sphinx('html', testroot='ext-autodoc')
75def test_autoattribute_instance_variable(app):
76    actual = do_autodoc(app, 'attribute', 'target.typed_vars.Class.attr4')
77    assert list(actual) == [
78        '',
79        '.. py:attribute:: Class.attr4',
80        '   :module: target.typed_vars',
81        '   :type: int',
82        '',
83        '   attr4',
84        '',
85    ]
86
87
88@pytest.mark.skipif(sys.version_info < (3, 6), reason='python 3.6+ is required.')
89@pytest.mark.sphinx('html', testroot='ext-autodoc')
90def test_autoattribute_instance_variable_in_alias(app):
91    actual = do_autodoc(app, 'attribute', 'target.typed_vars.Alias.attr4')
92    assert list(actual) == [
93        '',
94        '.. py:attribute:: Alias.attr4',
95        '   :module: target.typed_vars',
96        '   :type: int',
97        '',
98        '   attr4',
99        '',
100    ]
101
102
103@pytest.mark.sphinx('html', testroot='ext-autodoc')
104def test_autoattribute_slots_variable_list(app):
105    actual = do_autodoc(app, 'attribute', 'target.slots.Foo.attr')
106    assert list(actual) == [
107        '',
108        '.. py:attribute:: Foo.attr',
109        '   :module: target.slots',
110        '',
111    ]
112
113
114@pytest.mark.sphinx('html', testroot='ext-autodoc')
115def test_autoattribute_slots_variable_dict(app):
116    actual = do_autodoc(app, 'attribute', 'target.slots.Bar.attr1')
117    assert list(actual) == [
118        '',
119        '.. py:attribute:: Bar.attr1',
120        '   :module: target.slots',
121        '',
122        '   docstring of attr1',
123        '',
124    ]
125
126
127@pytest.mark.sphinx('html', testroot='ext-autodoc')
128def test_autoattribute_slots_variable_str(app):
129    actual = do_autodoc(app, 'attribute', 'target.slots.Baz.attr')
130    assert list(actual) == [
131        '',
132        '.. py:attribute:: Baz.attr',
133        '   :module: target.slots',
134        '',
135    ]
136
137
138@pytest.mark.sphinx('html', testroot='ext-autodoc')
139def test_autoattribute_GenericAlias(app):
140    actual = do_autodoc(app, 'attribute', 'target.genericalias.Class.T')
141    if sys.version_info < (3, 7):
142        assert list(actual) == [
143            '',
144            '.. py:attribute:: Class.T',
145            '   :module: target.genericalias',
146            '   :value: typing.List[int]',
147            '',
148            '   A list of int',
149            '',
150        ]
151    else:
152        assert list(actual) == [
153            '',
154            '.. py:attribute:: Class.T',
155            '   :module: target.genericalias',
156            '',
157            '   A list of int',
158            '',
159            '   alias of List[int]',
160            '',
161        ]
162
163
164@pytest.mark.sphinx('html', testroot='ext-autodoc')
165def test_autoattribute_NewType(app):
166    actual = do_autodoc(app, 'attribute', 'target.typevar.Class.T6')
167    assert list(actual) == [
168        '',
169        '.. py:attribute:: Class.T6',
170        '   :module: target.typevar',
171        '',
172        '   T6',
173        '',
174        '   alias of :class:`int`',
175        '',
176    ]
177
178
179@pytest.mark.sphinx('html', testroot='ext-autodoc')
180def test_autoattribute_TypeVar(app):
181    actual = do_autodoc(app, 'attribute', 'target.typevar.Class.T1')
182    assert list(actual) == [
183        '',
184        '.. py:attribute:: Class.T1',
185        '   :module: target.typevar',
186        '',
187        '   T1',
188        '',
189        "   alias of TypeVar('T1')",
190        '',
191    ]
192
193
194@pytest.mark.skipif(sys.version_info < (3, 6), reason='python 3.6+ is required.')
195@pytest.mark.sphinx('html', testroot='ext-autodoc')
196def test_autoattribute_hide_value(app):
197    actual = do_autodoc(app, 'attribute', 'target.hide_value.Foo.SENTINEL1')
198    assert list(actual) == [
199        '',
200        '.. py:attribute:: Foo.SENTINEL1',
201        '   :module: target.hide_value',
202        '',
203        '   docstring',
204        '',
205        '   :meta hide-value:',
206        '',
207    ]
208
209    actual = do_autodoc(app, 'attribute', 'target.hide_value.Foo.SENTINEL2')
210    assert list(actual) == [
211        '',
212        '.. py:attribute:: Foo.SENTINEL2',
213        '   :module: target.hide_value',
214        '',
215        '   :meta hide-value:',
216        '',
217    ]
218