Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Improve doc for data kwarg. #15776

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Dec 10, 2019
Merged

Improve doc for data kwarg. #15776

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 16 additions & 14 deletions lib/matplotlib/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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[<arg>]**:
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[<arg>]``) and
membership test (``<arg> in data``).
Objects passed as **data** must support item access (``data[s]``) and
membership test (``s in data``).
"""


Expand All @@ -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
Expand Down
41 changes: 10 additions & 31 deletions lib/matplotlib/tests/test_preprocess_data.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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__)