##// END OF EJS Templates
sigh
nfgf -
Show More
@@ -1,757 +1,757
1 1 # encoding: utf-8
2 2 """Magic functions for InteractiveShell.
3 3 """
4 4
5 5 #-----------------------------------------------------------------------------
6 6 # Copyright (C) 2001 Janko Hauser <jhauser@zscout.de> and
7 7 # Copyright (C) 2001 Fernando Perez <fperez@colorado.edu>
8 8 # Copyright (C) 2008 The IPython Development Team
9 9
10 10 # Distributed under the terms of the BSD License. The full license is in
11 11 # the file COPYING, distributed as part of this software.
12 12 #-----------------------------------------------------------------------------
13 13
14 14 import os
15 15 import re
16 16 import sys
17 17 from getopt import getopt, GetoptError
18 18
19 19 from traitlets.config.configurable import Configurable
20 20 from . import oinspect
21 21 from .error import UsageError
22 22 from .inputtransformer2 import ESC_MAGIC, ESC_MAGIC2
23 23 from ..utils.ipstruct import Struct
24 24 from ..utils.process import arg_split
25 25 from ..utils.text import dedent
26 26 from traitlets import Bool, Dict, Instance, observe
27 27 from logging import error
28 28
29 29 #-----------------------------------------------------------------------------
30 30 # Globals
31 31 #-----------------------------------------------------------------------------
32 32
33 33 # A dict we'll use for each class that has magics, used as temporary storage to
34 34 # pass information between the @line/cell_magic method decorators and the
35 35 # @magics_class class decorator, because the method decorators have no
36 36 # access to the class when they run. See for more details:
37 37 # http://stackoverflow.com/questions/2366713/can-a-python-decorator-of-an-instance-method-access-the-class
38 38
39 39 magics = dict(line={}, cell={})
40 40
41 41 magic_kinds = ('line', 'cell')
42 42 magic_spec = ('line', 'cell', 'line_cell')
43 43 magic_escapes = dict(line=ESC_MAGIC, cell=ESC_MAGIC2)
44 44
45 45 #-----------------------------------------------------------------------------
46 46 # Utility classes and functions
47 47 #-----------------------------------------------------------------------------
48 48
49 49 class Bunch: pass
50 50
51 51
52 52 def on_off(tag):
53 53 """Return an ON/OFF string for a 1/0 input. Simple utility function."""
54 54 return ['OFF','ON'][tag]
55 55
56 56
57 57 def compress_dhist(dh):
58 58 """Compress a directory history into a new one with at most 20 entries.
59 59
60 60 Return a new list made from the first and last 10 elements of dhist after
61 61 removal of duplicates.
62 62 """
63 63 head, tail = dh[:-10], dh[-10:]
64 64
65 65 newhead = []
66 66 done = set()
67 67 for h in head:
68 68 if h in done:
69 69 continue
70 70 newhead.append(h)
71 71 done.add(h)
72 72
73 73 return newhead + tail
74 74
75 75
76 76 def needs_local_scope(func):
77 77 """Decorator to mark magic functions which need to local scope to run."""
78 78 func.needs_local_scope = True
79 79 return func
80 80
81 81 #-----------------------------------------------------------------------------
82 82 # Class and method decorators for registering magics
83 83 #-----------------------------------------------------------------------------
84 84
85 85 def magics_class(cls):
86 86 """Class decorator for all subclasses of the main Magics class.
87 87
88 88 Any class that subclasses Magics *must* also apply this decorator, to
89 89 ensure that all the methods that have been decorated as line/cell magics
90 90 get correctly registered in the class instance. This is necessary because
91 91 when method decorators run, the class does not exist yet, so they
92 92 temporarily store their information into a module global. Application of
93 93 this class decorator copies that global data to the class instance and
94 94 clears the global.
95 95
96 96 Obviously, this mechanism is not thread-safe, which means that the
97 97 *creation* of subclasses of Magic should only be done in a single-thread
98 98 context. Instantiation of the classes has no restrictions. Given that
99 99 these classes are typically created at IPython startup time and before user
100 100 application code becomes active, in practice this should not pose any
101 101 problems.
102 102 """
103 103 cls.registered = True
104 104 cls.magics = dict(line = magics['line'],
105 105 cell = magics['cell'])
106 106 magics['line'] = {}
107 107 magics['cell'] = {}
108 108 return cls
109 109
110 110
111 111 def record_magic(dct, magic_kind, magic_name, func):
112 112 """Utility function to store a function as a magic of a specific kind.
113 113
114 114 Parameters
115 115 ----------
116 116 dct : dict
117 117 A dictionary with 'line' and 'cell' subdicts.
118 118 magic_kind : str
119 119 Kind of magic to be stored.
120 120 magic_name : str
121 121 Key to store the magic as.
122 122 func : function
123 123 Callable object to store.
124 124 """
125 125 if magic_kind == 'line_cell':
126 126 dct['line'][magic_name] = dct['cell'][magic_name] = func
127 127 else:
128 128 dct[magic_kind][magic_name] = func
129 129
130 130
131 131 def validate_type(magic_kind):
132 132 """Ensure that the given magic_kind is valid.
133 133
134 134 Check that the given magic_kind is one of the accepted spec types (stored
135 135 in the global `magic_spec`), raise ValueError otherwise.
136 136 """
137 137 if magic_kind not in magic_spec:
138 138 raise ValueError('magic_kind must be one of %s, %s given' %
139 139 magic_kinds, magic_kind)
140 140
141 141
142 142 # The docstrings for the decorator below will be fairly similar for the two
143 143 # types (method and function), so we generate them here once and reuse the
144 144 # templates below.
145 145 _docstring_template = \
146 146 """Decorate the given {0} as {1} magic.
147 147
148 148 The decorator can be used with or without arguments, as follows.
149 149
150 150 i) without arguments: it will create a {1} magic named as the {0} being
151 151 decorated::
152 152
153 153 @deco
154 154 def foo(...)
155 155
156 156 will create a {1} magic named `foo`.
157 157
158 158 ii) with one string argument: which will be used as the actual name of the
159 159 resulting magic::
160 160
161 161 @deco('bar')
162 162 def foo(...)
163 163
164 164 will create a {1} magic named `bar`.
165 165
166 166 To register a class magic use ``Interactiveshell.register_magic(class or instance)``.
167 167 """
168 168
169 169 # These two are decorator factories. While they are conceptually very similar,
170 170 # there are enough differences in the details that it's simpler to have them
171 171 # written as completely standalone functions rather than trying to share code
172 172 # and make a single one with convoluted logic.
173 173
174 174 def _method_magic_marker(magic_kind):
175 175 """Decorator factory for methods in Magics subclasses.
176 176 """
177 177
178 178 validate_type(magic_kind)
179 179
180 180 # This is a closure to capture the magic_kind. We could also use a class,
181 181 # but it's overkill for just that one bit of state.
182 182 def magic_deco(arg):
183 183 if callable(arg):
184 184 # "Naked" decorator call (just @foo, no args)
185 185 func = arg
186 186 name = func.__name__
187 187 retval = arg
188 188 record_magic(magics, magic_kind, name, name)
189 189 elif isinstance(arg, str):
190 190 # Decorator called with arguments (@foo('bar'))
191 191 name = arg
192 192 def mark(func, *a, **kw):
193 193 record_magic(magics, magic_kind, name, func.__name__)
194 194 return func
195 195 retval = mark
196 196 else:
197 197 raise TypeError("Decorator can only be called with "
198 198 "string or function")
199 199 return retval
200 200
201 201 # Ensure the resulting decorator has a usable docstring
202 202 magic_deco.__doc__ = _docstring_template.format('method', magic_kind)
203 203 return magic_deco
204 204
205 205
206 206 def _function_magic_marker(magic_kind):
207 207 """Decorator factory for standalone functions.
208 208 """
209 209 validate_type(magic_kind)
210 210
211 211 # This is a closure to capture the magic_kind. We could also use a class,
212 212 # but it's overkill for just that one bit of state.
213 213 def magic_deco(arg):
214 214 # Find get_ipython() in the caller's namespace
215 215 caller = sys._getframe(1)
216 216 for ns in ['f_locals', 'f_globals', 'f_builtins']:
217 217 get_ipython = getattr(caller, ns).get('get_ipython')
218 218 if get_ipython is not None:
219 219 break
220 220 else:
221 221 raise NameError('Decorator can only run in context where '
222 222 '`get_ipython` exists')
223 223
224 224 ip = get_ipython()
225 225
226 226 if callable(arg):
227 227 # "Naked" decorator call (just @foo, no args)
228 228 func = arg
229 229 name = func.__name__
230 230 ip.register_magic_function(func, magic_kind, name)
231 231 retval = arg
232 232 elif isinstance(arg, str):
233 233 # Decorator called with arguments (@foo('bar'))
234 234 name = arg
235 235 def mark(func, *a, **kw):
236 236 ip.register_magic_function(func, magic_kind, name)
237 237 return func
238 238 retval = mark
239 239 else:
240 240 raise TypeError("Decorator can only be called with "
241 241 "string or function")
242 242 return retval
243 243
244 244 # Ensure the resulting decorator has a usable docstring
245 245 ds = _docstring_template.format('function', magic_kind)
246 246
247 247 ds += dedent("""
248 248 Note: this decorator can only be used in a context where IPython is already
249 249 active, so that the `get_ipython()` call succeeds. You can therefore use
250 250 it in your startup files loaded after IPython initializes, but *not* in the
251 251 IPython configuration file itself, which is executed before IPython is
252 252 fully up and running. Any file located in the `startup` subdirectory of
253 253 your configuration profile will be OK in this sense.
254 254 """)
255 255
256 256 magic_deco.__doc__ = ds
257 257 return magic_deco
258 258
259 259
260 MAGIC_NO_VAR_EXPAND_ATTR = '_ipython_magic_no_var_expand'
261 MAGIC_OUTPUT_CAN_BE_DISABLED = '_ipython_magic_output_can_be_disabled'
260 MAGIC_NO_VAR_EXPAND_ATTR = "_ipython_magic_no_var_expand"
261 MAGIC_OUTPUT_CAN_BE_DISABLED = "_ipython_magic_output_can_be_disabled"
262 262
263 263
264 264 def no_var_expand(magic_func):
265 265 """Mark a magic function as not needing variable expansion
266 266
267 267 By default, IPython interprets `{a}` or `$a` in the line passed to magics
268 268 as variables that should be interpolated from the interactive namespace
269 269 before passing the line to the magic function.
270 270 This is not always desirable, e.g. when the magic executes Python code
271 271 (%timeit, %time, etc.).
272 272 Decorate magics with `@no_var_expand` to opt-out of variable expansion.
273 273
274 274 .. versionadded:: 7.3
275 275 """
276 276 setattr(magic_func, MAGIC_NO_VAR_EXPAND_ATTR, True)
277 277 return magic_func
278 278
279 279
280 280 def output_can_be_disabled(magic_func):
281 281 """Mark a magic function so its output may be disabled.
282 282
283 283 The output is disabled if the Python expression used as a parameter of
284 284 the magic ends in a semicolon, not counting a Python comment that can
285 285 follows it.
286 286 """
287 287 setattr(magic_func, MAGIC_OUTPUT_CAN_BE_DISABLED, True)
288 288 return magic_func
289 289
290 290 # Create the actual decorators for public use
291 291
292 292 # These three are used to decorate methods in class definitions
293 293 line_magic = _method_magic_marker('line')
294 294 cell_magic = _method_magic_marker('cell')
295 295 line_cell_magic = _method_magic_marker('line_cell')
296 296
297 297 # These three decorate standalone functions and perform the decoration
298 298 # immediately. They can only run where get_ipython() works
299 299 register_line_magic = _function_magic_marker('line')
300 300 register_cell_magic = _function_magic_marker('cell')
301 301 register_line_cell_magic = _function_magic_marker('line_cell')
302 302
303 303 #-----------------------------------------------------------------------------
304 304 # Core Magic classes
305 305 #-----------------------------------------------------------------------------
306 306
307 307 class MagicsManager(Configurable):
308 308 """Object that handles all magic-related functionality for IPython.
309 309 """
310 310 # Non-configurable class attributes
311 311
312 312 # A two-level dict, first keyed by magic type, then by magic function, and
313 313 # holding the actual callable object as value. This is the dict used for
314 314 # magic function dispatch
315 315 magics = Dict()
316 316 lazy_magics = Dict(
317 317 help="""
318 318 Mapping from magic names to modules to load.
319 319
320 320 This can be used in IPython/IPykernel configuration to declare lazy magics
321 321 that will only be imported/registered on first use.
322 322
323 323 For example::
324 324
325 325 c.MagicsManager.lazy_magics = {
326 326 "my_magic": "slow.to.import",
327 327 "my_other_magic": "also.slow",
328 328 }
329 329
330 330 On first invocation of `%my_magic`, `%%my_magic`, `%%my_other_magic` or
331 331 `%%my_other_magic`, the corresponding module will be loaded as an ipython
332 332 extensions as if you had previously done `%load_ext ipython`.
333 333
334 334 Magics names should be without percent(s) as magics can be both cell
335 335 and line magics.
336 336
337 337 Lazy loading happen relatively late in execution process, and
338 338 complex extensions that manipulate Python/IPython internal state or global state
339 339 might not support lazy loading.
340 340 """
341 341 ).tag(
342 342 config=True,
343 343 )
344 344
345 345 # A registry of the original objects that we've been given holding magics.
346 346 registry = Dict()
347 347
348 348 shell = Instance('IPython.core.interactiveshell.InteractiveShellABC', allow_none=True)
349 349
350 350 auto_magic = Bool(True, help=
351 351 "Automatically call line magics without requiring explicit % prefix"
352 352 ).tag(config=True)
353 353 @observe('auto_magic')
354 354 def _auto_magic_changed(self, change):
355 355 self.shell.automagic = change['new']
356 356
357 357 _auto_status = [
358 358 'Automagic is OFF, % prefix IS needed for line magics.',
359 359 'Automagic is ON, % prefix IS NOT needed for line magics.']
360 360
361 361 user_magics = Instance('IPython.core.magics.UserMagics', allow_none=True)
362 362
363 363 def __init__(self, shell=None, config=None, user_magics=None, **traits):
364 364
365 365 super(MagicsManager, self).__init__(shell=shell, config=config,
366 366 user_magics=user_magics, **traits)
367 367 self.magics = dict(line={}, cell={})
368 368 # Let's add the user_magics to the registry for uniformity, so *all*
369 369 # registered magic containers can be found there.
370 370 self.registry[user_magics.__class__.__name__] = user_magics
371 371
372 372 def auto_status(self):
373 373 """Return descriptive string with automagic status."""
374 374 return self._auto_status[self.auto_magic]
375 375
376 376 def lsmagic(self):
377 377 """Return a dict of currently available magic functions.
378 378
379 379 The return dict has the keys 'line' and 'cell', corresponding to the
380 380 two types of magics we support. Each value is a list of names.
381 381 """
382 382 return self.magics
383 383
384 384 def lsmagic_docs(self, brief=False, missing=''):
385 385 """Return dict of documentation of magic functions.
386 386
387 387 The return dict has the keys 'line' and 'cell', corresponding to the
388 388 two types of magics we support. Each value is a dict keyed by magic
389 389 name whose value is the function docstring. If a docstring is
390 390 unavailable, the value of `missing` is used instead.
391 391
392 392 If brief is True, only the first line of each docstring will be returned.
393 393 """
394 394 docs = {}
395 395 for m_type in self.magics:
396 396 m_docs = {}
397 397 for m_name, m_func in self.magics[m_type].items():
398 398 if m_func.__doc__:
399 399 if brief:
400 400 m_docs[m_name] = m_func.__doc__.split('\n', 1)[0]
401 401 else:
402 402 m_docs[m_name] = m_func.__doc__.rstrip()
403 403 else:
404 404 m_docs[m_name] = missing
405 405 docs[m_type] = m_docs
406 406 return docs
407 407
408 408 def register_lazy(self, name: str, fully_qualified_name: str):
409 409 """
410 410 Lazily register a magic via an extension.
411 411
412 412
413 413 Parameters
414 414 ----------
415 415 name : str
416 416 Name of the magic you wish to register.
417 417 fully_qualified_name :
418 418 Fully qualified name of the module/submodule that should be loaded
419 419 as an extensions when the magic is first called.
420 420 It is assumed that loading this extensions will register the given
421 421 magic.
422 422 """
423 423
424 424 self.lazy_magics[name] = fully_qualified_name
425 425
426 426 def register(self, *magic_objects):
427 427 """Register one or more instances of Magics.
428 428
429 429 Take one or more classes or instances of classes that subclass the main
430 430 `core.Magic` class, and register them with IPython to use the magic
431 431 functions they provide. The registration process will then ensure that
432 432 any methods that have decorated to provide line and/or cell magics will
433 433 be recognized with the `%x`/`%%x` syntax as a line/cell magic
434 434 respectively.
435 435
436 436 If classes are given, they will be instantiated with the default
437 437 constructor. If your classes need a custom constructor, you should
438 438 instanitate them first and pass the instance.
439 439
440 440 The provided arguments can be an arbitrary mix of classes and instances.
441 441
442 442 Parameters
443 443 ----------
444 444 *magic_objects : one or more classes or instances
445 445 """
446 446 # Start by validating them to ensure they have all had their magic
447 447 # methods registered at the instance level
448 448 for m in magic_objects:
449 449 if not m.registered:
450 450 raise ValueError("Class of magics %r was constructed without "
451 451 "the @register_magics class decorator")
452 452 if isinstance(m, type):
453 453 # If we're given an uninstantiated class
454 454 m = m(shell=self.shell)
455 455
456 456 # Now that we have an instance, we can register it and update the
457 457 # table of callables
458 458 self.registry[m.__class__.__name__] = m
459 459 for mtype in magic_kinds:
460 460 self.magics[mtype].update(m.magics[mtype])
461 461
462 462 def register_function(self, func, magic_kind='line', magic_name=None):
463 463 """Expose a standalone function as magic function for IPython.
464 464
465 465 This will create an IPython magic (line, cell or both) from a
466 466 standalone function. The functions should have the following
467 467 signatures:
468 468
469 469 * For line magics: `def f(line)`
470 470 * For cell magics: `def f(line, cell)`
471 471 * For a function that does both: `def f(line, cell=None)`
472 472
473 473 In the latter case, the function will be called with `cell==None` when
474 474 invoked as `%f`, and with cell as a string when invoked as `%%f`.
475 475
476 476 Parameters
477 477 ----------
478 478 func : callable
479 479 Function to be registered as a magic.
480 480 magic_kind : str
481 481 Kind of magic, one of 'line', 'cell' or 'line_cell'
482 482 magic_name : optional str
483 483 If given, the name the magic will have in the IPython namespace. By
484 484 default, the name of the function itself is used.
485 485 """
486 486
487 487 # Create the new method in the user_magics and register it in the
488 488 # global table
489 489 validate_type(magic_kind)
490 490 magic_name = func.__name__ if magic_name is None else magic_name
491 491 setattr(self.user_magics, magic_name, func)
492 492 record_magic(self.magics, magic_kind, magic_name, func)
493 493
494 494 def register_alias(self, alias_name, magic_name, magic_kind='line', magic_params=None):
495 495 """Register an alias to a magic function.
496 496
497 497 The alias is an instance of :class:`MagicAlias`, which holds the
498 498 name and kind of the magic it should call. Binding is done at
499 499 call time, so if the underlying magic function is changed the alias
500 500 will call the new function.
501 501
502 502 Parameters
503 503 ----------
504 504 alias_name : str
505 505 The name of the magic to be registered.
506 506 magic_name : str
507 507 The name of an existing magic.
508 508 magic_kind : str
509 509 Kind of magic, one of 'line' or 'cell'
510 510 """
511 511
512 512 # `validate_type` is too permissive, as it allows 'line_cell'
513 513 # which we do not handle.
514 514 if magic_kind not in magic_kinds:
515 515 raise ValueError('magic_kind must be one of %s, %s given' %
516 516 magic_kinds, magic_kind)
517 517
518 518 alias = MagicAlias(self.shell, magic_name, magic_kind, magic_params)
519 519 setattr(self.user_magics, alias_name, alias)
520 520 record_magic(self.magics, magic_kind, alias_name, alias)
521 521
522 522 # Key base class that provides the central functionality for magics.
523 523
524 524
525 525 class Magics(Configurable):
526 526 """Base class for implementing magic functions.
527 527
528 528 Shell functions which can be reached as %function_name. All magic
529 529 functions should accept a string, which they can parse for their own
530 530 needs. This can make some functions easier to type, eg `%cd ../`
531 531 vs. `%cd("../")`
532 532
533 533 Classes providing magic functions need to subclass this class, and they
534 534 MUST:
535 535
536 536 - Use the method decorators `@line_magic` and `@cell_magic` to decorate
537 537 individual methods as magic functions, AND
538 538
539 539 - Use the class decorator `@magics_class` to ensure that the magic
540 540 methods are properly registered at the instance level upon instance
541 541 initialization.
542 542
543 543 See :mod:`magic_functions` for examples of actual implementation classes.
544 544 """
545 545 # Dict holding all command-line options for each magic.
546 546 options_table = None
547 547 # Dict for the mapping of magic names to methods, set by class decorator
548 548 magics = None
549 549 # Flag to check that the class decorator was properly applied
550 550 registered = False
551 551 # Instance of IPython shell
552 552 shell = None
553 553
554 554 def __init__(self, shell=None, **kwargs):
555 555 if not(self.__class__.registered):
556 556 raise ValueError('Magics subclass without registration - '
557 557 'did you forget to apply @magics_class?')
558 558 if shell is not None:
559 559 if hasattr(shell, 'configurables'):
560 560 shell.configurables.append(self)
561 561 if hasattr(shell, 'config'):
562 562 kwargs.setdefault('parent', shell)
563 563
564 564 self.shell = shell
565 565 self.options_table = {}
566 566 # The method decorators are run when the instance doesn't exist yet, so
567 567 # they can only record the names of the methods they are supposed to
568 568 # grab. Only now, that the instance exists, can we create the proper
569 569 # mapping to bound methods. So we read the info off the original names
570 570 # table and replace each method name by the actual bound method.
571 571 # But we mustn't clobber the *class* mapping, in case of multiple instances.
572 572 class_magics = self.magics
573 573 self.magics = {}
574 574 for mtype in magic_kinds:
575 575 tab = self.magics[mtype] = {}
576 576 cls_tab = class_magics[mtype]
577 577 for magic_name, meth_name in cls_tab.items():
578 578 if isinstance(meth_name, str):
579 579 # it's a method name, grab it
580 580 tab[magic_name] = getattr(self, meth_name)
581 581 else:
582 582 # it's the real thing
583 583 tab[magic_name] = meth_name
584 584 # Configurable **needs** to be initiated at the end or the config
585 585 # magics get screwed up.
586 586 super(Magics, self).__init__(**kwargs)
587 587
588 588 def arg_err(self,func):
589 589 """Print docstring if incorrect arguments were passed"""
590 590 print('Error in arguments:')
591 591 print(oinspect.getdoc(func))
592 592
593 593 def format_latex(self, strng):
594 594 """Format a string for latex inclusion."""
595 595
596 596 # Characters that need to be escaped for latex:
597 597 escape_re = re.compile(r'(%|_|\$|#|&)',re.MULTILINE)
598 598 # Magic command names as headers:
599 599 cmd_name_re = re.compile(r'^(%s.*?):' % ESC_MAGIC,
600 600 re.MULTILINE)
601 601 # Magic commands
602 602 cmd_re = re.compile(r'(?P<cmd>%s.+?\b)(?!\}\}:)' % ESC_MAGIC,
603 603 re.MULTILINE)
604 604 # Paragraph continue
605 605 par_re = re.compile(r'\\$',re.MULTILINE)
606 606
607 607 # The "\n" symbol
608 608 newline_re = re.compile(r'\\n')
609 609
610 610 # Now build the string for output:
611 611 #strng = cmd_name_re.sub(r'\n\\texttt{\\textsl{\\large \1}}:',strng)
612 612 strng = cmd_name_re.sub(r'\n\\bigskip\n\\texttt{\\textbf{ \1}}:',
613 613 strng)
614 614 strng = cmd_re.sub(r'\\texttt{\g<cmd>}',strng)
615 615 strng = par_re.sub(r'\\\\',strng)
616 616 strng = escape_re.sub(r'\\\1',strng)
617 617 strng = newline_re.sub(r'\\textbackslash{}n',strng)
618 618 return strng
619 619
620 620 def parse_options(self, arg_str, opt_str, *long_opts, **kw):
621 621 """Parse options passed to an argument string.
622 622
623 623 The interface is similar to that of :func:`getopt.getopt`, but it
624 624 returns a :class:`~IPython.utils.struct.Struct` with the options as keys
625 625 and the stripped argument string still as a string.
626 626
627 627 arg_str is quoted as a true sys.argv vector by using shlex.split.
628 628 This allows us to easily expand variables, glob files, quote
629 629 arguments, etc.
630 630
631 631 Parameters
632 632 ----------
633 633 arg_str : str
634 634 The arguments to parse.
635 635 opt_str : str
636 636 The options specification.
637 637 mode : str, default 'string'
638 638 If given as 'list', the argument string is returned as a list (split
639 639 on whitespace) instead of a string.
640 640 list_all : bool, default False
641 641 Put all option values in lists. Normally only options
642 642 appearing more than once are put in a list.
643 643 posix : bool, default True
644 644 Whether to split the input line in POSIX mode or not, as per the
645 645 conventions outlined in the :mod:`shlex` module from the standard
646 646 library.
647 647 """
648 648
649 649 # inject default options at the beginning of the input line
650 650 caller = sys._getframe(1).f_code.co_name
651 651 arg_str = '%s %s' % (self.options_table.get(caller,''),arg_str)
652 652
653 653 mode = kw.get('mode','string')
654 654 if mode not in ['string','list']:
655 655 raise ValueError('incorrect mode given: %s' % mode)
656 656 # Get options
657 657 list_all = kw.get('list_all',0)
658 658 posix = kw.get('posix', os.name == 'posix')
659 659 strict = kw.get('strict', True)
660 660
661 661 preserve_non_opts = kw.get("preserve_non_opts", False)
662 662 remainder_arg_str = arg_str
663 663
664 664 # Check if we have more than one argument to warrant extra processing:
665 665 odict = {} # Dictionary with options
666 666 args = arg_str.split()
667 667 if len(args) >= 1:
668 668 # If the list of inputs only has 0 or 1 thing in it, there's no
669 669 # need to look for options
670 670 argv = arg_split(arg_str, posix, strict)
671 671 # Do regular option processing
672 672 try:
673 673 opts,args = getopt(argv, opt_str, long_opts)
674 674 except GetoptError as e:
675 675 raise UsageError(
676 676 '%s ( allowed: "%s" %s)' % (e.msg, opt_str, " ".join(long_opts))
677 677 ) from e
678 678 for o, a in opts:
679 679 if mode == "string" and preserve_non_opts:
680 680 # remove option-parts from the original args-string and preserve remaining-part.
681 681 # This relies on the arg_split(...) and getopt(...)'s impl spec, that the parsed options are
682 682 # returned in the original order.
683 683 remainder_arg_str = remainder_arg_str.replace(o, "", 1).replace(
684 684 a, "", 1
685 685 )
686 686 if o.startswith("--"):
687 687 o = o[2:]
688 688 else:
689 689 o = o[1:]
690 690 try:
691 691 odict[o].append(a)
692 692 except AttributeError:
693 693 odict[o] = [odict[o],a]
694 694 except KeyError:
695 695 if list_all:
696 696 odict[o] = [a]
697 697 else:
698 698 odict[o] = a
699 699
700 700 # Prepare opts,args for return
701 701 opts = Struct(odict)
702 702 if mode == 'string':
703 703 if preserve_non_opts:
704 704 args = remainder_arg_str.lstrip()
705 705 else:
706 706 args = " ".join(args)
707 707
708 708 return opts,args
709 709
710 710 def default_option(self, fn, optstr):
711 711 """Make an entry in the options_table for fn, with value optstr"""
712 712
713 713 if fn not in self.lsmagic():
714 714 error("%s is not a magic function" % fn)
715 715 self.options_table[fn] = optstr
716 716
717 717
718 718 class MagicAlias(object):
719 719 """An alias to another magic function.
720 720
721 721 An alias is determined by its magic name and magic kind. Lookup
722 722 is done at call time, so if the underlying magic changes the alias
723 723 will call the new function.
724 724
725 725 Use the :meth:`MagicsManager.register_alias` method or the
726 726 `%alias_magic` magic function to create and register a new alias.
727 727 """
728 728 def __init__(self, shell, magic_name, magic_kind, magic_params=None):
729 729 self.shell = shell
730 730 self.magic_name = magic_name
731 731 self.magic_params = magic_params
732 732 self.magic_kind = magic_kind
733 733
734 734 self.pretty_target = '%s%s' % (magic_escapes[self.magic_kind], self.magic_name)
735 735 self.__doc__ = "Alias for `%s`." % self.pretty_target
736 736
737 737 self._in_call = False
738 738
739 739 def __call__(self, *args, **kwargs):
740 740 """Call the magic alias."""
741 741 fn = self.shell.find_magic(self.magic_name, self.magic_kind)
742 742 if fn is None:
743 743 raise UsageError("Magic `%s` not found." % self.pretty_target)
744 744
745 745 # Protect against infinite recursion.
746 746 if self._in_call:
747 747 raise UsageError("Infinite recursion detected; "
748 748 "magic aliases cannot call themselves.")
749 749 self._in_call = True
750 750 try:
751 751 if self.magic_params:
752 752 args_list = list(args)
753 753 args_list[0] = self.magic_params + " " + args[0]
754 754 args = tuple(args_list)
755 755 return fn(*args, **kwargs)
756 756 finally:
757 757 self._in_call = False
General Comments 0
You need to be logged in to leave comments. Login now