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

Skip to content

Commit 4f6ada2

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 8d62769 commit 4f6ada2

10 files changed

Lines changed: 159 additions & 155 deletions

File tree

‎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
@@ -1441,7 +1441,7 @@ def _add_data_doc(docstring, replace_names):
14411441
-------
14421442
The augmented docstring.
14431443
"""
1444-
docstring = dedent(docstring) if docstring is not None else ""
1444+
docstring = inspect.cleandoc(docstring) if docstring is not None else ""
14451445
repl = ("* All positional and all keyword arguments."
14461446
if replace_names is None else
14471447
""

‎lib/matplotlib/cbook/__init__.py‎

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

561561

562+
@deprecated("3.1", alternative="inspect.cleandoc")
562563
def dedent(s):
563564
"""
564565
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

@@ -618,7 +619,7 @@ def _single_spectrum_helper(x, mode, Fs=None, window=None, pad_to=None,
618619

619620

620621
# Split out these keyword docs so that they can be used elsewhere
621-
docstring.interpd.update(Spectral=cbook.dedent("""
622+
docstring.interpd.update(Spectral=inspect.cleandoc("""
622623
Fs : scalar
623624
The sampling frequency (samples per time unit). It is used
624625
to calculate the Fourier frequencies, freqs, in cycles per time
@@ -640,7 +641,7 @@ def _single_spectrum_helper(x, mode, Fs=None, window=None, pad_to=None,
640641
"""))
641642

642643

643-
docstring.interpd.update(Single_Spectrum=cbook.dedent("""
644+
docstring.interpd.update(Single_Spectrum=inspect.cleandoc("""
644645
pad_to : int
645646
The number of points to which the data segment is padded when
646647
performing the FFT. While not increasing the actual resolution of
@@ -652,7 +653,7 @@ def _single_spectrum_helper(x, mode, Fs=None, window=None, pad_to=None,
652653
"""))
653654

654655

655-
docstring.interpd.update(PSD=cbook.dedent("""
656+
docstring.interpd.update(PSD=inspect.cleandoc("""
656657
pad_to : int
657658
The number of points to which the data segment is padded when
658659
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),
@@ -3104,8 +3105,8 @@ def connect(self, posA, posB):
31043105
return Path(vertices, codes)
31053106

31063107
if __doc__:
3107-
__doc__ = cbook.dedent(__doc__) % \
3108-
{"AvailableConnectorstyles": _pprint_styles(_style_list)}
3108+
__doc__ = inspect.cleandoc(__doc__) % {
3109+
"AvailableConnectorstyles": _pprint_styles(_style_list)}
31093110

31103111

31113112
def _point_along_a_line(x0, y0, x1, y1, d):
@@ -3895,8 +3896,8 @@ def transmute(self, path, mutation_size, linewidth):
38953896
return path, True
38963897

38973898
if __doc__:
3898-
__doc__ = cbook.dedent(__doc__) % \
3899-
{"AvailableArrowstyles": _pprint_styles(_style_list)}
3899+
__doc__ = inspect.cleandoc(__doc__) % {
3900+
"AvailableArrowstyles": _pprint_styles(_style_list)}
39003901

39013902

39023903
docstring.interpd.update(

0 commit comments

Comments
 (0)