Important

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).

Module: core.prefilter

Prefiltering components.

Prefilters transform user input before it is exec’d by Python. These transforms are used to implement additional syntax such as !ls and %magic.

16 Classes

class IPython.core.prefilter.PrefilterError

Bases: Exception

class IPython.core.prefilter.PrefilterManager(**kwargs: Any)

Bases: Configurable

Main prefilter component.

The IPython prefilter is run on all user input before it is run. The prefilter consumes lines of input and produces transformed lines of input.

The implementation consists of two phases:

  1. Transformers

  2. Checkers and handlers

Over time, we plan on deprecating the checkers and handlers and doing everything in the transformers.

The transformers are instances of PrefilterTransformer and have a single method transform() that takes a line and returns a transformed line. The transformation can be accomplished using any tool, but our current ones use regular expressions for speed.

After all the transformers have been run, the line is fed to the checkers, which are instances of PrefilterChecker. The line is passed to the check() method, which either returns None or a PrefilterHandler instance. If None is returned, the other checkers are tried. If an PrefilterHandler instance is returned, the line is passed to the handle() method of the returned handler and no further checkers are tried.

Both transformers and checkers have a priority attribute, that determines the order in which they are called. Smaller priorities are tried first.

Both transformers and checkers also have enabled attribute, which is a boolean that determines if the instance is used.

Users or developers can change the priority or enabled attribute of transformers or checkers, but they must call the sort_checkers() or sort_transformers() method after changing the priority.

__init__(shell=None, **kwargs)

Create a configurable given a config config.

Parameters:
  • config (Config) – If this is empty, default values are used. If config is a Config instance, it will be used to configure the instance.

  • parent (Configurable instance, optional) – The parent Configurable instance of this object.

Notes

Subclasses of Configurable must call the __init__() method of Configurable before doing anything else and using super():

class MyConfigurable(Configurable):
    def __init__(self, config=None):
        super(MyConfigurable, self).__init__(config=config)
        # Then any other code you need to finish initialization.

This ensures that instances will be configured properly.

property checkers

Return a list of checkers, sorted by priority.

find_handler(line_info)

Find a handler for the line_info by trying checkers.

get_handler_by_esc(esc_str)

Get a handler by its escape string.

get_handler_by_name(name)

Get a handler by its name.

property handlers

Return a dict of all the handlers.

init_checkers()

Create the default checkers.

init_handlers()

Create the default handlers.

prefilter_line(line, continue_prompt=False)

Prefilter a single input line as text.

This method prefilters a single line of text by calling the transformers and then the checkers/handlers.

prefilter_line_info(line_info)

Prefilter a line that has been converted to a LineInfo object.

This implements the checker/handler part of the prefilter pipe.

prefilter_lines(lines, continue_prompt=False)

Prefilter multiple input lines of text.

This is the main entry point for prefiltering multiple lines of input. This simply calls prefilter_line() for each line of input.

This covers cases where there are multiple lines in the user entry, which is the case when the user goes back to a multiline history entry and presses enter.

register_checker(checker)

Register a checker instance.

register_handler(name, handler, esc_strings)

Register a handler instance by name with esc_strings.

register_transformer(transformer)

Register a transformer instance.

sort_checkers()

Sort the checkers by priority.

This must be called after the priority of a checker is changed. The register_checker() method calls this automatically.

sort_transformers()

Sort the transformers by priority.

This must be called after the priority of a transformer is changed. The register_transformer() method calls this automatically.

transform_line(line, continue_prompt)

Calls the enabled transformers in order of increasing priority.

property transformers

Return a list of checkers, sorted by priority.

unregister_checker(checker)

Unregister a checker instance.

unregister_handler(name, handler, esc_strings)

Unregister a handler instance by name with esc_strings.

unregister_transformer(transformer)

Unregister a transformer instance.

class IPython.core.prefilter.PrefilterTransformer(**kwargs: Any)

Bases: Configurable

Transform a line of user input.

__init__(shell=None, prefilter_manager=None, **kwargs)

Create a configurable given a config config.

Parameters:
  • config (Config) – If this is empty, default values are used. If config is a Config instance, it will be used to configure the instance.

  • parent (Configurable instance, optional) – The parent Configurable instance of this object.

Notes

Subclasses of Configurable must call the __init__() method of Configurable before doing anything else and using super():

class MyConfigurable(Configurable):
    def __init__(self, config=None):
        super(MyConfigurable, self).__init__(config=config)
        # Then any other code you need to finish initialization.

This ensures that instances will be configured properly.

transform(line, continue_prompt)

Transform a line, returning the new one.

class IPython.core.prefilter.PrefilterChecker(**kwargs: Any)

Bases: Configurable

Inspect an input line and return a handler for that line.

__init__(shell=None, prefilter_manager=None, **kwargs)

Create a configurable given a config config.

Parameters:
  • config (Config) – If this is empty, default values are used. If config is a Config instance, it will be used to configure the instance.

  • parent (Configurable instance, optional) – The parent Configurable instance of this object.

Notes

Subclasses of Configurable must call the __init__() method of Configurable before doing anything else and using super():

class MyConfigurable(Configurable):
    def __init__(self, config=None):
        super(MyConfigurable, self).__init__(config=config)
        # Then any other code you need to finish initialization.

This ensures that instances will be configured properly.

check(line_info)

Inspect line_info and return a handler instance or None.

class IPython.core.prefilter.EmacsChecker(**kwargs: Any)

Bases: PrefilterChecker

check(line_info)

Emacs ipython-mode tags certain input lines.

class IPython.core.prefilter.MacroChecker(**kwargs: Any)

Bases: PrefilterChecker

check(line_info)

Inspect line_info and return a handler instance or None.

class IPython.core.prefilter.IPyAutocallChecker(**kwargs: Any)

Bases: PrefilterChecker

check(line_info)

Instances of IPyAutocall in user_ns get autocalled immediately

class IPython.core.prefilter.AssignmentChecker(**kwargs: Any)

Bases: PrefilterChecker

check(line_info)

Check to see if user is assigning to a var for the first time, in which case we want to avoid any sort of automagic / autocall games.

This allows users to assign to either alias or magic names true python variables (the magic/alias systems always take second seat to true python code). E.g. ls=’hi’, or ls,that=1,2

class IPython.core.prefilter.AutoMagicChecker(**kwargs: Any)

Bases: PrefilterChecker

check(line_info)

If the ifun is magic, and automagic is on, run it. Note: normal, non-auto magic would already have been triggered via ‘%’ in check_esc_chars. This just checks for automagic. Also, before triggering the magic handler, make sure that there is nothing in the user namespace which could shadow it.

class IPython.core.prefilter.PythonOpsChecker(**kwargs: Any)

Bases: PrefilterChecker

check(line_info)

If the ‘rest’ of the line begins with a function call or pretty much any python operator, we should simply execute the line (regardless of whether or not there’s a possible autocall expansion). This avoids spurious (and very confusing) geattr() accesses.

class IPython.core.prefilter.AutocallChecker(**kwargs: Any)

Bases: PrefilterChecker

check(line_info)

Check if the initial word/function is callable and autocall is on.

exclude_regexp

RegExp to exclude strings with this start from autocalling.

function_name_regexp

RegExp to identify potential function names.

class IPython.core.prefilter.PrefilterHandler(**kwargs: Any)

Bases: Configurable

__init__(shell=None, prefilter_manager=None, **kwargs)

Create a configurable given a config config.

Parameters:
  • config (Config) – If this is empty, default values are used. If config is a Config instance, it will be used to configure the instance.

  • parent (Configurable instance, optional) – The parent Configurable instance of this object.

Notes

Subclasses of Configurable must call the __init__() method of Configurable before doing anything else and using super():

class MyConfigurable(Configurable):
    def __init__(self, config=None):
        super(MyConfigurable, self).__init__(config=config)
        # Then any other code you need to finish initialization.

This ensures that instances will be configured properly.

handle(line_info)

Handle normal input lines. Use as a template for handlers.

class IPython.core.prefilter.MacroHandler(**kwargs: Any)

Bases: PrefilterHandler

handle(line_info)

Handle normal input lines. Use as a template for handlers.

class IPython.core.prefilter.MagicHandler(**kwargs: Any)

Bases: PrefilterHandler

handle(line_info)

Execute magic functions.

class IPython.core.prefilter.AutoHandler(**kwargs: Any)

Bases: PrefilterHandler

handle(line_info)

Handle lines which can be auto-executed, quoting if requested.

class IPython.core.prefilter.EmacsHandler(**kwargs: Any)

Bases: PrefilterHandler

handle(line_info)

Handle input lines marked by python-mode.

1 Function

IPython.core.prefilter.is_shadowed(identifier, ip)

Is the given identifier defined in one of the namespaces which shadow the alias and magic namespaces? Note that an identifier is different than ifun, because it can not contain a ‘.’ character.