Support Receives section for generator.send(...) params (#145)

Author: jnothman

doc/format.rst

@@ -252,13 +252,21 @@ The sections of a function's docstring are:
    Support for the **Yields** section was added in `numpydoc
    <https://github.com/numpy/numpydoc>`_ version 0.6.
 
-7. **Other Parameters**
+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 Receives 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::
@@ -271,16 +279,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
@@ -319,7 +327,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
@@ -364,7 +372,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]_``,
@@ -397,7 +405,7 @@ The sections of a function's docstring are:
 
 .. highlight:: pycon
 
-14. **Examples**
+15. **Examples**
 
     An optional section for examples, using the `doctest
     <http://docs.python.org/library/doctest.html>`_ format.

numpydoc/docscrape.py

@@ -127,6 +127,7 @@ class NumpyDocString(Mapping):
         'Parameters': [],
         'Returns': [],
         'Yields': [],
+        'Receives': [],
         'Raises': [],
         'Warns': [],
         'Other Parameters': [],
@@ -350,6 +351,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 'Receives' in section_names:
+            msg = 'Docstring contains a Receives section but not Yields.'
+            raise ValueError(msg)
 
         for (section, content) in sections:
             if not section.startswith('..'):
@@ -359,8 +363,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', 'Receives',
+                           'Raises', 'Warns', 'Other Parameters', 'Attributes',
                            'Methods'):
                 self[section] = self._parse_param_list(content)
             elif section.startswith('.. index::'):
@@ -484,7 +488,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', 'Receives',
                            'Other Parameters', 'Raises', 'Warns'):
             out += self._str_param_list(param_list)
         out += self._str_section('Warnings')

numpydoc/docscrape_sphinx.py

@@ -374,6 +374,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'),
+            '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'),

numpydoc/templates/numpydoc_docstring.rst

@@ -4,6 +4,7 @@
 {{parameters}}
 {{returns}}
 {{yields}}
+{{receives}}
 {{other_parameters}}
 {{raises}}
 {{warns}}

numpydoc/tests/test_docscrape.py

@@ -150,6 +150,25 @@
 doc_yields = NumpyDocString(doc_yields_txt)
 
 
+doc_sent_txt = """
+Test generator
+
+Yields
+------
+a : int
+    The number of apples.
+
+Receives
+--------
+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)')
@@ -216,6 +235,38 @@ def test_yields():
         assert desc[0].endswith(end)
 
 
+def test_sent():
+    section = doc_sent['Receives']
+    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 arg == arg_
+        assert 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.
@@ -468,6 +519,25 @@ def test_yield_str():
 .. index:: """)
 
 
+def test_receives_str():
+    line_by_line_compare(str(doc_sent),
+"""Test generator
+
+Yields
+------
+a : int
+    The number of apples.
+
+Receives
+--------
+b : int
+    The number of bananas.
+c : int
+    The number of oranges.
+
+.. index:: """)
+
+
 def test_no_index_in_str():
     assert "index" not in str(NumpyDocString("""Test idx