ENH: Append docs in @unpack_labeled_data

jankatins · jankatins · commit 8dbb2cc4e7c0 · 2015-08-31T12:06:34.000+02:00
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -119,7 +119,7 @@
 import functools
 # cbook must import matplotlib only within function
 # definitions, so it is safe to import from it here.
-from matplotlib.cbook import is_string_like, mplDeprecation
+from matplotlib.cbook import is_string_like, mplDeprecation, dedent
 from matplotlib.compat import subprocess
 from matplotlib.rcsetup import (defaultParams,
                                 validate_backend,
@@ -1534,6 +1534,19 @@ def _replacer(data, key):
         return key
 
 
+_DATA_DOC_APPENDIX = """
+
+Notes
+-----
+
+In addition to the above described arguments, this function can take a
+**data** keyword argument. If such a **data** argument is given, the
+following arguments are replaced by **data[<arg>]**:
+
+{replaced}
+"""
+
+
 def unpack_labeled_data(replace_names=None, replace_all_args=False,
                         label_namer=None, positional_parameter_names=None):
     """
@@ -1708,10 +1721,25 @@ def inner(ax, *args, **kwargs):
                                   RuntimeWarning, stacklevel=2)
                     # raise Exception()
             return func(ax, *args, **kwargs)
+        pre_doc = inner.__doc__
+        if pre_doc is None:
+            pre_doc = ''
+        else:
+            pre_doc = dedent(pre_doc)
+        _repl = ""
+        if replace_names is None:
+            _repl = "* All positional and all keyword arguments."
+        else:
+            if len(replace_names) != 0:
+                _repl = "* All arguments with the following names: '{names}'."
+            if replace_all_args:
+                _repl += "\n* All positional arguments."
+            _repl = _repl.format(names="', '".join(replace_names))
+        inner.__doc__ = (pre_doc +
+                         _DATA_DOC_APPENDIX.format(replaced=_repl))
         return inner
     return param
 
-
 verbose.report('matplotlib version %s' % __version__)
 verbose.report('verbose.level %s' % verbose.level)
 verbose.report('interactive is %s' % is_interactive())
diff --git a/lib/matplotlib/tests/test_labled_data_unpacking.py b/lib/matplotlib/tests/test_labled_data_unpacking.py
@@ -1,7 +1,8 @@
 from __future__ import (absolute_import, division, print_function,
                         unicode_literals)
 
-from nose.tools import assert_raises, assert_equal
+from nose.tools import (assert_raises, assert_equal, assert_regexp_matches,
+                        assert_not_regexp_matches)
 from nose.plugins.skip import SkipTest
 
 from .. import unpack_labeled_data
@@ -327,3 +328,49 @@ def funcy(ax, *args, **kwargs):
                  "x: [1, 2], y: [8, 9], ls: x, w: xyz, label: ")
     assert_equal(func2(None, "a", "b", w="x", label="text", data=data),
                  "x: [1, 2], y: [8, 9], ls: x, w: xyz, label: text")
+
+
+def test_docstring_addition():
+    @unpack_labeled_data()
+    def funcy(ax, *args, **kwargs):
+        """Funcy does nothing"""
+        pass
+
+    assert_regexp_matches(funcy.__doc__,
+                          r".*All positional and all keyword arguments\.")
+    assert_not_regexp_matches(funcy.__doc__, r".*All positional arguments\.")
+    assert_not_regexp_matches(funcy.__doc__,
+                              r".*All arguments with the following names: .*")
+
+    @unpack_labeled_data(replace_all_args=True, replace_names=[])
+    def funcy(ax, x, y, z, bar=None):
+        """Funcy does nothing"""
+        pass
+
+    assert_regexp_matches(funcy.__doc__, r".*All positional arguments\.")
+    assert_not_regexp_matches(funcy.__doc__,
+                              r".*All positional and all keyword arguments\.")
+    assert_not_regexp_matches(funcy.__doc__,
+                              r".*All arguments with the following names: .*")
+
+    @unpack_labeled_data(replace_all_args=True, replace_names=["bar"])
+    def funcy(ax, x, y, z, bar=None):
+        """Funcy does nothing"""
+        pass
+
+    assert_regexp_matches(funcy.__doc__, r".*All positional arguments\.")
+    assert_regexp_matches(funcy.__doc__,
+                          r".*All arguments with the following names: 'bar'\.")
+    assert_not_regexp_matches(funcy.__doc__,
+                              r".*All positional and all keyword arguments\.")
+
+    @unpack_labeled_data(replace_names=["x", "bar"])
+    def funcy(ax, x, y, z, bar=None):
+        """Funcy does nothing"""
+        pass
+
+    assert_regexp_matches(funcy.__doc__,
+                 r".*All arguments with the following names: 'x', 'bar'\.")
+    assert_not_regexp_matches(funcy.__doc__,
+                              r".*All positional and all keyword arguments\.")
+    assert_not_regexp_matches(funcy.__doc__, r".*All positional arguments\.")
