From 67ef9117fe0ca47c3f9abe039c9dd4dfee489d11 Mon Sep 17 00:00:00 2001 From: Antony Lee Date: Mon, 7 Jan 2019 02:59:37 +0100 Subject: [PATCH] Improve doc for data kwarg. --- lib/matplotlib/__init__.py | 30 +++++++------- lib/matplotlib/tests/test_preprocess_data.py | 41 +++++--------------- 2 files changed, 26 insertions(+), 45 deletions(-) diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py index 27ce53b8e18e..11968a34b509 100644 --- a/lib/matplotlib/__init__.py +++ b/lib/matplotlib/__init__.py @@ -1402,14 +1402,12 @@ def _label_from_arg(y, default_name): _DATA_DOC_APPENDIX = """ .. note:: - 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[]**: + In addition to the above described arguments, this function can take + a *data* keyword argument. If such a *data* argument is given, +{replaced} - {replaced} - - Objects passed as **data** must support item access (``data[]``) and - membership test (`` in data``). + Objects passed as **data** must support item access (``data[s]``) and + membership test (``s in data``). """ @@ -1429,13 +1427,17 @@ def _add_data_doc(docstring, replace_names): ------- The augmented docstring. """ - docstring = inspect.cleandoc(docstring) if docstring is not None else "" - repl = ("* All positional and all keyword arguments." - if replace_names is None else - "" - if len(replace_names) == 0 else - "* All arguments with the following names: {}.".format( - ", ".join(map(repr, sorted(replace_names))))) + if (docstring is None + or replace_names is not None and len(replace_names) == 0): + return docstring + docstring = inspect.cleandoc(docstring) + repl = ( + (" every other argument can also be string ``s``, which is\n" + " interpreted as ``data[s]`` (unless this raises an exception).") + if replace_names is None else + (" the following arguments can also be string ``s``, which is\n" + " interpreted as ``data[s]`` (unless this raises an exception):\n" + " " + ", ".join(map("*{}*".format, replace_names))) + ".") addendum = _DATA_DOC_APPENDIX.format(replaced=repl) if _DATA_DOC_TITLE not in docstring: addendum = _DATA_DOC_TITLE + addendum diff --git a/lib/matplotlib/tests/test_preprocess_data.py b/lib/matplotlib/tests/test_preprocess_data.py index 28f6cc416cac..e1ac9d891b7e 100644 --- a/lib/matplotlib/tests/test_preprocess_data.py +++ b/lib/matplotlib/tests/test_preprocess_data.py @@ -189,50 +189,29 @@ def test_docstring_addition(): @_preprocess_data() def funcy(ax, *args, **kwargs): """Funcy does nothing""" - pass - assert re.search(r".*All positional and all keyword arguments\.", - funcy.__doc__) - assert not re.search(r".*All positional arguments\.", - funcy.__doc__) - assert not re.search(r".*All arguments with the following names: .*", - funcy.__doc__) + assert re.search(r"every other argument", funcy.__doc__) + assert not re.search(r"the following arguments", funcy.__doc__) @_preprocess_data(replace_names=[]) def funcy(ax, x, y, z, bar=None): """Funcy does nothing""" - pass - assert not re.search(r".*All positional arguments\.", - funcy.__doc__) - assert not re.search(r".*All positional and all keyword arguments\.", - funcy.__doc__) - assert not re.search(r".*All arguments with the following names: .*", - funcy.__doc__) + assert not re.search(r"every other argument", funcy.__doc__) + assert not re.search(r"the following arguments", funcy.__doc__) @_preprocess_data(replace_names=["bar"]) def funcy(ax, x, y, z, bar=None): """Funcy does nothing""" - pass - assert not re.search(r".*All positional arguments\.", - funcy.__doc__) - assert re.search(r".*All arguments with the following names: 'bar'\.", - funcy.__doc__) - assert not re.search(r".*All positional and all keyword arguments\.", + assert not re.search(r"every other argument", funcy.__doc__) + assert not re.search(r"the following arguments .*: \*bar\*\.", funcy.__doc__) - @_preprocess_data(replace_names=["x", "bar"]) - def funcy(ax, x, y, z, bar=None): + @_preprocess_data(replace_names=["x", "t"]) + def funcy(ax, x, y, z, t=None): """Funcy does nothing""" - pass - # lists can print in any order, so test for both x, bar and bar, x. - assert re.search(r".*All arguments with the following names: '.*', '.*'\.", - funcy.__doc__) - assert re.search(r".*'x'.*", funcy.__doc__) - assert re.search(r".*'bar'.*", funcy.__doc__) - assert not re.search(r".*All positional and all keyword arguments\.", - funcy.__doc__) - assert not re.search(r".*All positional arguments\.", + assert not re.search(r"every other argument", funcy.__doc__) + assert not re.search(r"the following arguments .*: \*x\*, \*t\*\.", funcy.__doc__)