Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/IPython/core/magic_arguments.py: 84%

1''' A decorator-based method of constructing IPython magics with `argparse` 

2option handling. 

3 

4New magic functions can be defined like so:: 

5 

6 from IPython.core.magic_arguments import (argument, magic_arguments, 

7 parse_argstring) 

8 

9 @magic_arguments() 

10 @argument('-o', '--option', help='An optional argument.') 

11 @argument('arg', type=int, help='An integer positional argument.') 

12 def magic_cool(self, arg): 

13 """ A really cool magic command. 

14 

15 """ 

16 args = parse_argstring(magic_cool, arg) 

17 ... 

18 

19The `@magic_arguments` decorator marks the function as having argparse arguments. 

20The `@argument` decorator adds an argument using the same syntax as argparse's 

21`add_argument()` method. More sophisticated uses may also require the 

22`@argument_group` or `@kwds` decorator to customize the formatting and the 

23parsing. 

24 

25Help text for the magic is automatically generated from the docstring and the 

26arguments:: 

27 

28 In[1]: %cool? 

29 %cool [-o OPTION] arg 

30  

31 A really cool magic command. 

32  

33 positional arguments: 

34 arg An integer positional argument. 

35  

36 optional arguments: 

37 -o OPTION, --option OPTION 

38 An optional argument. 

39 

40Here is an elaborated example that uses default parameters in `argument` and calls the `args` in the cell magic:: 

41 

42 from IPython.core.magic import register_cell_magic 

43 from IPython.core.magic_arguments import (argument, magic_arguments, 

44 parse_argstring) 

45 

46 

47 @magic_arguments() 

48 @argument( 

49 "--option", 

50 "-o", 

51 help=("Add an option here"), 

52 ) 

53 @argument( 

54 "--style", 

55 "-s", 

56 default="foo", 

57 help=("Add some style arguments"), 

58 ) 

59 @register_cell_magic 

60 def my_cell_magic(line, cell): 

61 args = parse_argstring(my_cell_magic, line) 

62 print(f"{args.option=}") 

63 print(f"{args.style=}") 

64 print(f"{cell=}") 

65 

66In a jupyter notebook, this cell magic can be executed like this:: 

67 

68 %%my_cell_magic -o Hello 

69 print("bar") 

70 i = 42 

71 

72Inheritance diagram: 

73 

74.. inheritance-diagram:: IPython.core.magic_arguments 

75 :parts: 3 

76 

77''' 

78#----------------------------------------------------------------------------- 

79# Copyright (C) 2010-2011, IPython Development Team. 

80# 

81# Distributed under the terms of the Modified BSD License. 

82# 

83# The full license is in the file COPYING.txt, distributed with this software. 

84#----------------------------------------------------------------------------- 

85import argparse 

86import re 

87 

88# Our own imports 

89from IPython.core.error import UsageError 

90from IPython.utils.decorators import undoc 

91from IPython.utils.process import arg_split 

92from IPython.utils.text import dedent 

93 

94NAME_RE = re.compile(r"[a-zA-Z][a-zA-Z0-9_-]*$") 

95 

96@undoc 

97class MagicHelpFormatter(argparse.RawDescriptionHelpFormatter): 

98 """A HelpFormatter with a couple of changes to meet our needs. 

99 """ 

100 # Modified to dedent text. 

101 def _fill_text(self, text, width, indent): 

102 return argparse.RawDescriptionHelpFormatter._fill_text(self, dedent(text), width, indent) 

103 

104 # Modified to wrap argument placeholders in <> where necessary. 

105 def _format_action_invocation(self, action): 

106 if not action.option_strings: 

107 metavar, = self._metavar_formatter(action, action.dest)(1) 

108 return metavar 

109 

110 else: 

111 parts = [] 

112 

113 # if the Optional doesn't take a value, format is: 

114 # -s, --long 

115 if action.nargs == 0: 

116 parts.extend(action.option_strings) 

117 

118 # if the Optional takes a value, format is: 

119 # -s ARGS, --long ARGS 

120 else: 

121 default = action.dest.upper() 

122 args_string = self._format_args(action, default) 

123 # IPYTHON MODIFICATION: If args_string is not a plain name, wrap 

124 # it in <> so it's valid RST. 

125 if not NAME_RE.match(args_string): 

126 args_string = "<%s>" % args_string 

127 for option_string in action.option_strings: 

128 parts.append('%s %s' % (option_string, args_string)) 

129 

130 return ', '.join(parts) 

131 

132 # Override the default prefix ('usage') to our % magic escape, 

133 # in a code block. 

134 def add_usage(self, usage, actions, groups, prefix="::\n\n %"): 

135 super(MagicHelpFormatter, self).add_usage(usage, actions, groups, prefix) 

136 

137class MagicArgumentParser(argparse.ArgumentParser): 

138 """ An ArgumentParser tweaked for use by IPython magics. 

139 """ 

140 def __init__(self, 

141 prog=None, 

142 usage=None, 

143 description=None, 

144 epilog=None, 

145 parents=None, 

146 formatter_class=MagicHelpFormatter, 

147 prefix_chars='-', 

148 argument_default=None, 

149 conflict_handler='error', 

150 add_help=False): 

151 if parents is None: 

152 parents = [] 

153 super(MagicArgumentParser, self).__init__(prog=prog, usage=usage, 

154 description=description, epilog=epilog, 

155 parents=parents, formatter_class=formatter_class, 

156 prefix_chars=prefix_chars, argument_default=argument_default, 

157 conflict_handler=conflict_handler, add_help=add_help) 

158 

159 def error(self, message): 

160 """ Raise a catchable error instead of exiting. 

161 """ 

162 raise UsageError(message) 

163 

164 def parse_argstring(self, argstring): 

165 """ Split a string into an argument list and parse that argument list. 

166 """ 

167 argv = arg_split(argstring) 

168 return self.parse_args(argv) 

169 

170 

171def construct_parser(magic_func): 

172 """ Construct an argument parser using the function decorations. 

173 """ 

174 kwds = getattr(magic_func, 'argcmd_kwds', {}) 

175 if 'description' not in kwds: 

176 kwds['description'] = getattr(magic_func, '__doc__', None) 

177 arg_name = real_name(magic_func) 

178 parser = MagicArgumentParser(arg_name, **kwds) 

179 # Reverse the list of decorators in order to apply them in the 

180 # order in which they appear in the source. 

181 group = None 

182 for deco in magic_func.decorators[::-1]: 

183 result = deco.add_to_parser(parser, group) 

184 if result is not None: 

185 group = result 

186 

187 # Replace the magic function's docstring with the full help text. 

188 magic_func.__doc__ = parser.format_help() 

189 

190 return parser 

191 

192 

193def parse_argstring(magic_func, argstring): 

194 """ Parse the string of arguments for the given magic function. 

195 """ 

196 return magic_func.parser.parse_argstring(argstring) 

197 

198 

199def real_name(magic_func): 

200 """ Find the real name of the magic. 

201 """ 

202 magic_name = magic_func.__name__ 

203 if magic_name.startswith('magic_'): 

204 magic_name = magic_name[len('magic_'):] 

205 return getattr(magic_func, 'argcmd_name', magic_name) 

206 

207 

208class ArgDecorator(object): 

209 """ Base class for decorators to add ArgumentParser information to a method. 

210 """ 

211 

212 def __call__(self, func): 

213 if not getattr(func, 'has_arguments', False): 

214 func.has_arguments = True 

215 func.decorators = [] 

216 func.decorators.append(self) 

217 return func 

218 

219 def add_to_parser(self, parser, group): 

220 """ Add this object's information to the parser, if necessary. 

221 """ 

222 pass 

223 

224 

225class magic_arguments(ArgDecorator): 

226 """ Mark the magic as having argparse arguments and possibly adjust the 

227 name. 

228 """ 

229 

230 def __init__(self, name=None): 

231 self.name = name 

232 

233 def __call__(self, func): 

234 if not getattr(func, 'has_arguments', False): 

235 func.has_arguments = True 

236 func.decorators = [] 

237 if self.name is not None: 

238 func.argcmd_name = self.name 

239 # This should be the first decorator in the list of decorators, thus the 

240 # last to execute. Build the parser. 

241 func.parser = construct_parser(func) 

242 return func 

243 

244 

245class ArgMethodWrapper(ArgDecorator): 

246 

247 """ 

248 Base class to define a wrapper for ArgumentParser method. 

249 

250 Child class must define either `_method_name` or `add_to_parser`. 

251 

252 """ 

253 

254 _method_name: str 

255 

256 def __init__(self, *args, **kwds): 

257 self.args = args 

258 self.kwds = kwds 

259 

260 def add_to_parser(self, parser, group): 

261 """ Add this object's information to the parser. 

262 """ 

263 if group is not None: 

264 parser = group 

265 getattr(parser, self._method_name)(*self.args, **self.kwds) 

266 return None 

267 

268 

269class argument(ArgMethodWrapper): 

270 """ Store arguments and keywords to pass to add_argument(). 

271 

272 Instances also serve to decorate command methods. 

273 """ 

274 _method_name = 'add_argument' 

275 

276 

277class defaults(ArgMethodWrapper): 

278 """ Store arguments and keywords to pass to set_defaults(). 

279 

280 Instances also serve to decorate command methods. 

281 """ 

282 _method_name = 'set_defaults' 

283 

284 

285class argument_group(ArgMethodWrapper): 

286 """ Store arguments and keywords to pass to add_argument_group(). 

287 

288 Instances also serve to decorate command methods. 

289 """ 

290 

291 def add_to_parser(self, parser, group): 

292 """ Add this object's information to the parser. 

293 """ 

294 return parser.add_argument_group(*self.args, **self.kwds) 

295 

296 

297class kwds(ArgDecorator): 

298 """ Provide other keywords to the sub-parser constructor. 

299 """ 

300 def __init__(self, **kwds): 

301 self.kwds = kwds 

302 

303 def __call__(self, func): 

304 func = super(kwds, self).__call__(func) 

305 func.argcmd_kwds = self.kwds 

306 return func 

307 

308 

309__all__ = ['magic_arguments', 'argument', 'argument_group', 'kwds', 

310 'parse_argstring']