Hide keyboard shortcuts

Hot-keys on this page

r m x p   toggle line displays

j k   next/prev highlighted chunk

0   (zero) top of page

1   (one) first highlighted chunk

1import inspect 

2 

3from matplotlib import cbook 

4 

5 

6class 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 = args or kwargs 

37 

38 def __call__(self, func): 

39 if func.__doc__: 

40 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 @classmethod 

50 def from_params(cls, params): 

51 """ 

52 In the case where the params is a mutable sequence (list or 

53 dictionary) and it may change before this class is called, one may 

54 explicitly use a reference to the params rather than using *args or 

55 **kwargs which will copy the values and not reference them. 

56 """ 

57 result = cls() 

58 result.params = params 

59 return result 

60 

61 

62@cbook.deprecated("3.1") 

63class Appender: 

64 r""" 

65 A function decorator that will append an addendum to the docstring 

66 of the target function. 

67 

68 This decorator should be robust even if func.__doc__ is None 

69 (for example, if -OO was passed to the interpreter). 

70 

71 Usage: construct a docstring.Appender with a string to be joined to 

72 the original docstring. An optional 'join' parameter may be supplied 

73 which will be used to join the docstring and addendum. e.g. 

74 

75 add_copyright = Appender("Copyright (c) 2009", join='\n') 

76 

77 @add_copyright 

78 def my_dog(has='fleas'): 

79 "This docstring will have a copyright below" 

80 pass 

81 """ 

82 def __init__(self, addendum, join=''): 

83 self.addendum = addendum 

84 self.join = join 

85 

86 def __call__(self, func): 

87 docitems = [func.__doc__, self.addendum] 

88 func.__doc__ = func.__doc__ and self.join.join(docitems) 

89 return func 

90 

91 

92@cbook.deprecated("3.1", alternative="inspect.getdoc()") 

93def dedent(func): 

94 "Dedent a docstring (if present)" 

95 func.__doc__ = func.__doc__ and cbook.dedent(func.__doc__) 

96 return func 

97 

98 

99def copy(source): 

100 "Copy a docstring from another source function (if present)" 

101 def do_copy(target): 

102 if source.__doc__: 

103 target.__doc__ = source.__doc__ 

104 return target 

105 return do_copy 

106 

107 

108# Create a decorator that will house the various docstring snippets reused 

109# throughout Matplotlib. 

110interpd = Substitution() 

111 

112 

113def dedent_interpd(func): 

114 """Dedent *func*'s docstring, then interpolate it with ``interpd``.""" 

115 func.__doc__ = inspect.getdoc(func) 

116 return interpd(func) 

117 

118 

119@cbook.deprecated("3.1", alternative="docstring.copy() and cbook.dedent()") 

120def copy_dedent(source): 

121 """A decorator that will copy the docstring from the source and 

122 then dedent it""" 

123 # note the following is ugly because "Python is not a functional 

124 # language" - GVR. Perhaps one day, functools.compose will exist. 

125 # or perhaps not. 

126 # http://mail.python.org/pipermail/patches/2007-February/021687.html 

127 return lambda target: dedent(copy(source)(target))