Skip to content

Minor refactoring of docstring formatting in preprocess_data #10191

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
Jan 8, 2018
Merged

Minor refactoring of docstring formatting in preprocess_data #10191

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
55 changes: 39 additions & 16 deletions lib/matplotlib/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1545,6 +1545,41 @@ def _replacer(data, key):
"""


def _add_data_doc(docstring, replace_names, replace_all_args):
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't these be keyword arguments if they're optional? (ie. docstring, replace_names=None, replace_all_args=False)

Copy link
Member Author

@timhoffm timhoffm Jan 8, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No. This is just a private helper function which does not need the flexibility of keyword args. In particular, I do not want to duplicate the defaults of _preprocess_data.

The docstring was just a copy from _preprocess_data. I've now removed the optional, and default notes.

"""Add documentation for a *data* field to the given docstring.

Parameters
----------
docstring : str
The input docstring.
replace_names : list of strings or None
The list of parameter names which arguments should be replaced by
`data[name]`. If None, all arguments are replaced if they are
included in `data`.
replace_all_args : bool
If True, all arguments in *args get replaced, even if they are not
in replace_names.

Returns
-------
The augmented docstring.
"""
if docstring is None:
docstring = ''
else:
docstring = dedent(docstring)
_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(sorted(replace_names)))
return docstring + _DATA_DOC_APPENDIX.format(replaced=_repl)


def _preprocess_data(replace_names=None, replace_all_args=False,
label_namer=None, positional_parameter_names=None):
"""
Expand Down Expand Up @@ -1789,27 +1824,15 @@ def inner(ax, *args, **kwargs):
"the Matplotlib list!)" % (label_namer, func.__name__),
RuntimeWarning, stacklevel=2)
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(sorted(replace_names)))
inner.__doc__ = (pre_doc +
_DATA_DOC_APPENDIX.format(replaced=_repl))

inner.__doc__ = _add_data_doc(inner.__doc__,
replace_names, replace_all_args)
if not python_has_wrapped:
inner.__wrapped__ = func
if new_sig is not None:
inner.__signature__ = new_sig
return inner

return param

_log.info('matplotlib version %s', __version__)
Expand Down