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

Skip to content

Simplify and tighten the docstring handling API. #13125

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.

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
Feb 3, 2019

Conversation

anntzer
Copy link
Contributor

@anntzer anntzer commented Jan 7, 2019

  • Despite what the comment says, I find no import time difference
    between using cbook.dedent and inspect.cleandoc/inspect.getdoc, so use
    the stdlib function. Deprecate cbook.dedent and docstring.dedent.
  • Deprecate the Appender class, which is both (effectively) unused and a
    ridiculously overengineered API.
  • We don't need to dedent the pyplot docstring, just to copy them from
    the Axes methods. Deprecate docstring.copy_dedent.
  • We don't need to dedent the anchored_artists docstrings.

PR Summary

PR Checklist

  • Has Pytest style unit tests
  • Code is Flake 8 compliant
  • New features are documented, with examples if plot related
  • Documentation is sphinx and numpydoc compliant
  • Added an entry to doc/users/next_whats_new/ if major new feature (follow instructions in README.rst there)
  • Documented in doc/api/api_changes.rst if API changed in a backward-incompatible way

@timhoffm
Copy link
Member

timhoffm commented Jan 10, 2019

Despite what the comment says, I find no import time difference

At least for the single call, there's a factor 3 difference.

s = """
    A GUI neutral radio button.

    For the buttons to remain responsive
    you must keep a reference to this object.

    The following attributes are exposed:

     *ax*
        The :class:`matplotlib.axes.Axes` instance the buttons are in

     *activecolor*
        The color of the button when clicked

     *labels*
        A list of :class:`matplotlib.text.Text` instances

     *circles*
        A list of :class:`matplotlib.patches.Circle` instances

     *value_selected*
        A string listing the current value selected

    Connect to the RadioButtons with the :meth:`on_clicked` method
    """

from inspect import cleandoc
from matplotlib.cbook import dedent
%timeit cleandoc(s)
27.3 µs ± 859 ns per loop (mean ± std. dev. of 7 runs, 10000 loops each)

%timeit dedent(s)
10.4 µs ± 172 ns per loop (mean ± std. dev. of 7 runs, 100000 loops each)

Maybe we're not doing it often enough, but I would have assumed that this would parse a lot of our docstrings.

@anntzer
Copy link
Contributor Author

anntzer commented Jan 10, 2019

Instrumenting calls to cbook.dedent (with global counters) shows that after removing the unnecessary calls to dedent in pyplot (as this PR does), there are 123 calls to dedent, so we're talking about a ~2ms difference (which is real, but likely quite less than the noise of timing the import of the whole library).
I can revert that specific part though if people think it's important...

@timhoffm
Copy link
Member

Fair enough.

Copy link
Member

@jklymak jklymak left a comment

Choose a reason for hiding this comment

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

@anntzer anntzer force-pushed the simplify-docstring.py branch from e39ff24 to 15188fd Compare January 15, 2019 22:08
@anntzer
Copy link
Contributor Author

anntzer commented Jan 15, 2019

Good catch... should be fixed now.

diff --git c/lib/matplotlib/docstring.py w/lib/matplotlib/docstring.py
index 79ea63a96..88b7a022b 100644
--- c/lib/matplotlib/docstring.py
+++ w/lib/matplotlib/docstring.py
@@ -112,7 +112,7 @@ interpd = Substitution()
 
 def dedent_interpd(func):
     """Dedent *func*'s docstring, then interpolate it with ``interpd``."""
-    func.__doc__ = inspect.getdoc(func.__doc__)
+    func.__doc__ = inspect.getdoc(func)
     return interpd(func)

(duh)

@jklymak
Copy link
Member

jklymak commented Jan 16, 2019

Seems to work now...

- Despite what the comment says, I find no import time difference
  between using cbook.dedent and inspect.cleandoc/inspect.getdoc, so use
  the stdlib function.  Deprecate `cbook.dedent` and `docstring.dedent`.
- Deprecate the Appender class, which is both (effectively) unused and a
  ridiculously overengineered API.
- We don't need to dedent the pyplot docstring, just to copy them from
  the Axes methods.  Deprecate `docstring.copy_dedent`.
- We don't need to dedent the anchored_artists docstrings.
@anntzer
Copy link
Contributor Author

anntzer commented Feb 2, 2019

rebased

@timhoffm timhoffm merged commit f92bd01 into matplotlib:master Feb 3, 2019
@anntzer anntzer deleted the simplify-docstring.py branch February 3, 2019 16:25
@QuLogic QuLogic added this to the v3.1 milestone Feb 4, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants