core.magic

Module: core.magic

Inheritance diagram for IPython.core.magic:

Magic functions for InteractiveShell.

Classes

Bunch

class IPython.core.magic.Bunch

Magics

class IPython.core.magic.Magics(shell)

Bases: object

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 %cd ../ vs. %cd(”../”)

Classes providing magic functions need to subclass this class, and they MUST:

• Use the method decorators @line_magic and @cell_magic to decorate

individual methods as magic functions, AND

• Use the class decorator @magics_class to ensure that the magic

methods are properly registered at the instance level upon instance initialization.

See magic_functions for examples of actual implementation classes.

__init__(shell)

arg_err(func)

Print docstring if incorrect arguments were passed

default_option(fn, optstr)

Make an entry in the options_table for fn, with value optstr

format_latex(strng)

Format a string for latex inclusion.

magics = None

options_table = None

parse_options(arg_str, opt_str, *long_opts, **kw)

Parse options passed to an argument string.

The interface is similar to that of getopt(), but it returns back a Struct with 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.

Options:

-mode: default ‘string’. If given as ‘list’, the argument string is returned as a list (split on whitespace) instead of a string.

-list_all: put all option values in lists. Normally only options appearing more than once are put in a list.

-posix (True): whether to split the input line in POSIX mode or not, as per the conventions outlined in the shlex module from the standard library.

registered = False

shell = None

MagicsManager

class IPython.core.magic.MagicsManager(shell=None, config=None, user_magics=None, **traits)

Bases: IPython.config.configurable.Configurable

Object that handles all magic-related functionality for IPython.

__init__(shell=None, config=None, user_magics=None, **traits)

auto_magic

A boolean (True, False) trait.

auto_status()

Return descriptive string with automagic status.

classmethod class_config_section()

Get the config class config section

classmethod class_get_help(inst=None)

Get the help string for this class in ReST format.

If inst is given, it’s current trait values will be used in place of class defaults.

classmethod class_get_trait_help(trait, inst=None)

Get the help string for a single trait.

If inst is given, it’s current trait values will be used in place of the class default.

classmethod class_print_help(inst=None)

Get the help string for a single trait and print it.

classmethod class_trait_names(**metadata)

Get a list of all the names of this classes traits.

This method is just like the trait_names() method, but is unbound.

classmethod class_traits(**metadata)

Get a list of all the traits of this class.

This method is just like the traits() method, but is unbound.

The TraitTypes returned don’t know anything about the values that the various HasTrait’s instances are holding.

This follows the same algorithm as traits does and does not allow for any simple way of specifying merely that a metadata name exists, but has any value. This is because get_metadata returns None if a metadata key doesn’t exist.

config

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

created = None

define_magic(name, func)

[Deprecated] Expose own function as magic function for IPython.

Example:

def foo_impl(self, parameter_s=''):
    'My very own magic!. (Use docstrings, IPython reads them).'
    print 'Magic function. Passed parameter is between < >:'
    print '<%s>' % parameter_s
    print 'The self object is:', self

ip.define_magic('foo',foo_impl)

lsmagic()

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.

lsmagic_docs(brief=False, missing='')

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 missing is used instead.

If brief is True, only the first line of each docstring will be returned.

lsmagic_info()

magics

An instance of a Python dict.

on_trait_change(handler, name=None, remove=False)

Setup a handler to be called when a trait changes.

This is used to setup dynamic notifications of trait changes.

Static handlers can be created by creating methods on a HasTraits subclass with the naming convention ‘_[traitname]_changed’. Thus, to create static handler for the trait ‘a’, create the method _a_changed(self, name, old, new) (fewer arguments can be used, see below).

Parameters :

handler : callable

A callable that is called when a trait changes. Its signature can be handler(), handler(name), handler(name, new) or handler(name, old, new).

name : list, str, None

If None, the handler will apply to all traits. If a list of str, handler will apply to all names in the list. If a str, the handler will apply just to that name.

remove : bool

If False (the default), then install the handler. If True then unintall it.

register(*magic_objects)

Register one or more instances of Magics.

Take one or more classes or instances of classes that subclass the main core.Magic class, 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 %x/%%x syntax 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_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: def f(line)
• 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==None when invoked as %f, and with cell as a string when invoked as %%f.

Parameters :

func : callable

Function to be registered as a magic.

magic_kind : str

Kind of magic, one of ‘line’, ‘cell’ or ‘line_cell’

magic_name : optional str

If given, the name the magic will have in the IPython namespace. By default, the name of the function itself is used.

registry

An instance of a Python dict.

shell

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

trait_metadata(traitname, key)

Get metadata values for trait by key.

trait_names(**metadata)

Get a list of all the names of this classes traits.

traits(**metadata)

Get a list of all the traits of this class.

The TraitTypes returned don’t know anything about the values that the various HasTrait’s instances are holding.

This follows the same algorithm as traits does and does not allow for any simple way of specifying merely that a metadata name exists, but has any value. This is because get_metadata returns None if a metadata key doesn’t exist.

update_config(config)

Fire the traits events when the config is updated.

user_magics

A trait whose value must be an instance of a specified class.

The value can also be an instance of a subclass of the specified class.

Functions

IPython.core.magic.compress_dhist(dh)

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.

IPython.core.magic.magics_class(cls)

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.

IPython.core.magic.needs_local_scope(func)

Decorator to mark magic functions which need to local scope to run.

IPython.core.magic.on_off(tag)

Return an ON/OFF string for a 1/0 input. Simple utility function.

IPython.core.magic.record_magic(dct, magic_kind, magic_name, func)

Utility function to store a function as a magic of a specific kind.

Parameters :

dct : dict

A dictionary with ‘line’ and ‘cell’ subdicts.

magic_kind : str

Kind of magic to be stored.

magic_name : str

Key to store the magic as.

func : function

Callable object to store.

IPython.core.magic.validate_type(magic_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.