FilesExpand file tree

v3.10.5

/

_docstring.py

Copy path

Blame

More file actions

Blame

More file actions

Latest commit

 

History

History

History

141 lines (104 loc) · 4.33 KB

v3.10.5

/

_docstring.py

Copy path

Top

File metadata and controls

• Code
• Blame

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()