##// END OF EJS Templates
Ensure that all public magic decorators have descriptive docstrings.
Fernando Perez -
Show More
@@ -104,7 +104,40 b' def validate_type(magic_kind):'
104 magic_kinds, magic_kind)
104 magic_kinds, magic_kind)
105
105
106
106
107 def _magic_marker(magic_kind):
107 # The docstrings for the decorator below will be fairly similar for the two
108 # types (method and function), so we generate them here once and reuse the
109 # templates below.
110 _docstring_template = \
111 """Decorate the given {0} as {1} magic.
112
113 The decorator can be used:
114
115 i) without arguments: it will create a {1} magic named as the {0} being
116 decorated::
117
118 @deco
119 def foo(...)
120
121 will create a {1} magic named `foo`.
122
123 ii) with one string argument: which will be used as the actual name of the
124 resulting magic::
125
126 @deco('bar')
127 def foo(...)
128
129 will create a {1} magic named `bar`.
130 """
131
132 # These two are decorator factories. While they are conceptually very similar,
133 # there are enough differences in the details that it's simpler to have them
134 # written as completely standalone functions rather than trying to share code
135 # and make a single one with convoluted logic.
136
137 def _method_magic_marker(magic_kind):
138 """Decorator factory for methods in Magics subclasses.
139 """
140
108 validate_type(magic_kind)
141 validate_type(magic_kind)
109
142
110 # This is a closure to capture the magic_kind. We could also use a class,
143 # This is a closure to capture the magic_kind. We could also use a class,
@@ -116,14 +149,12 b' def _magic_marker(magic_kind):'
116 # "Naked" decorator call (just @foo, no args)
149 # "Naked" decorator call (just @foo, no args)
117 func = arg
150 func = arg
118 name = func.func_name
151 name = func.func_name
119 func.magic_name = name
120 retval = decorator(call, func)
152 retval = decorator(call, func)
121 record_magic(magics, magic_kind, name, name)
153 record_magic(magics, magic_kind, name, name)
122 elif isinstance(arg, basestring):
154 elif isinstance(arg, basestring):
123 # Decorator called with arguments (@foo('bar'))
155 # Decorator called with arguments (@foo('bar'))
124 name = arg
156 name = arg
125 def mark(func, *a, **kw):
157 def mark(func, *a, **kw):
126 func.magic_name = name
127 record_magic(magics, magic_kind, name, func.func_name)
158 record_magic(magics, magic_kind, name, func.func_name)
128 return decorator(call, func)
159 return decorator(call, func)
129 retval = mark
160 retval = mark
@@ -132,10 +163,15 b' def _magic_marker(magic_kind):'
132 "string or function")
163 "string or function")
133 return retval
164 return retval
134
165
166 # Ensure the resulting decorator has a usable docstring
167 magic_deco.__doc__ = _docstring_template.format('method', magic_kind)
135 return magic_deco
168 return magic_deco
136
169
137
170
138 def _function_magic_marker(magic_kind):
171 def _function_magic_marker(magic_kind):
172 """Decorator factory for standalone functions.
173 """
174
139 validate_type(magic_kind)
175 validate_type(magic_kind)
140
176
141 # This is a closure to capture the magic_kind. We could also use a class,
177 # This is a closure to capture the magic_kind. We could also use a class,
@@ -172,15 +208,17 b' def _function_magic_marker(magic_kind):'
172 "string or function")
208 "string or function")
173 return retval
209 return retval
174
210
211 # Ensure the resulting decorator has a usable docstring
212 magic_deco.__doc__ = _docstring_template.format('function', magic_kind)
175 return magic_deco
213 return magic_deco
176
214
177
215
178 # Create the actual decorators for public use
216 # Create the actual decorators for public use
179
217
180 # These three are used to decorate methods in class definitions
218 # These three are used to decorate methods in class definitions
181 line_magic = _magic_marker('line')
219 line_magic = _method_magic_marker('line')
182 cell_magic = _magic_marker('cell')
220 cell_magic = _method_magic_marker('cell')
183 line_cell_magic = _magic_marker('line_cell')
221 line_cell_magic = _method_magic_marker('line_cell')
184
222
185 # These three decorate standalone functions and perform the decoration
223 # These three decorate standalone functions and perform the decoration
186 # immediately. They can only run where get_ipython() works
224 # immediately. They can only run where get_ipython() works
General Comments 0
You need to be logged in to leave comments. Login now