1+ import inspect
2+
13from matplotlib import cbook
24
35
46class 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" )
5863class 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()" )
8793def 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.
103110interpd = Substitution ()
104111
105112
106113def 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()" )
112120def copy_dedent (source ):
113121 """A decorator that will copy the docstring from the source and
114122 then dedent it"""
0 commit comments