This documentation covers IPython versions 6.0 and higher. Beginning with version 6.0, IPython stopped supporting compatibility with Python versions lower than 3.3 including all versions of Python 2.7.
If you are looking for an IPython version compatible with Python 2.7, please use the IPython 5.x LTS release and refer to its documentation (LTS is the long term support release).
Magic functions for InteractiveShell.
MagicsManager(shell=None, config=None, user_magics=None, **traits)¶
Object that handles all magic-related functionality for IPython.
__init__(shell=None, config=None, user_magics=None, **traits)¶
Return descriptive string with automagic status.
Return a dict of currently available magic functions.
The return dict has the keys ‘line’ and ‘cell’, corresponding to the two types of magics we support. Each value is a list of names.
Return dict of documentation of magic functions.
The return dict has the keys ‘line’ and ‘cell’, corresponding to the two types of magics we support. Each value is a dict keyed by magic name whose value is the function docstring. If a docstring is unavailable, the value of
missingis used instead.
If brief is True, only the first line of each docstring will be returned.
Register one or more instances of Magics.
Take one or more classes or instances of classes that subclass the main
core.Magicclass, and register them with IPython to use the magic functions they provide. The registration process will then ensure that any methods that have decorated to provide line and/or cell magics will be recognized with the
%%xsyntax as a line/cell magic respectively.
If classes are given, they will be instantiated with the default constructor. If your classes need a custom constructor, you should instanitate them first and pass the instance.
The provided arguments can be an arbitrary mix of classes and instances.
Parameters: magic_objects (one or more classes or instances) –
register_alias(alias_name, magic_name, magic_kind='line', magic_params=None)¶
Register an alias to a magic function.
The alias is an instance of
MagicAlias, which holds the name and kind of the magic it should call. Binding is done at call time, so if the underlying magic function is changed the alias will call the new function.
register_function(func, magic_kind='line', magic_name=None)¶
Expose a standalone function as magic function for IPython.
This will create an IPython magic (line, cell or both) from a standalone function. The functions should have the following signatures:
- For line magics:
- For cell magics:
def f(line, cell)
- For a function that does both:
def f(line, cell=None)
In the latter case, the function will be called with
cell==Nonewhen invoked as
%f, and with cell as a string when invoked as
- For line magics:
Base class for implementing magic functions.
Shell functions which can be reached as %function_name. All magic functions should accept a string, which they can parse for their own needs. This can make some functions easier to type, eg
Classes providing magic functions need to subclass this class, and they MUST:
- Use the method decorators
@cell_magicto decorate individual methods as magic functions, AND
- Use the class decorator
@magics_classto ensure that the magic methods are properly registered at the instance level upon instance initialization.
magic_functionsfor examples of actual implementation classes.
Print docstring if incorrect arguments were passed
Make an entry in the options_table for fn, with value optstr
Format a string for latex inclusion.
parse_options(arg_str, opt_str, *long_opts, **kw)¶
Parse options passed to an argument string.
The interface is similar to that of
getopt.getopt(), but it returns a
Structwith the options as keys and the stripped argument string still as a string.
arg_str is quoted as a true sys.argv vector by using shlex.split. This allows us to easily expand variables, glob files, quote arguments, etc.
- arg_str (str) – The arguments to parse.
- opt_str (str) – The options specification.
- mode (str, default 'string') – If given as ‘list’, the argument string is returned as a list (split on whitespace) instead of a string.
- list_all (bool, default False) – Put all option values in lists. Normally only options appearing more than once are put in a list.
- posix (bool, default True) – Whether to split the input line in POSIX mode or not, as per the
conventions outlined in the
shlexmodule from the standard library.
- Use the method decorators
MagicAlias(shell, magic_name, magic_kind, magic_params=None)¶
An alias to another magic function.
An alias is determined by its magic name and magic kind. Lookup is done at call time, so if the underlying magic changes the alias will call the new function.
MagicsManager.register_alias()method or the
%alias_magicmagic function to create and register a new alias.
__init__(shell, magic_name, magic_kind, magic_params=None)¶
Return an ON/OFF string for a 1/0 input. Simple utility function.
Compress a directory history into a new one with at most 20 entries.
Return a new list made from the first and last 10 elements of dhist after removal of duplicates.
Decorator to mark magic functions which need to local scope to run.
Class decorator for all subclasses of the main Magics class.
Any class that subclasses Magics must also apply this decorator, to ensure that all the methods that have been decorated as line/cell magics get correctly registered in the class instance. This is necessary because when method decorators run, the class does not exist yet, so they temporarily store their information into a module global. Application of this class decorator copies that global data to the class instance and clears the global.
Obviously, this mechanism is not thread-safe, which means that the creation of subclasses of Magic should only be done in a single-thread context. Instantiation of the classes has no restrictions. Given that these classes are typically created at IPython startup time and before user application code becomes active, in practice this should not pose any problems.
record_magic(dct, magic_kind, magic_name, func)¶
Utility function to store a function as a magic of a specific kind.
Ensure that the given magic_kind is valid.
Check that the given magic_kind is one of the accepted spec types (stored in the global
magic_spec), raise ValueError otherwise.