From 0fd4eecc25d1bc471876d3f9d24a8388f2d22e96 Mon Sep 17 00:00:00 2001 From: Joel Nothman Date: Tue, 14 Nov 2017 18:48:05 +1100 Subject: [PATCH 1/4] Support Sent section fixes #47 TODO: tests --- doc/format.rst | 24 +++++++++++++++-------- numpydoc/docscrape.py | 10 +++++++--- numpydoc/docscrape_sphinx.py | 1 + numpydoc/templates/numpydoc_docstring.rst | 1 + 4 files changed, 25 insertions(+), 11 deletions(-) diff --git a/doc/format.rst b/doc/format.rst index 9b3b0ca5..9b9f5060 100644 --- a/doc/format.rst +++ b/doc/format.rst @@ -250,13 +250,21 @@ The sections of a function's docstring are: Support for the **Yields** section was added in `numpydoc `_ version 0.6. -7. **Other Parameters** +7. **Sent** + + Explanation of parameters passed to a generator's ``.send()`` method, + formatted as for Parameters, above. Since, like for Yields and Returns, a + single object is always passed to the method, this may describe either the + single parameter, or positional arguments passed as a tuple. If a docstring + includes Sent it must also include Yields. + +8. **Other Parameters** An optional section used to describe infrequently used parameters. It should only be used if a function has a large number of keyword parameters, to prevent cluttering the **Parameters** section. -8. **Raises** +9. **Raises** An optional section detailing which errors get raised and under what conditions:: @@ -269,16 +277,16 @@ The sections of a function's docstring are: This section should be used judiciously, i.e., only for errors that are non-obvious or have a large chance of getting raised. -9. **Warns** +10. **Warns** An optional section detailing which warnings get raised and under what conditions, formatted similarly to Raises. -10. **Warnings** +11. **Warnings** An optional section with cautions to the user in free text/reST. -11. **See Also** +12. **See Also** An optional section used to refer to related code. This section can be very useful, but should be used judiciously. The goal is to @@ -317,7 +325,7 @@ The sections of a function's docstring are: func_b, func_c_, func_d func_e -12. **Notes** +13. **Notes** An optional section that provides additional information about the code, possibly including a discussion of the algorithm. This @@ -362,7 +370,7 @@ The sections of a function's docstring are: where filename is a path relative to the reference guide source directory. -13. **References** +14. **References** References cited in the **notes** section may be listed here, e.g. if you cited the article below using the text ``[1]_``, @@ -387,7 +395,7 @@ The sections of a function's docstring are: should not be required to understand it. References are numbered, starting from one, in the order in which they are cited. -14. **Examples** +15. **Examples** An optional section for examples, using the `doctest `_ format. diff --git a/numpydoc/docscrape.py b/numpydoc/docscrape.py index 6ca62922..11f483e3 100644 --- a/numpydoc/docscrape.py +++ b/numpydoc/docscrape.py @@ -120,6 +120,7 @@ class NumpyDocString(collections.Mapping): 'Parameters': [], 'Returns': [], 'Yields': [], + 'Sent': [], 'Raises': [], 'Warns': [], 'Other Parameters': [], @@ -342,6 +343,9 @@ def _parse(self): if has_returns and has_yields: msg = 'Docstring contains both a Returns and Yields section.' raise ValueError(msg) + if not has_yields and 'Sent' in section_names: + msg = 'Docstring contains a Sent section but not Yields.' + raise ValueError(msg) for (section, content) in sections: if not section.startswith('..'): @@ -351,8 +355,8 @@ def _parse(self): self._error_location("The section %s appears twice" % section) - if section in ('Parameters', 'Returns', 'Yields', 'Raises', - 'Warns', 'Other Parameters', 'Attributes', + if section in ('Parameters', 'Returns', 'Yields', 'Sent', + 'Raises', 'Warns', 'Other Parameters', 'Attributes', 'Methods'): self[section] = self._parse_param_list(content) elif section.startswith('.. index::'): @@ -468,7 +472,7 @@ def __str__(self, func_role=''): out += self._str_signature() out += self._str_summary() out += self._str_extended_summary() - for param_list in ('Parameters', 'Returns', 'Yields', + for param_list in ('Parameters', 'Returns', 'Yields', 'Sent', 'Other Parameters', 'Raises', 'Warns'): out += self._str_param_list(param_list) out += self._str_section('Warnings') diff --git a/numpydoc/docscrape_sphinx.py b/numpydoc/docscrape_sphinx.py index ff5be26c..a2063cab 100644 --- a/numpydoc/docscrape_sphinx.py +++ b/numpydoc/docscrape_sphinx.py @@ -355,6 +355,7 @@ def __str__(self, indent=0, func_role="obj"): 'parameters': self._str_param_list('Parameters'), 'returns': self._str_returns('Returns'), 'yields': self._str_returns('Yields'), + 'sent': self._str_returns('Sent'), 'other_parameters': self._str_param_list('Other Parameters'), 'raises': self._str_param_list('Raises'), 'warns': self._str_param_list('Warns'), diff --git a/numpydoc/templates/numpydoc_docstring.rst b/numpydoc/templates/numpydoc_docstring.rst index 1900db53..08b7ca86 100644 --- a/numpydoc/templates/numpydoc_docstring.rst +++ b/numpydoc/templates/numpydoc_docstring.rst @@ -4,6 +4,7 @@ {{parameters}} {{returns}} {{yields}} +{{sent}} {{other_parameters}} {{raises}} {{warns}} From 34e9323942b11a8cf290fb097f2a00d4bb59c04f Mon Sep 17 00:00:00 2001 From: Joel Nothman Date: Tue, 14 Nov 2017 20:09:29 +1100 Subject: [PATCH 2/4] Add tests for Sent --- numpydoc/tests/test_docscrape.py | 70 ++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/numpydoc/tests/test_docscrape.py b/numpydoc/tests/test_docscrape.py index 8fa3d23f..a302e902 100644 --- a/numpydoc/tests/test_docscrape.py +++ b/numpydoc/tests/test_docscrape.py @@ -151,6 +151,25 @@ doc_yields = NumpyDocString(doc_yields_txt) +doc_sent_txt = """ +Test generator + +Yields +------ +a : int + The number of apples. + +Sent +---- +b : int + The number of bananas. +c : int + The number of oranges. + +""" +doc_sent = NumpyDocString(doc_sent_txt) + + def test_signature(): assert doc['Signature'].startswith('numpy.multivariate_normal(') assert doc['Signature'].endswith('spam=None)') @@ -211,6 +230,38 @@ def test_yields(): assert desc[0].endswith(end) +def test_sent(): + section = doc_sent['Sent'] + assert_equal(len(section), 2) + truth = [('b', 'int', 'bananas.'), + ('c', 'int', 'oranges.')] + for (arg, arg_type, desc), (arg_, arg_type_, end) in zip(section, truth): + assert_equal(arg, arg_) + assert_equal(arg_type, arg_type_) + assert desc[0].startswith('The number of') + assert desc[0].endswith(end) + + +def test_returnyield(): + doc_text = """ +Test having returns and yields. + +Returns +------- +int + The number of apples. + +Yields +------ +a : int + The number of apples. +b : int + The number of bananas. + +""" + assert_raises(ValueError, NumpyDocString, doc_text) + + def test_returnyield(): doc_text = """ Test having returns and yields. @@ -462,6 +513,25 @@ def test_yield_str(): .. index:: """) +def test_sent_str(): + line_by_line_compare(str(doc_sent), +"""Test generator + +Yields +------ +a : int + The number of apples. + +Sent +---- +b : int + The number of bananas. +c : int + The number of oranges. + +.. index:: """) + + def test_sphinx_str(): sphinx_doc = SphinxDocString(doc_txt) line_by_line_compare(str(sphinx_doc), From ac8254e526c65ae578c9c295a6865458526e869f Mon Sep 17 00:00:00 2001 From: Joel Nothman Date: Mon, 4 Dec 2017 10:12:55 +1100 Subject: [PATCH 3/4] Rename Sent to Receives --- doc/format.rst | 4 ++-- numpydoc/docscrape.py | 10 +++++----- numpydoc/docscrape_sphinx.py | 2 +- numpydoc/templates/numpydoc_docstring.rst | 2 +- numpydoc/tests/test_docscrape.py | 10 +++++----- 5 files changed, 14 insertions(+), 14 deletions(-) diff --git a/doc/format.rst b/doc/format.rst index 9b9f5060..9f81fea0 100644 --- a/doc/format.rst +++ b/doc/format.rst @@ -250,13 +250,13 @@ The sections of a function's docstring are: Support for the **Yields** section was added in `numpydoc `_ version 0.6. -7. **Sent** +7. **Receives** Explanation of parameters passed to a generator's ``.send()`` method, formatted as for Parameters, above. Since, like for Yields and Returns, a single object is always passed to the method, this may describe either the single parameter, or positional arguments passed as a tuple. If a docstring - includes Sent it must also include Yields. + includes Receives it must also include Yields. 8. **Other Parameters** diff --git a/numpydoc/docscrape.py b/numpydoc/docscrape.py index 11f483e3..7ea62388 100644 --- a/numpydoc/docscrape.py +++ b/numpydoc/docscrape.py @@ -120,7 +120,7 @@ class NumpyDocString(collections.Mapping): 'Parameters': [], 'Returns': [], 'Yields': [], - 'Sent': [], + 'Receives': [], 'Raises': [], 'Warns': [], 'Other Parameters': [], @@ -343,8 +343,8 @@ def _parse(self): if has_returns and has_yields: msg = 'Docstring contains both a Returns and Yields section.' raise ValueError(msg) - if not has_yields and 'Sent' in section_names: - msg = 'Docstring contains a Sent section but not Yields.' + if not has_yields and 'Receives' in section_names: + msg = 'Docstring contains a Receives section but not Yields.' raise ValueError(msg) for (section, content) in sections: @@ -355,7 +355,7 @@ def _parse(self): self._error_location("The section %s appears twice" % section) - if section in ('Parameters', 'Returns', 'Yields', 'Sent', + if section in ('Parameters', 'Returns', 'Yields', 'Receives', 'Raises', 'Warns', 'Other Parameters', 'Attributes', 'Methods'): self[section] = self._parse_param_list(content) @@ -472,7 +472,7 @@ def __str__(self, func_role=''): out += self._str_signature() out += self._str_summary() out += self._str_extended_summary() - for param_list in ('Parameters', 'Returns', 'Yields', 'Sent', + for param_list in ('Parameters', 'Returns', 'Yields', 'Receives', 'Other Parameters', 'Raises', 'Warns'): out += self._str_param_list(param_list) out += self._str_section('Warnings') diff --git a/numpydoc/docscrape_sphinx.py b/numpydoc/docscrape_sphinx.py index a2063cab..cf6e2c78 100644 --- a/numpydoc/docscrape_sphinx.py +++ b/numpydoc/docscrape_sphinx.py @@ -355,7 +355,7 @@ def __str__(self, indent=0, func_role="obj"): 'parameters': self._str_param_list('Parameters'), 'returns': self._str_returns('Returns'), 'yields': self._str_returns('Yields'), - 'sent': self._str_returns('Sent'), + 'receives': self._str_returns('Receives'), 'other_parameters': self._str_param_list('Other Parameters'), 'raises': self._str_param_list('Raises'), 'warns': self._str_param_list('Warns'), diff --git a/numpydoc/templates/numpydoc_docstring.rst b/numpydoc/templates/numpydoc_docstring.rst index 08b7ca86..79ab1f8e 100644 --- a/numpydoc/templates/numpydoc_docstring.rst +++ b/numpydoc/templates/numpydoc_docstring.rst @@ -4,7 +4,7 @@ {{parameters}} {{returns}} {{yields}} -{{sent}} +{{receives}} {{other_parameters}} {{raises}} {{warns}} diff --git a/numpydoc/tests/test_docscrape.py b/numpydoc/tests/test_docscrape.py index a302e902..5e49bd1d 100644 --- a/numpydoc/tests/test_docscrape.py +++ b/numpydoc/tests/test_docscrape.py @@ -159,8 +159,8 @@ a : int The number of apples. -Sent ----- +Receives +-------- b : int The number of bananas. c : int @@ -231,7 +231,7 @@ def test_yields(): def test_sent(): - section = doc_sent['Sent'] + section = doc_sent['Receives'] assert_equal(len(section), 2) truth = [('b', 'int', 'bananas.'), ('c', 'int', 'oranges.')] @@ -522,8 +522,8 @@ def test_sent_str(): a : int The number of apples. -Sent ----- +Receives +-------- b : int The number of bananas. c : int From 0eab27b8d9c3cdb7c2df210ed4d526a2d749afcd Mon Sep 17 00:00:00 2001 From: Joel Nothman Date: Tue, 9 Apr 2019 18:25:15 +1000 Subject: [PATCH 4/4] Pytest-style assertions --- numpydoc/tests/test_docscrape.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/numpydoc/tests/test_docscrape.py b/numpydoc/tests/test_docscrape.py index 8d6af51f..a0fb19c1 100644 --- a/numpydoc/tests/test_docscrape.py +++ b/numpydoc/tests/test_docscrape.py @@ -237,12 +237,12 @@ def test_yields(): def test_sent(): section = doc_sent['Receives'] - assert_equal(len(section), 2) + assert len(section) == 2 truth = [('b', 'int', 'bananas.'), ('c', 'int', 'oranges.')] for (arg, arg_type, desc), (arg_, arg_type_, end) in zip(section, truth): - assert_equal(arg, arg_) - assert_equal(arg_type, arg_type_) + assert arg == arg_ + assert arg_type == arg_type_ assert desc[0].startswith('The number of') assert desc[0].endswith(end)