diff options
Diffstat (limited to 'numpydoc/tests/test_docscrape.py')
| -rw-r--r-- | numpydoc/tests/test_docscrape.py | 603 |
1 files changed, 356 insertions, 247 deletions
diff --git a/numpydoc/tests/test_docscrape.py b/numpydoc/tests/test_docscrape.py index 9644008..01447a0 100644 --- a/numpydoc/tests/test_docscrape.py +++ b/numpydoc/tests/test_docscrape.py @@ -8,20 +8,19 @@ import jinja2 from numpydoc.numpydoc import update_config from numpydoc.xref import DEFAULT_LINKS -from numpydoc.docscrape import ( - NumpyDocString, - FunctionDoc, - ClassDoc, - ParseError +from numpydoc.docscrape import NumpyDocString, FunctionDoc, ClassDoc, ParseError +from numpydoc.docscrape_sphinx import ( + SphinxDocString, + SphinxClassDoc, + SphinxFunctionDoc, + get_doc_object, ) -from numpydoc.docscrape_sphinx import (SphinxDocString, SphinxClassDoc, - SphinxFunctionDoc, get_doc_object) import pytest from pytest import raises as assert_raises from pytest import warns as assert_warns -doc_txt = '''\ +doc_txt = """\ numpy.multivariate_normal(mean, cov, shape=None, spam=None) Draw values from a multivariate normal distribution with specified @@ -131,11 +130,12 @@ doc_txt = '''\ .. index:: random :refguide: random;distributions, random;gauss - ''' + """ -@pytest.fixture(params=['','\n '], ids=["flush", "newline_indented"]) + +@pytest.fixture(params=["", "\n "], ids=["flush", "newline_indented"]) def doc(request): - return NumpyDocString(request.param+doc_txt) + return NumpyDocString(request.param + doc_txt) doc_yields_txt = """ @@ -173,92 +173,92 @@ doc_sent = NumpyDocString(doc_sent_txt) def test_signature(doc): - assert doc['Signature'].startswith('numpy.multivariate_normal(') - assert doc['Signature'].endswith('spam=None)') + assert doc["Signature"].startswith("numpy.multivariate_normal(") + assert doc["Signature"].endswith("spam=None)") def test_summary(doc): - assert doc['Summary'][0].startswith('Draw values') - assert doc['Summary'][-1].endswith('covariance.') + assert doc["Summary"][0].startswith("Draw values") + assert doc["Summary"][-1].endswith("covariance.") def test_extended_summary(doc): - assert doc['Extended Summary'][0].startswith('The multivariate normal') + assert doc["Extended Summary"][0].startswith("The multivariate normal") def test_parameters(doc): - assert len(doc['Parameters']) == 4 - names = [n for n, _, _ in doc['Parameters']] - assert all(a == b for a, b in zip(names, ['mean', 'cov', 'shape'])) + assert len(doc["Parameters"]) == 4 + names = [n for n, _, _ in doc["Parameters"]] + assert all(a == b for a, b in zip(names, ["mean", "cov", "shape"])) - arg, arg_type, desc = doc['Parameters'][1] - assert arg_type == '(N, N) ndarray' - assert desc[0].startswith('Covariance matrix') - assert doc['Parameters'][0][-1][-1] == ' (1+2+3)/3' + arg, arg_type, desc = doc["Parameters"][1] + assert arg_type == "(N, N) ndarray" + assert desc[0].startswith("Covariance matrix") + assert doc["Parameters"][0][-1][-1] == " (1+2+3)/3" - arg, arg_type, desc = doc['Parameters'][2] - assert arg == 'shape' - assert arg_type == 'tuple of ints' - assert desc[0].startswith('Given') - assert doc['Parameters'][0][-1][-1] == ' (1+2+3)/3' + arg, arg_type, desc = doc["Parameters"][2] + assert arg == "shape" + assert arg_type == "tuple of ints" + assert desc[0].startswith("Given") + assert doc["Parameters"][0][-1][-1] == " (1+2+3)/3" - arg, arg_type, desc = doc['Parameters'][3] - assert arg == 'dtype' - assert arg_type == 'data type object, optional (default : float)' - assert desc[0].startswith('The type and size') + arg, arg_type, desc = doc["Parameters"][3] + assert arg == "dtype" + assert arg_type == "data type object, optional (default : float)" + assert desc[0].startswith("The type and size") def test_other_parameters(doc): - assert len(doc['Other Parameters']) == 1 - assert [n for n, _, _ in doc['Other Parameters']] == ['spam'] - arg, arg_type, desc = doc['Other Parameters'][0] - assert arg_type == 'parrot' - assert desc[0].startswith('A parrot off its mortal coil') - + assert len(doc["Other Parameters"]) == 1 + assert [n for n, _, _ in doc["Other Parameters"]] == ["spam"] + arg, arg_type, desc = doc["Other Parameters"][0] + assert arg_type == "parrot" + assert desc[0].startswith("A parrot off its mortal coil") def test_returns(doc): - assert len(doc['Returns']) == 3 - arg, arg_type, desc = doc['Returns'][0] - assert arg == 'out' - assert arg_type == 'ndarray' - assert desc[0].startswith('The drawn samples') - assert desc[-1].endswith('distribution.') + assert len(doc["Returns"]) == 3 + arg, arg_type, desc = doc["Returns"][0] + assert arg == "out" + assert arg_type == "ndarray" + assert desc[0].startswith("The drawn samples") + assert desc[-1].endswith("distribution.") - arg, arg_type, desc = doc['Returns'][1] - assert arg == '' - assert arg_type == 'list of str' - assert desc[0].startswith('This is not a real') - assert desc[-1].endswith('anonymous return values.') + arg, arg_type, desc = doc["Returns"][1] + assert arg == "" + assert arg_type == "list of str" + assert desc[0].startswith("This is not a real") + assert desc[-1].endswith("anonymous return values.") - arg, arg_type, desc = doc['Returns'][2] - assert arg == '' - assert arg_type == 'no_description' - assert not ''.join(desc).strip() + arg, arg_type, desc = doc["Returns"][2] + assert arg == "" + assert arg_type == "no_description" + assert not "".join(desc).strip() def test_yields(): - section = doc_yields['Yields'] + section = doc_yields["Yields"] assert len(section) == 3 - truth = [('a', 'int', 'apples.'), - ('b', 'int', 'bananas.'), - ('', 'int', 'unknowns.')] + truth = [ + ("a", "int", "apples."), + ("b", "int", "bananas."), + ("", "int", "unknowns."), + ] for (arg, arg_type, desc), (arg_, arg_type_, end) in zip(section, truth): assert arg == arg_ assert arg_type == arg_type_ - assert desc[0].startswith('The number of') + assert desc[0].startswith("The number of") assert desc[0].endswith(end) def test_sent(): - section = doc_sent['Receives'] + section = doc_sent["Receives"] assert len(section) == 2 - truth = [('b', 'int', 'bananas.'), - ('c', 'int', 'oranges.')] + truth = [("b", "int", "bananas."), ("c", "int", "oranges.")] for (arg, arg_type, desc), (arg_, arg_type_, end) in zip(section, truth): assert arg == arg_ assert arg_type == arg_type_ - assert desc[0].startswith('The number of') + assert desc[0].startswith("The number of") assert desc[0].endswith(end) @@ -311,6 +311,7 @@ That should break... Second note. """ + def spam(self, a, b): """Spam\n\nSpam spam.""" pass @@ -340,40 +341,40 @@ That should break... def test_notes(doc): - assert doc['Notes'][0].startswith('Instead') - assert doc['Notes'][-1].endswith('definite.') - assert len(doc['Notes']) == 17 + assert doc["Notes"][0].startswith("Instead") + assert doc["Notes"][-1].endswith("definite.") + assert len(doc["Notes"]) == 17 def test_references(doc): - assert doc['References'][0].startswith('..') - assert doc['References'][-1].endswith('2001.') + assert doc["References"][0].startswith("..") + assert doc["References"][-1].endswith("2001.") def test_examples(doc): - assert doc['Examples'][0].startswith('>>>') - assert doc['Examples'][-1].endswith('True]') + assert doc["Examples"][0].startswith(">>>") + assert doc["Examples"][-1].endswith("True]") def test_index(doc): - assert doc['index']['default'] == 'random' - assert len(doc['index']) == 2 - assert len(doc['index']['refguide']) == 2 + assert doc["index"]["default"] == "random" + assert len(doc["index"]) == 2 + assert len(doc["index"]["refguide"]) == 2 def _strip_blank_lines(s): "Remove leading, trailing and multiple blank lines" - s = re.sub(r'^\s*\n', '', s) - s = re.sub(r'\n\s*$', '', s) - s = re.sub(r'\n\s*\n', r'\n\n', s) + s = re.sub(r"^\s*\n", "", s) + s = re.sub(r"\n\s*$", "", s) + s = re.sub(r"\n\s*\n", r"\n\n", s) return s def line_by_line_compare(a, b, n_lines=None): a = textwrap.dedent(a) b = textwrap.dedent(b) - a = [l.rstrip() for l in _strip_blank_lines(a).split('\n')][:n_lines] - b = [l.rstrip() for l in _strip_blank_lines(b).split('\n')][:n_lines] + a = [l.rstrip() for l in _strip_blank_lines(a).split("\n")][:n_lines] + b = [l.rstrip() for l in _strip_blank_lines(b).split("\n")][:n_lines] assert len(a) == len(b) for ii, (aa, bb) in enumerate(zip(a, b)): assert aa == bb @@ -383,8 +384,9 @@ def test_str(doc): # doc_txt has the order of Notes and See Also sections flipped. # This should be handled automatically, and so, one thing this test does # is to make sure that See Also precedes Notes in the output. - line_by_line_compare(str(doc), -"""numpy.multivariate_normal(mean, cov, shape=None, spam=None) + line_by_line_compare( + str(doc), + """numpy.multivariate_normal(mean, cov, shape=None, spam=None) Draw values from a multivariate normal distribution with specified mean and covariance. @@ -494,12 +496,14 @@ standard deviation: [True, True] .. index:: random - :refguide: random;distributions, random;gauss""") + :refguide: random;distributions, random;gauss""", + ) def test_yield_str(): - line_by_line_compare(str(doc_yields), -"""Test generator + line_by_line_compare( + str(doc_yields), + """Test generator Yields ------ @@ -509,12 +513,14 @@ b : int The number of bananas. int The number of unknowns. -""") +""", + ) def test_receives_str(): - line_by_line_compare(str(doc_sent), -"""Test generator + line_by_line_compare( + str(doc_sent), + """Test generator Yields ------ @@ -527,29 +533,44 @@ b : int The number of bananas. c : int The number of oranges. -""") +""", + ) def test_no_index_in_str(): - assert "index" not in str(NumpyDocString("""Test idx + assert "index" not in str( + NumpyDocString( + """Test idx - """)) + """ + ) + ) - assert "index" in str(NumpyDocString("""Test idx + assert "index" in str( + NumpyDocString( + """Test idx .. index :: random - """)) + """ + ) + ) - assert "index" in str(NumpyDocString("""Test idx + assert "index" in str( + NumpyDocString( + """Test idx .. index :: foo - """)) + """ + ) + ) + def test_sphinx_str(): sphinx_doc = SphinxDocString(doc_txt) - line_by_line_compare(str(sphinx_doc), -""" + line_by_line_compare( + str(sphinx_doc), + """ .. index:: random single: random;distributions, random;gauss @@ -668,13 +689,15 @@ standard deviation: >>> print(list((x[0, 0, :] - mean) < 0.6)) [True, True] -""") +""", + ) def test_sphinx_yields_str(): sphinx_doc = SphinxDocString(doc_yields_txt) - line_by_line_compare(str(sphinx_doc), -"""Test generator + line_by_line_compare( + str(sphinx_doc), + """Test generator :Yields: @@ -686,10 +709,12 @@ def test_sphinx_yields_str(): int The number of unknowns. -""") +""", + ) -doc2 = NumpyDocString(""" +doc2 = NumpyDocString( + """ Returns array of indices of the maximum values of along the given axis. Parameters @@ -698,39 +723,43 @@ doc2 = NumpyDocString(""" Array to look in. axis : {None, integer} If None, the index is into the flattened array, otherwise along - the specified axis""") + the specified axis""" +) def test_parameters_without_extended_description(): - assert len(doc2['Parameters']) == 2 + assert len(doc2["Parameters"]) == 2 -doc3 = NumpyDocString(""" +doc3 = NumpyDocString( + """ my_signature(*params, **kwds) Return this and that. - """) + """ +) def test_escape_stars(): - signature = str(doc3).split('\n')[0] - assert signature == r'my_signature(\*params, \*\*kwds)' + signature = str(doc3).split("\n")[0] + assert signature == r"my_signature(\*params, \*\*kwds)" def my_func(a, b, **kwargs): pass fdoc = FunctionDoc(func=my_func) - assert fdoc['Signature'] == '' + assert fdoc["Signature"] == "" doc4 = NumpyDocString( """a.conj() - Return an array with all complex-valued elements conjugated.""") + Return an array with all complex-valued elements conjugated.""" +) def test_empty_extended_summary(): - assert doc4['Extended Summary'] == [] + assert doc4["Extended Summary"] == [] doc5 = NumpyDocString( @@ -746,34 +775,37 @@ doc5 = NumpyDocString( ----- SomeWarning If needed - """) + """ +) def test_raises(): - assert len(doc5['Raises']) == 1 - param = doc5['Raises'][0] - assert param.name == '' - assert param.type == 'LinAlgException' - assert param.desc == ['If array is singular.'] + assert len(doc5["Raises"]) == 1 + param = doc5["Raises"][0] + assert param.name == "" + assert param.type == "LinAlgException" + assert param.desc == ["If array is singular."] def test_warns(): - assert len(doc5['Warns']) == 1 - param = doc5['Warns'][0] - assert param.name == '' - assert param.type == 'SomeWarning' - assert param.desc == ['If needed'] + assert len(doc5["Warns"]) == 1 + param = doc5["Warns"][0] + assert param.name == "" + assert param.type == "SomeWarning" + assert param.desc == ["If needed"] + # see numpydoc/numpydoc #281 # we want to correctly parse "See Also" both in docstrings both like -#"""foo +# """foo # and -#""" -#foo -@pytest.mark.parametrize('prefix', ['', '\n ']) +# """ +# foo +@pytest.mark.parametrize("prefix", ["", "\n "]) def test_see_also(prefix): doc6 = NumpyDocString( - prefix + """z(x,theta) + prefix + + """z(x,theta) See Also -------- @@ -789,51 +821,65 @@ def test_see_also(prefix): :obj:`~baz.obj_r` :class:`class_j`: fubar foobar - """) + """ + ) - assert len(doc6['See Also']) == 10 - for funcs, desc in doc6['See Also']: + assert len(doc6["See Also"]) == 10 + for funcs, desc in doc6["See Also"]: for func, role in funcs: - if func in ('func_a', 'func_b', 'func_c', 'func_f', - 'func_g', 'func_h', 'func_j', 'func_k', 'baz.obj_q', - 'func_f1', 'func_g1', 'func_h1', 'func_j1', - '~baz.obj_r'): + if func in ( + "func_a", + "func_b", + "func_c", + "func_f", + "func_g", + "func_h", + "func_j", + "func_k", + "baz.obj_q", + "func_f1", + "func_g1", + "func_h1", + "func_j1", + "~baz.obj_r", + ): assert not desc, str([func, desc]) - elif func in ('func_f2', 'func_g2', 'func_h2', 'func_j2'): + elif func in ("func_f2", "func_g2", "func_h2", "func_j2"): assert desc, str([func, desc]) else: assert desc, str([func, desc]) - if func == 'func_h': - assert role == 'meth' - elif func == 'baz.obj_q' or func == '~baz.obj_r': - assert role == 'obj' - elif func == 'class_j': - assert role == 'class' - elif func in ['func_h1', 'func_h2']: - assert role == 'meth' + if func == "func_h": + assert role == "meth" + elif func == "baz.obj_q" or func == "~baz.obj_r": + assert role == "obj" + elif func == "class_j": + assert role == "class" + elif func in ["func_h1", "func_h2"]: + assert role == "meth" else: assert role is None, str([func, role]) - if func == 'func_d': - assert desc == ['some equivalent func'] - elif func == 'foo.func_e': - assert desc == ['some other func over', 'multiple lines'] - elif func == 'class_j': - assert desc == ['fubar', 'foobar'] - elif func in ['func_f2', 'func_g2', 'func_h2', 'func_j2']: - assert desc == ['description of multiple'], str([desc, ['description of multiple']]) + if func == "func_d": + assert desc == ["some equivalent func"] + elif func == "foo.func_e": + assert desc == ["some other func over", "multiple lines"] + elif func == "class_j": + assert desc == ["fubar", "foobar"] + elif func in ["func_f2", "func_g2", "func_h2", "func_j2"]: + assert desc == ["description of multiple"], str( + [desc, ["description of multiple"]] + ) def test_see_also_parse_error(): - text = ( - """ + text = """ z(x,theta) See Also -------- :func:`~foo` - """) + """ with pytest.raises(ValueError, match="See Also entry ':func:`~foo`'"): NumpyDocString(text) @@ -848,17 +894,21 @@ def test_see_also_print(): goes here func_d """ + pass - s = str(FunctionDoc(Dummy, role='func')) - assert(':func:`func_a`, :func:`func_b`' in s) - assert(' some relationship' in s) - assert(':func:`func_d`' in s) + s = str(FunctionDoc(Dummy, role="func")) + assert ":func:`func_a`, :func:`func_b`" in s + assert " some relationship" in s + assert ":func:`func_d`" in s def test_see_also_trailing_comma_warning(): - warnings.filterwarnings('error') - with assert_warns(Warning, match='Unexpected comma or period after function list at index 43 of line .*'): + warnings.filterwarnings("error") + with assert_warns( + Warning, + match="Unexpected comma or period after function list at index 43 of line .*", + ): NumpyDocString( """ z(x,theta) @@ -868,7 +918,8 @@ def test_see_also_trailing_comma_warning(): func_f2, func_g2, :meth:`func_h2`, func_j2, : description of multiple :class:`class_j`: fubar foobar - """) + """ + ) def test_unknown_section(): @@ -887,6 +938,7 @@ This should be ignored and warned about ---- This class has a nope section. """ + pass with pytest.warns(UserWarning, match="Unknown section Mope") as record: @@ -901,17 +953,21 @@ This should be ignored and warned about assert len(record) == 1 -doc7 = NumpyDocString(""" +doc7 = NumpyDocString( + """ Doc starts on second line. - """) + """ +) def test_empty_first_line(): - assert doc7['Summary'][0].startswith('Doc starts') + assert doc7["Summary"][0].startswith("Doc starts") -doc8 = NumpyDocString(""" + +doc8 = NumpyDocString( + """ Parameters with colon and no types: @@ -920,21 +976,27 @@ doc8 = NumpyDocString(""" data : some stuff, technically invalid - """) + """ +) def test_trailing_colon(): - assert doc8['Parameters'][0].name == 'data' + assert doc8["Parameters"][0].name == "data" def test_no_summary(): - str(SphinxDocString(""" + str( + SphinxDocString( + """ Parameters - ----------""")) + ----------""" + ) + ) def test_unicode(): - doc = SphinxDocString(""" + doc = SphinxDocString( + """ öäöäöäöäöåååå öäöäöäööäååå @@ -949,33 +1011,41 @@ def test_unicode(): ååå : ööö äää - """) - assert isinstance(doc['Summary'][0], str) - assert doc['Summary'][0] == 'öäöäöäöäöåååå' + """ + ) + assert isinstance(doc["Summary"][0], str) + assert doc["Summary"][0] == "öäöäöäöäöåååå" def test_plot_examples(): cfg = dict(use_plots=True) - doc = SphinxDocString(""" + doc = SphinxDocString( + """ Examples -------- >>> import matplotlib.pyplot as plt >>> plt.plot([1,2,3],[4,5,6]) >>> plt.show() - """, config=cfg) - assert 'plot::' in str(doc), str(doc) + """, + config=cfg, + ) + assert "plot::" in str(doc), str(doc) - doc = SphinxDocString(""" + doc = SphinxDocString( + """ Examples -------- >>> from matplotlib import pyplot as plt >>> plt.plot([1,2,3],[4,5,6]) >>> plt.show() - """, config=cfg) - assert 'plot::' in str(doc), str(doc) + """, + config=cfg, + ) + assert "plot::" in str(doc), str(doc) - doc = SphinxDocString(""" + doc = SphinxDocString( + """ Examples -------- .. plot:: @@ -983,13 +1053,16 @@ def test_plot_examples(): import matplotlib.pyplot as plt plt.plot([1,2,3],[4,5,6]) plt.show() - """, config=cfg) - assert str(doc).count('plot::') == 1, str(doc) + """, + config=cfg, + ) + assert str(doc).count("plot::") == 1, str(doc) def test_use_blockquotes(): cfg = dict(use_blockquotes=True) - doc = SphinxDocString(""" + doc = SphinxDocString( + """ Parameters ---------- abc : def @@ -1003,8 +1076,12 @@ def test_use_blockquotes(): GHI JKL MNO - """, config=cfg) - line_by_line_compare(str(doc), ''' + """, + config=cfg, + ) + line_by_line_compare( + str(doc), + """ :Parameters: **abc** : def @@ -1024,22 +1101,25 @@ def test_use_blockquotes(): JKL MNO - ''') + """, + ) def test_class_members(): - class Dummy: """ Dummy class. """ + def spam(self, a, b): """Spam\n\nSpam spam.""" pass + def ham(self, c, d): """Cheese\n\nNo cheese.""" pass + @property def spammity(self): """Spammity index""" @@ -1047,32 +1127,34 @@ def test_class_members(): class Ignorable: """local class, to be ignored""" + pass for cls in (ClassDoc, SphinxClassDoc): doc = cls(Dummy, config=dict(show_class_members=False)) - assert 'Methods' not in str(doc), (cls, str(doc)) - assert 'spam' not in str(doc), (cls, str(doc)) - assert 'ham' not in str(doc), (cls, str(doc)) - assert 'spammity' not in str(doc), (cls, str(doc)) - assert 'Spammity index' not in str(doc), (cls, str(doc)) + assert "Methods" not in str(doc), (cls, str(doc)) + assert "spam" not in str(doc), (cls, str(doc)) + assert "ham" not in str(doc), (cls, str(doc)) + assert "spammity" not in str(doc), (cls, str(doc)) + assert "Spammity index" not in str(doc), (cls, str(doc)) doc = cls(Dummy, config=dict(show_class_members=True)) - assert 'Methods' in str(doc), (cls, str(doc)) - assert 'spam' in str(doc), (cls, str(doc)) - assert 'ham' in str(doc), (cls, str(doc)) - assert 'spammity' in str(doc), (cls, str(doc)) + assert "Methods" in str(doc), (cls, str(doc)) + assert "spam" in str(doc), (cls, str(doc)) + assert "ham" in str(doc), (cls, str(doc)) + assert "spammity" in str(doc), (cls, str(doc)) if cls is SphinxClassDoc: - assert '.. autosummary::' in str(doc), str(doc) + assert ".. autosummary::" in str(doc), str(doc) else: - assert 'Spammity index' in str(doc), str(doc) + assert "Spammity index" in str(doc), str(doc) class SubDummy(Dummy): """ Subclass of Dummy class. """ + def ham(self, c, d): """Cheese\n\nNo cheese.\nOverloaded Dummy.ham""" pass @@ -1082,31 +1164,35 @@ def test_class_members(): pass for cls in (ClassDoc, SphinxClassDoc): - doc = cls(SubDummy, config=dict(show_class_members=True, - show_inherited_class_members=False)) - assert 'Methods' in str(doc), (cls, str(doc)) - assert 'spam' not in str(doc), (cls, str(doc)) - assert 'ham' in str(doc), (cls, str(doc)) - assert 'bar' in str(doc), (cls, str(doc)) - assert 'spammity' not in str(doc), (cls, str(doc)) + doc = cls( + SubDummy, + config=dict(show_class_members=True, show_inherited_class_members=False), + ) + assert "Methods" in str(doc), (cls, str(doc)) + assert "spam" not in str(doc), (cls, str(doc)) + assert "ham" in str(doc), (cls, str(doc)) + assert "bar" in str(doc), (cls, str(doc)) + assert "spammity" not in str(doc), (cls, str(doc)) if cls is SphinxClassDoc: - assert '.. autosummary::' in str(doc), str(doc) + assert ".. autosummary::" in str(doc), str(doc) else: - assert 'Spammity index' not in str(doc), str(doc) + assert "Spammity index" not in str(doc), str(doc) - doc = cls(SubDummy, config=dict(show_class_members=True, - show_inherited_class_members=True)) - assert 'Methods' in str(doc), (cls, str(doc)) - assert 'spam' in str(doc), (cls, str(doc)) - assert 'ham' in str(doc), (cls, str(doc)) - assert 'bar' in str(doc), (cls, str(doc)) - assert 'spammity' in str(doc), (cls, str(doc)) + doc = cls( + SubDummy, + config=dict(show_class_members=True, show_inherited_class_members=True), + ) + assert "Methods" in str(doc), (cls, str(doc)) + assert "spam" in str(doc), (cls, str(doc)) + assert "ham" in str(doc), (cls, str(doc)) + assert "bar" in str(doc), (cls, str(doc)) + assert "spammity" in str(doc), (cls, str(doc)) if cls is SphinxClassDoc: - assert '.. autosummary::' in str(doc), str(doc) + assert ".. autosummary::" in str(doc), str(doc) else: - assert 'Spammity index' in str(doc), str(doc) + assert "Spammity index" in str(doc), str(doc) def test_duplicate_signature(): @@ -1115,13 +1201,14 @@ def test_duplicate_signature(): # docstring itself. doc = NumpyDocString( - """ + """ z(x1, x2) z(a, theta) - """) + """ + ) - assert doc['Signature'].strip() == 'z(a, theta)' + assert doc["Signature"].strip() == "z(a, theta)" class_doc_txt = """ @@ -1167,8 +1254,9 @@ class_doc_txt = """ def test_class_members_doc(): doc = ClassDoc(None, class_doc_txt) - line_by_line_compare(str(doc), - """ + line_by_line_compare( + str(doc), + """ Foo Parameters @@ -1206,7 +1294,8 @@ def test_class_members_doc(): b c - """) + """, + ) def test_class_members_doc_sphinx(): @@ -1245,8 +1334,9 @@ def test_class_members_doc_sphinx(): return None doc = SphinxClassDoc(Foo, class_doc_txt) - line_by_line_compare(str(doc), - """ + line_by_line_compare( + str(doc), + """ Foo :Parameters: @@ -1298,11 +1388,11 @@ def test_class_members_doc_sphinx(): **c** ===== ========== - """) + """, + ) def test_class_attributes_as_member_list(): - class Foo: """ Class docstring. @@ -1313,6 +1403,7 @@ def test_class_attributes_as_member_list(): Another description that is not used. """ + @property def an_attribute(self): """Test attribute""" @@ -1339,10 +1430,14 @@ def test_class_attributes_as_member_list(): def test_templated_sections(): - doc = SphinxClassDoc(None, class_doc_txt, - config={'template': jinja2.Template('{{examples}}\n{{parameters}}')}) - line_by_line_compare(str(doc), - """ + doc = SphinxClassDoc( + None, + class_doc_txt, + config={"template": jinja2.Template("{{examples}}\n{{parameters}}")}, + ) + line_by_line_compare( + str(doc), + """ .. rubric:: Examples For usage examples, see `ode`. @@ -1355,14 +1450,14 @@ def test_templated_sections(): **jac** : callable ``jac(t, y, *jac_args)`` Bbb. - """) + """, + ) def test_nonstandard_property(): # test discovery of a property that does not satisfy isinstace(.., property) class SpecialProperty: - def __init__(self, axis=0, doc=""): self.axis = axis self.__doc__ = doc @@ -1387,7 +1482,8 @@ def test_nonstandard_property(): def test_args_and_kwargs(): cfg = dict() - doc = SphinxDocString(""" + doc = SphinxDocString( + """ Parameters ---------- param1 : int @@ -1396,8 +1492,12 @@ def test_args_and_kwargs(): Arguments **kwargs : dict Keyword arguments - """, config=cfg) - line_by_line_compare(str(doc), r""" + """, + config=cfg, + ) + line_by_line_compare( + str(doc), + r""" :Parameters: **param1** : int @@ -1408,17 +1508,24 @@ def test_args_and_kwargs(): **\*\*kwargs** : dict Keyword arguments - """) + """, + ) + def test_autoclass(): - cfg=dict(show_class_members=True, - show_inherited_class_members=True) - doc = SphinxClassDoc(str, ''' + cfg = dict(show_class_members=True, show_inherited_class_members=True) + doc = SphinxClassDoc( + str, + """ A top section before .. autoclass:: str - ''', config=cfg) - line_by_line_compare(str(doc), r''' + """, + config=cfg, + ) + line_by_line_compare( + str(doc), + r""" A top section before .. autoclass:: str @@ -1426,7 +1533,9 @@ A top section before .. rubric:: Methods - ''', 5) + """, + 5, + ) xref_doc_txt = """ @@ -1489,10 +1598,10 @@ Test xref in Parameters, Other Parameters and Returns def test_xref(): xref_aliases = { - 'sequence': ':obj:`python:sequence`', + "sequence": ":obj:`python:sequence`", } - class Config(): + class Config: def __init__(self, a, b): self.numpydoc_xref_aliases = a self.numpydoc_xref_aliases_complete = b @@ -1504,18 +1613,18 @@ def test_xref(): for key in xref_aliases: xref_aliases_complete[key] = xref_aliases[key] config = Config(xref_aliases, xref_aliases_complete) - app = namedtuple('config', 'config')(config) + app = namedtuple("config", "config")(config) update_config(app) - xref_ignore = {'of', 'default', 'optional'} + xref_ignore = {"of", "default", "optional"} doc = SphinxDocString( xref_doc_txt, config=dict( xref_param_type=True, xref_aliases=xref_aliases_complete, - xref_ignore=xref_ignore - ) + xref_ignore=xref_ignore, + ), ) line_by_line_compare(str(doc), xref_doc_txt_expected) @@ -1531,11 +1640,10 @@ def test__error_location_no_name_attr(): from collections.abc import Callable # Create a Callable that doesn't have a __name__ attribute - class Foo(): + class Foo: def __call__(self): pass - foo = Foo() # foo is a Callable, but no a function instance assert isinstance(foo, Callable) @@ -1549,4 +1657,5 @@ def test__error_location_no_name_attr(): if __name__ == "__main__": import pytest + pytest.main() |