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

Skip to content

Commit e39ff24

Browse files
anntzeranntzer
committed
Simplify and tighten the docstring handling API.
- 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.
1 parent de38ef2 commit e39ff24

File tree

10 files changed

+159
-155
lines changed

10 files changed

+159
-155
lines changed

‎doc/api/next_api_changes/2018-01-08-AL.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
Deprecations
2+
````````````
3+
4+
``cbook.dedent``, ``docstring.Appender``, ``docstring.dedent``, and
5+
``docstring.copy_dedent`` are deprecated (use the standard library's docstring
6+
manipulation tools, such as `inspect.cleandoc` and `inspect.getdoc` instead).

‎lib/matplotlib/__init__.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1554,7 +1554,7 @@ def _add_data_doc(docstring, replace_names):
15541554
-------
15551555
The augmented docstring.
15561556
"""
1557-
docstring = dedent(docstring) if docstring is not None else ""
1557+
docstring = inspect.cleandoc(docstring) if docstring is not None else ""
15581558
repl = ("* All positional and all keyword arguments."
15591559
if replace_names is None else
15601560
""

‎lib/matplotlib/cbook/__init__.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -573,6 +573,7 @@ def get_realpath_and_stat(path):
573573
_dedent_regex = {}
574574

575575

576+
@deprecated("3.1", alternative="inspect.cleandoc")
576577
def dedent(s):
577578
"""
578579
Remove excess indentation from docstring *s*.

‎lib/matplotlib/docstring.py

Lines changed: 34 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,49 @@
1+
import inspect
2+
13
from matplotlib import cbook
24

35

46
class Substitution(object):
57
"""
6-
A decorator to take a function's docstring and perform string
7-
substitution on it.
8+
A decorator that performs %-substitution on an object's docstring.
89
9-
This decorator should be robust even if func.__doc__ is None
10-
(for example, if -OO was passed to the interpreter)
10+
This decorator should be robust even if ``obj.__doc__`` is None (for
11+
example, if -OO was passed to the interpreter).
1112
12-
Usage: construct a docstring.Substitution with a sequence or
13-
dictionary suitable for performing substitution; then
14-
decorate a suitable function with the constructed object. e.g.
13+
Usage: construct a docstring.Substitution with a sequence or dictionary
14+
suitable for performing substitution; then decorate a suitable function
15+
with the constructed object, e.g.::
1516
16-
sub_author_name = Substitution(author='Jason')
17+
sub_author_name = Substitution(author='Jason')
1718
18-
@sub_author_name
19-
def some_function(x):
20-
"%(author)s wrote this function"
19+
@sub_author_name
20+
def some_function(x):
21+
"%(author)s wrote this function"
2122
22-
# note that some_function.__doc__ is now "Jason wrote this function"
23+
# note that some_function.__doc__ is now "Jason wrote this function"
2324
24-
One can also use positional arguments.
25+
One can also use positional arguments::
2526
26-
sub_first_last_names = Substitution('Edgar Allen', 'Poe')
27+
sub_first_last_names = Substitution('Edgar Allen', 'Poe')
2728
28-
@sub_first_last_names
29-
def some_function(x):
30-
"%s %s wrote the Raven"
29+
@sub_first_last_names
30+
def some_function(x):
31+
"%s %s wrote the Raven"
3132
"""
3233
def __init__(self, *args, **kwargs):
33-
assert not (len(args) and len(kwargs)), \
34-
"Only positional or keyword args are allowed"
34+
if args and kwargs:
35+
raise TypeError("Only positional or keyword args are allowed")
3536
self.params = args or kwargs
3637

3738
def __call__(self, func):
38-
func.__doc__ = func.__doc__ and func.__doc__ % self.params
39+
if func.__doc__:
40+
func.__doc__ %= self.params
3941
return func
4042

4143
def update(self, *args, **kwargs):
42-
"Assume self.params is a dict and update it with supplied args"
44+
"""
45+
Update ``self.params`` (which must be a dict) with the supplied args.
46+
"""
4347
self.params.update(*args, **kwargs)
4448

4549
@classmethod
@@ -55,6 +59,7 @@ def from_params(cls, params):
5559
return result
5660

5761

62+
@cbook.deprecated("3.1")
5863
class Appender(object):
5964
"""
6065
A function decorator that will append an addendum to the docstring
@@ -84,6 +89,7 @@ def __call__(self, func):
8489
return func
8590

8691

92+
@cbook.deprecated("3.1", alternative="inspect.getdoc()")
8793
def dedent(func):
8894
"Dedent a docstring (if present)"
8995
func.__doc__ = func.__doc__ and cbook.dedent(func.__doc__)
@@ -98,17 +104,19 @@ def do_copy(target):
98104
return target
99105
return do_copy
100106

101-
# create a decorator that will house the various documentation that
102-
# is reused throughout matplotlib
107+
108+
# Create a decorator that will house the various docstring snippets reused
109+
# throughout Matplotlib.
103110
interpd = Substitution()
104111

105112

106113
def dedent_interpd(func):
107-
"""A special case of the interpd that first performs a dedent on
108-
the incoming docstring"""
109-
return interpd(dedent(func))
114+
"""Dedent *func*'s docstring, then interpolate it with ``interpd``."""
115+
func.__doc__ = inspect.getdoc(func.__doc__)
116+
return interpd(func)
110117

111118

119+
@cbook.deprecated("3.1", alternative="docstring.copy() and cbook.dedent()")
112120
def copy_dedent(source):
113121
"""A decorator that will copy the docstring from the source and
114122
then dedent it"""

‎lib/matplotlib/mlab.py

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,7 @@
5454
"""
5555

5656
import csv
57+
import inspect
5758

5859
import numpy as np
5960

@@ -646,7 +647,7 @@ def _single_spectrum_helper(x, mode, Fs=None, window=None, pad_to=None,
646647

647648

648649
# Split out these keyword docs so that they can be used elsewhere
649-
docstring.interpd.update(Spectral=cbook.dedent("""
650+
docstring.interpd.update(Spectral=inspect.cleandoc("""
650651
Fs : scalar
651652
The sampling frequency (samples per time unit). It is used
652653
to calculate the Fourier frequencies, freqs, in cycles per time
@@ -670,7 +671,7 @@ def _single_spectrum_helper(x, mode, Fs=None, window=None, pad_to=None,
670671
"""))
671672

672673

673-
docstring.interpd.update(Single_Spectrum=cbook.dedent("""
674+
docstring.interpd.update(Single_Spectrum=inspect.cleandoc("""
674675
pad_to : int
675676
The number of points to which the data segment is padded when
676677
performing the FFT. While not increasing the actual resolution of
@@ -682,7 +683,7 @@ def _single_spectrum_helper(x, mode, Fs=None, window=None, pad_to=None,
682683
"""))
683684

684685

685-
docstring.interpd.update(PSD=cbook.dedent("""
686+
docstring.interpd.update(PSD=inspect.cleandoc("""
686687
pad_to : int
687688
The number of points to which the data segment is padded when
688689
performing the FFT. This can be different from *NFFT*, which

‎lib/matplotlib/patches.py

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import contextlib
22
import functools
3+
import inspect
34
import math
45
from numbers import Number
56
import textwrap
@@ -2435,8 +2436,8 @@ def transmute(self, x0, y0, width, height, mutation_size):
24352436
return Path(saw_vertices, codes)
24362437

24372438
if __doc__: # __doc__ could be None if -OO optimization is enabled
2438-
__doc__ = cbook.dedent(__doc__) % \
2439-
{"AvailableBoxstyles": _pprint_styles(_style_list)}
2439+
__doc__ = inspect.cleandoc(__doc__) % {
2440+
"AvailableBoxstyles": _pprint_styles(_style_list)}
24402441

24412442
docstring.interpd.update(
24422443
AvailableBoxstyles=_pprint_styles(BoxStyle._style_list),
@@ -3112,8 +3113,8 @@ def connect(self, posA, posB):
31123113
return Path(vertices, codes)
31133114

31143115
if __doc__:
3115-
__doc__ = cbook.dedent(__doc__) % \
3116-
{"AvailableConnectorstyles": _pprint_styles(_style_list)}
3116+
__doc__ = inspect.cleandoc(__doc__) % {
3117+
"AvailableConnectorstyles": _pprint_styles(_style_list)}
31173118

31183119

31193120
def _point_along_a_line(x0, y0, x1, y1, d):
@@ -3913,8 +3914,8 @@ def transmute(self, path, mutation_size, linewidth):
39133914
return path, True
39143915

39153916
if __doc__:
3916-
__doc__ = cbook.dedent(__doc__) % \
3917-
{"AvailableArrowstyles": _pprint_styles(_style_list)}
3917+
__doc__ = inspect.cleandoc(__doc__) % {
3918+
"AvailableArrowstyles": _pprint_styles(_style_list)}
39183919

39193920

39203921
docstring.interpd.update(

0 commit comments

Comments
 (0)