1"""
2    test_ext_autodoc_autofunction
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_classes(app):
21    actual = do_autodoc(app, 'function', 'target.classes.Foo')
22    assert list(actual) == [
23        '',
24        '.. py:function:: Foo()',
25        '   :module: target.classes',
26        '',
27    ]
28
29    actual = do_autodoc(app, 'function', 'target.classes.Bar')
30    assert list(actual) == [
31        '',
32        '.. py:function:: Bar(x, y)',
33        '   :module: target.classes',
34        '',
35    ]
36
37    actual = do_autodoc(app, 'function', 'target.classes.Baz')
38    assert list(actual) == [
39        '',
40        '.. py:function:: Baz(x, y)',
41        '   :module: target.classes',
42        '',
43    ]
44
45    actual = do_autodoc(app, 'function', 'target.classes.Qux')
46    assert list(actual) == [
47        '',
48        '.. py:function:: Qux(foo, bar)',
49        '   :module: target.classes',
50        '',
51    ]
52
53
54@pytest.mark.sphinx('html', testroot='ext-autodoc')
55def test_callable(app):
56    actual = do_autodoc(app, 'function', 'target.callable.function')
57    assert list(actual) == [
58        '',
59        '.. py:function:: function(arg1, arg2, **kwargs)',
60        '   :module: target.callable',
61        '',
62        '   A callable object that behaves like a function.',
63        '',
64    ]
65
66
67@pytest.mark.sphinx('html', testroot='ext-autodoc')
68def test_method(app):
69    actual = do_autodoc(app, 'function', 'target.callable.method')
70    assert list(actual) == [
71        '',
72        '.. py:function:: method(arg1, arg2)',
73        '   :module: target.callable',
74        '',
75        '   docstring of Callable.method().',
76        '',
77    ]
78
79
80@pytest.mark.sphinx('html', testroot='ext-autodoc')
81def test_builtin_function(app):
82    actual = do_autodoc(app, 'function', 'os.umask')
83    assert list(actual) == [
84        '',
85        '.. py:function:: umask(mask, /)',
86        '   :module: os',
87        '',
88        '   Set the current numeric umask and return the previous umask.',
89        '',
90    ]
91
92
93@pytest.mark.sphinx('html', testroot='ext-autodoc')
94def test_methoddescriptor(app):
95    actual = do_autodoc(app, 'function', 'builtins.int.__add__')
96    assert list(actual) == [
97        '',
98        '.. py:function:: __add__(self, value, /)',
99        '   :module: builtins.int',
100        '',
101        '   Return self+value.',
102        '',
103    ]
104
105
106@pytest.mark.sphinx('html', testroot='ext-autodoc')
107def test_decorated(app):
108    actual = do_autodoc(app, 'function', 'target.decorator.foo')
109    assert list(actual) == [
110        '',
111        '.. py:function:: foo(name=None, age=None)',
112        '   :module: target.decorator',
113        '',
114    ]
115
116
117@pytest.mark.sphinx('html', testroot='ext-autodoc')
118def test_singledispatch(app):
119    options = {}
120    actual = do_autodoc(app, 'function', 'target.singledispatch.func', options)
121    if sys.version_info < (3, 6):
122        # check the result via "in" because the order of singledispatch signatures is
123        # usually changed (because dict is not OrderedDict yet!)
124        assert '.. py:function:: func(arg, kwarg=None)' in actual
125        assert '                 func(arg: int, kwarg=None)' in actual
126        assert '                 func(arg: str, kwarg=None)' in actual
127    else:
128        assert list(actual) == [
129            '',
130            '.. py:function:: func(arg, kwarg=None)',
131            '                 func(arg: int, kwarg=None)',
132            '                 func(arg: str, kwarg=None)',
133            '   :module: target.singledispatch',
134            '',
135            '   A function for general use.',
136            '',
137        ]
138
139
140@pytest.mark.sphinx('html', testroot='ext-autodoc')
141def test_cfunction(app):
142    actual = do_autodoc(app, 'function', 'time.asctime')
143    assert list(actual) == [
144        '',
145        '.. py:function:: asctime([tuple]) -> string',
146        '   :module: time',
147        '',
148        "   Convert a time tuple to a string, e.g. 'Sat Jun 06 16:26:11 1998'.",
149        '   When the time tuple is not present, current time as returned by localtime()',
150        '   is used.',
151        '',
152    ]
153
154
155@pytest.mark.sphinx('html', testroot='ext-autodoc')
156def test_wrapped_function(app):
157    actual = do_autodoc(app, 'function', 'target.wrappedfunction.slow_function')
158    assert list(actual) == [
159        '',
160        '.. py:function:: slow_function(message, timeout)',
161        '   :module: target.wrappedfunction',
162        '',
163        '   This function is slow.',
164        '',
165    ]
166
167
168@pytest.mark.sphinx('html', testroot='ext-autodoc')
169def test_wrapped_function_contextmanager(app):
170    actual = do_autodoc(app, 'function', 'target.wrappedfunction.feeling_good')
171    assert list(actual) == [
172        '',
173        '.. py:function:: feeling_good(x: int, y: int) -> Generator',
174        '   :module: target.wrappedfunction',
175        '',
176        "   You'll feel better in this context!",
177        '',
178    ]
179