FazBrowse GitHub Viewer
|
Trending
|
URL:
|
Home
Tools:
[Download Repo ZIP]
[View Raw Code]
[Original HTTPS Page]
matplotlib/lib/matplotlib/_docstring.py at main · spha-code/matplotlib · GitHub
spha-code
matplotlib
Repository navigation
Code
Pull requests
Actions
Projects
Security and quality
Insights
Expand file tree
Breadcrumbs
matplotlib
/
lib
/
matplotlib
/
_docstring.py
Copy path
More file actions
More file actions
Latest commit
History
History
History
141 lines (104 loc) · 4.33 KB
Breadcrumbs
matplotlib
/
lib
/
matplotlib
/
_docstring.py
Copy path
File metadata and controls
141 lines (104 loc) · 4.33 KB
Raw
Copy raw file
Download raw file
Open symbols panel
Edit and raw actions
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
import
inspect
from
.
import
_api
def
kwarg_doc
(
text
):
"""
Decorator for defining the kwdoc documentation of artist properties.
This decorator can be applied to artist property setter methods.
The given text is stored in a private attribute ``_kwarg_doc`` on
the method. It is used to overwrite auto-generated documentation
in the *kwdoc list* for artists. The kwdoc list is used to document
``**kwargs`` when they are properties of an artist. See e.g. the
``**kwargs`` section in `.Axes.text`.
The text should contain the supported types, as well as the default
value if applicable, e.g.:
@_docstring.kwarg_doc("bool, default: :rc:`text.usetex`")
def set_usetex(self, usetex):
See Also
--------
matplotlib.artist.kwdoc
"""
def
decorator
(
func
):
func
.
_kwarg_doc
=
text
return
func
return
decorator
class
Substitution
:
"""
A decorator that performs %-substitution on an object's docstring.
This decorator should be robust even if ``obj.__doc__`` is None (for
example, if -OO was passed to the interpreter).
Usage: construct a docstring.Substitution with a sequence or dictionary
suitable for performing substitution; then decorate a suitable function
with the constructed object, e.g.::
sub_author_name = Substitution(author='Jason')
@sub_author_name
def some_function(x):
"%(author)s wrote this function"
# note that some_function.__doc__ is now "Jason wrote this function"
One can also use positional arguments::
sub_first_last_names = Substitution('Edgar Allen', 'Poe')
@sub_first_last_names
def some_function(x):
"%s %s wrote the Raven"
"""
def
__init__
(
self
,
*
args
,
**
kwargs
):
if
args
and
kwargs
:
raise
TypeError
(
"Only positional or keyword args are allowed"
)
self
.
params
=
args
or
kwargs
def
__call__
(
self
,
func
):
if
func
.
__doc__
:
func
.
__doc__
=
inspect
.
cleandoc
(
func
.
__doc__
)
%
self
.
params
return
func
class
_ArtistKwdocLoader
(
dict
):
def
__missing__
(
self
,
key
):
if
not
key
.
endswith
(
":kwdoc"
):
raise
KeyError
(
key
)
name
=
key
[:
-
len
(
":kwdoc"
)]
from
matplotlib
.
artist
import
Artist
,
kwdoc
try
:
cls
,
=
(
cls
for
cls
in
_api
.
recursive_subclasses
(
Artist
)
if
cls
.
__name__
==
name
)
except
ValueError
as
e
:
raise
KeyError
(
key
)
from
e
return
self
.
setdefault
(
key
,
kwdoc
(
cls
))
class
_ArtistPropertiesSubstitution
:
"""
A class to substitute formatted placeholders in docstrings.
This is realized in a single instance ``_docstring.interpd``.
Use `~._ArtistPropertiesSubstition.register` to define placeholders and
their substitution, e.g. ``_docstring.interpd.register(name="some value")``.
Use this as a decorator to apply the substitution::
@_docstring.interpd
def some_func():
'''Replace %(name)s.'''
Decorating a class triggers substitution both on the class docstring and
on the class' ``__init__`` docstring (which is a commonly required
pattern for Artist subclasses).
Substitutions of the form ``%(classname:kwdoc)s`` (ending with the
literal ":kwdoc" suffix) trigger lookup of an Artist subclass with the
given *classname*, and are substituted with the `.kwdoc` of that class.
"""
def
__init__
(
self
):
self
.
params
=
_ArtistKwdocLoader
()
def
register
(
self
,
**
kwargs
):
"""
Register substitutions.
``_docstring.interpd.register(name="some value")`` makes "name" available
as a named parameter that will be replaced by "some value".
"""
self
.
params
.
update
(
**
kwargs
)
def
__call__
(
self
,
obj
):
if
obj
.
__doc__
:
obj
.
__doc__
=
inspect
.
cleandoc
(
obj
.
__doc__
)
%
self
.
params
if
isinstance
(
obj
,
type
)
and
obj
.
__init__
!=
object
.
__init__
:
self
(
obj
.
__init__
)
return
obj
def
copy
(
source
):
"""Copy a docstring from another source function (if present)."""
def
do_copy
(
target
):
if
source
.
__doc__
:
target
.
__doc__
=
source
.
__doc__
return
target
return
do_copy
# Create a decorator that will house the various docstring snippets reused
# throughout Matplotlib.
interpd
=
_ArtistPropertiesSubstitution
()
Back
|
FazBrowse Home
|
New Git URL