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

doc/format.rst

@@ -250,13 +250,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. **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
     <http://docs.python.org/library/doctest.html>`_ format.

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')

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'),

numpydoc/templates/numpydoc_docstring.rst

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

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),