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 223b2b1

Browse filesBrowse files
QuLogicQuLogic
authored
Merge pull request #22148 from oscargus/deprecatedocstring
MNT: Deprecate `docstring`
2 parents f35a330 + 52df591 commit 223b2b1
Copy full SHA for 223b2b1
Expand file treeCollapse file tree

37 files changed

+305
-300
lines changed

‎doc/api/next_api_changes/deprecations/22148-OG.rst

Copy file name to clipboard
+5Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Module ``docstring`` deprecated
2+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3+
4+
The module ``matplotlib.docstring`` is considered internal and public access
5+
is deprecated.

‎doc/api/prev_api_changes/api_changes_3.5.0/removals.rst

Copy file name to clipboardExpand all lines: doc/api/prev_api_changes/api_changes_3.5.0/removals.rst
+1-1Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -214,7 +214,7 @@ The following class methods have been removed:
214214
- ``Colorbar.on_mappable_changed`` and ``Colorbar.update_bruteforce``; use
215215
``Colorbar.update_normal()`` instead
216216
- ``docstring.Substitution.from_params`` has been removed; directly assign to
217-
``params`` of `.Substitution` instead
217+
``params`` of ``docstring.Substitution`` instead
218218
- ``DraggableBase.artist_picker``; set the artist's picker instead
219219
- ``DraggableBase.on_motion_blit``; use `.DraggableBase.on_motion` instead
220220
- ``FigureCanvasGTK3._renderer_init``

‎doc/devel/documenting_mpl.rst

Copy file name to clipboardExpand all lines: doc/devel/documenting_mpl.rst
+3-3Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -684,14 +684,14 @@ are:
684684
2. as automated as possible so that as properties change, the docs
685685
are updated automatically.
686686

687-
The ``@docstring.interpd`` decorator implements this. Any function accepting
687+
The ``@_docstring.interpd`` decorator implements this. Any function accepting
688688
`.Line2D` pass-through ``kwargs``, e.g., `matplotlib.axes.Axes.plot`, can list
689689
a summary of the `.Line2D` properties, as follows:
690690

691691
.. code-block:: python
692692
693693
# in axes.py
694-
@docstring.interpd
694+
@_docstring.interpd
695695
def plot(self, *args, **kwargs):
696696
"""
697697
Some stuff omitted
@@ -726,7 +726,7 @@ gets interpolated into the docstring.
726726

727727
Note that this scheme does not work for decorating an Artist's ``__init__``, as
728728
the subclass and its properties are not defined yet at that point. Instead,
729-
``@docstring.interpd`` can be used to decorate the class itself -- at that
729+
``@_docstring.interpd`` can be used to decorate the class itself -- at that
730730
point, `.kwdoc` can list the properties and interpolate them into
731731
``__init__.__doc__``.
732732

‎lib/matplotlib/__init__.py

Copy file name to clipboardExpand all lines: lib/matplotlib/__init__.py
+2-2Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,7 @@
106106

107107
# cbook must import matplotlib only within function
108108
# definitions, so it is safe to import from it here.
109-
from . import _api, _version, cbook, docstring, rcsetup
109+
from . import _api, _version, cbook, _docstring, rcsetup
110110
from matplotlib.cbook import sanitize_sequence
111111
from matplotlib._api import MatplotlibDeprecationWarning
112112
from matplotlib.rcsetup import validate_backend, cycler
@@ -593,7 +593,7 @@ def gen_candidates():
593593
_deprecated_remain_as_none = {}
594594

595595

596-
@docstring.Substitution(
596+
@_docstring.Substitution(
597597
"\n".join(map("- {}".format, sorted(rcsetup._validators, key=str.lower)))
598598
)
599599
class RcParams(MutableMapping, dict):

‎lib/matplotlib/_docstring.py

Copy file name to clipboard
+97Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
import inspect
2+
3+
from . import _api
4+
5+
6+
class Substitution:
7+
"""
8+
A decorator that performs %-substitution on an object's docstring.
9+
10+
This decorator should be robust even if ``obj.__doc__`` is None (for
11+
example, if -OO was passed to the interpreter).
12+
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.::
16+
17+
sub_author_name = Substitution(author='Jason')
18+
19+
@sub_author_name
20+
def some_function(x):
21+
"%(author)s wrote this function"
22+
23+
# note that some_function.__doc__ is now "Jason wrote this function"
24+
25+
One can also use positional arguments::
26+
27+
sub_first_last_names = Substitution('Edgar Allen', 'Poe')
28+
29+
@sub_first_last_names
30+
def some_function(x):
31+
"%s %s wrote the Raven"
32+
"""
33+
def __init__(self, *args, **kwargs):
34+
if args and kwargs:
35+
raise TypeError("Only positional or keyword args are allowed")
36+
self.params = params = args or kwargs
37+
38+
def __call__(self, func):
39+
if func.__doc__:
40+
func.__doc__ = inspect.cleandoc(func.__doc__) % self.params
41+
return func
42+
43+
def update(self, *args, **kwargs):
44+
"""
45+
Update ``self.params`` (which must be a dict) with the supplied args.
46+
"""
47+
self.params.update(*args, **kwargs)
48+
49+
50+
class _ArtistKwdocLoader(dict):
51+
def __missing__(self, key):
52+
if not key.endswith(":kwdoc"):
53+
raise KeyError(key)
54+
name = key[:-len(":kwdoc")]
55+
from matplotlib.artist import Artist, kwdoc
56+
try:
57+
cls, = [cls for cls in _api.recursive_subclasses(Artist)
58+
if cls.__name__ == name]
59+
except ValueError as e:
60+
raise KeyError(key) from e
61+
return self.setdefault(key, kwdoc(cls))
62+
63+
64+
class _ArtistPropertiesSubstitution(Substitution):
65+
"""
66+
A `.Substitution` with two additional features:
67+
68+
- Substitutions of the form ``%(classname:kwdoc)s`` (ending with the
69+
literal ":kwdoc" suffix) trigger lookup of an Artist subclass with the
70+
given *classname*, and are substituted with the `.kwdoc` of that class.
71+
- Decorating a class triggers substitution both on the class docstring and
72+
on the class' ``__init__`` docstring (which is a commonly required
73+
pattern for Artist subclasses).
74+
"""
75+
76+
def __init__(self):
77+
self.params = _ArtistKwdocLoader()
78+
79+
def __call__(self, obj):
80+
super().__call__(obj)
81+
if isinstance(obj, type) and obj.__init__ != object.__init__:
82+
self(obj.__init__)
83+
return obj
84+
85+
86+
def copy(source):
87+
"""Copy a docstring from another source function (if present)."""
88+
def do_copy(target):
89+
if source.__doc__:
90+
target.__doc__ = source.__doc__
91+
return target
92+
return do_copy
93+
94+
95+
# Create a decorator that will house the various docstring snippets reused
96+
# throughout Matplotlib.
97+
dedent_interpd = interpd = _ArtistPropertiesSubstitution()

‎lib/matplotlib/_enums.py

Copy file name to clipboardExpand all lines: lib/matplotlib/_enums.py
+2-2Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
"""
1212

1313
from enum import Enum, auto
14-
from matplotlib import docstring
14+
from matplotlib import _docstring
1515

1616

1717
class _AutoStringNameEnum(Enum):
@@ -181,5 +181,5 @@ def demo():
181181
+ ", ".join([f"'{cs.name}'" for cs in CapStyle]) \
182182
+ "}"
183183

184-
docstring.interpd.update({'JoinStyle': JoinStyle.input_description,
184+
_docstring.interpd.update({'JoinStyle': JoinStyle.input_description,
185185
'CapStyle': CapStyle.input_description})

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.