Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 4f6ada2

Browse filesBrowse 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
Copy full SHA for 4f6ada2

File tree

Expand file treeCollapse file tree

10 files changed

+159
-155
lines changed
Filter options
Expand file treeCollapse file tree

10 files changed

+159
-155
lines changed

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

Copy file name to clipboard
+6Lines 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

Copy file name to clipboardExpand all lines: lib/matplotlib/__init__.py
+1-1Lines 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

Copy file name to clipboardExpand all lines: lib/matplotlib/cbook/__init__.py
+1Lines 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

Copy file name to clipboardExpand all lines: lib/matplotlib/docstring.py
+34-26Lines 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

Copy file name to clipboardExpand all lines: lib/matplotlib/mlab.py
+4-3Lines 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

Copy file name to clipboardExpand all lines: lib/matplotlib/patches.py
+7-6Lines 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 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.