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

Main IPython class.

8 Classes

class IPython.core.interactiveshell.PickleShareDB(root)

Bases: MutableMapping

The main ‘connection’ object for PickleShare database

__init__(root)

Return a db object that will manage the specied directory

Get a convenient link for accessing items

hcompress(hashroot)

Compress category ‘hashroot’, so hset is fast again

hget will fail if fast_only is True for compressed items (that were hset before hcompress).

hdict(hashroot)

Get all data contained in hashed category ‘hashroot’ as dict

hget(hashroot, key, default=<object object>, fast_only=True)

hashed get

hset(hashroot, key, value)

hashed set

keys(globpat=None)

All keys in DB, or all keys matching a glob

uncache(*items)

Removes all, or specified items from cache

Use this after reading a large amount of large objects to free up memory, when you won’t be needing the objects for a while.

waitget(key, maxwaittime=60)

Wait (poll) for a key to get a value

Will wait for maxwaittime seconds before raising a KeyError. The call exits normally if the key field in db gets a value within the timeout period.

Use this for synchronizing different processes or for ensuring that an unfortunately timed “db[‘key’] = newvalue” operation in another process (which causes all ‘get’ operation to cause a KeyError for the duration of pickling) won’t screw up your program logic.

class IPython.core.interactiveshell.ProvisionalWarning

Bases: DeprecationWarning

Warning class for unstable features

class IPython.core.interactiveshell.SpaceInInput

Bases: Exception

class IPython.core.interactiveshell.SeparateUnicode(default_value: str | Sentinel = ..., allow_none: Literal[False] = ..., read_only: bool | None = ..., help: str | None = ..., config: Any = ..., **kwargs: Any)
class IPython.core.interactiveshell.SeparateUnicode(default_value: str | Sentinel | None = ..., allow_none: Literal[True] = ..., read_only: bool | None = ..., help: str | None = ..., config: Any = ..., **kwargs: Any)

Bases: Unicode

A Unicode subclass to validate separate_in, separate_out, etc.

This is a Unicode based trait that converts ‘0’->’’ and '\\n'->'\n'.

class IPython.core.interactiveshell.ExecutionInfo(raw_cell, store_history, silent, shell_futures, cell_id)

Bases: object

The arguments used for a call to InteractiveShell.run_cell()

Stores information about what is going to happen.

__init__(raw_cell, store_history, silent, shell_futures, cell_id)
class IPython.core.interactiveshell.ExecutionResult(info)

Bases: object

The result of a call to InteractiveShell.run_cell()

Stores information about what took place.

__init__(info)
raise_error()

Reraises error if success is False, otherwise does nothing

class IPython.core.interactiveshell.InteractiveShell(**kwargs: Any)

Bases: SingletonConfigurable

An enhanced, interactive shell for Python.

__init__(ipython_dir=None, profile_dir=None, user_module=None, user_ns=None, custom_exceptions=((), 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 all_ns_refs

Get a list of references to all the namespace dictionaries in which IPython might store a user-created object.

Note that this does not include the displayhook, which also caches objects from the output.

ast_node_interactivity

‘all’, ‘last’, ‘last_expr’ or ‘none’, ‘last_expr_or_assign’ specifying which nodes should be run interactively (displaying output from expressions).

ast_transformers: List[NodeTransformer]

A list of ast.NodeTransformer subclass instances, which will be applied to user input before code is run.

atexit_operations()

This will be executed at the time of exit.

Cleanup operations and saving of persistent data that is done unconditionally by IPython should be performed here.

For things that may depend on startup flags or platform specifics (such as having readline or not), register a separate atexit function in the code that has the appropriate information, rather than trying to clutter

auto_rewrite_input(cmd)

Print to the screen the rewritten form of the user’s command.

This shows visual feedback by rewriting input lines that cause automatic calling to kick in, like:

/f x

into:

------> f(x)

after the user’s input prompt. This helps the user understand that the input line was transformed automatically by IPython.

autoawait

Automatically run await statement in the top level repl.

autocall

Make IPython automatically call any callable object even if you didn’t type explicit parentheses. For example, ‘str 43’ becomes ‘str(43)’ automatically. The value can be ‘0’ to disable the feature, ‘1’ for ‘smart’ autocall, where it is not applied if there are no more arguments on the line, and ‘2’ for ‘full’ autocall, where all callable objects are automatically called (even if no arguments are present).

autoindent

Autoindent IPython code entered interactively.

automagic

Enable magic commands to be called without the leading %.

banner1

The part of the banner to be printed before the profile

banner2

The part of the banner to be printed after the profile

cache_size

Set the size of the output cache. The default is 1000, you can change it permanently in your config file. Setting it to 0 completely disables the caching system, and the minimum value accepted is 3 (if you provide a value less than 3, it is reset to 0 and a warning is issued). This limit is defined because otherwise you’ll spend more time re-flushing a too small cache than working

property call_pdb

Control auto-activation of pdb at exceptions

check_complete(code: str) Tuple[str, str]

Return whether a block of code is ready to execute, or should be continued

Parameters:

code (string) – Python input code, which can be multiline.

Returns:

  • status (str) – One of ‘complete’, ‘incomplete’, or ‘invalid’ if source is not a prefix of valid code.

  • indent (str) – When status is ‘incomplete’, this is some whitespace to insert on the next line of the prompt.

clear_main_mod_cache()

Clear the cache of main modules.

Mainly for use by utilities like %reset.

Examples

In [15]: import IPython

In [16]: m = _ip.new_main_mod(IPython.__file__, ‘IPython’)

In [17]: len(_ip._main_mod_cache) > 0 Out[17]: True

In [18]: _ip.clear_main_mod_cache()

In [19]: len(_ip._main_mod_cache) == 0 Out[19]: True

color_info

Use colors for displaying information about objects. Because this information is passed through a pager (like ‘less’), and some pagers get confused with color codes, this capability can be turned off.

colors

Set the color scheme (NoColor, Neutral, Linux, or LightBG).

complete(text, line=None, cursor_pos=None)

Return the completed text and a list of completions.

Parameters:
  • text (string) – A string of text to be completed on. It can be given as empty and instead a line/position pair are given. In this case, the completer itself will split the line like readline does.

  • line (string, optional) – The complete line that text is part of.

  • cursor_pos (int, optional) – The position of the cursor on the input line.

Returns:

  • text (string) – The actual text that was completed.

  • matches (list) – A sorted list with all possible completions.

Notes

The optional arguments allow the completion to take more context into account, and are part of the low-level completion API.

This is a wrapper around the completion mechanism, similar to what readline does at the command line when the TAB key is hit. By exposing it as a method, it can be used by other non-readline environments (such as GUIs) for text completion.

Examples

In [1]: x = ‘hello’

In [2]: _ip.complete(‘x.l’) Out[2]: (‘x.l’, [‘x.ljust’, ‘x.lower’, ‘x.lstrip’])

debugger(force=False)

Call the pdb debugger.

Keywords:

  • force(False): by default, this routine checks the instance call_pdb flag and does not actually invoke the debugger if the flag is false. The ‘force’ option forces the debugger to activate even if the flag is false.

debugger_cls

alias of InterruptiblePdb

define_macro(name, themacro)

Define a new macro

Parameters:
  • name (str) – The name of the macro.

  • themacro (str or Macro) – The action to do upon invoking the macro. If a string, a new Macro object is created by passing the string to it.

del_var(varname, by_name=False)

Delete a variable from the various namespaces, so that, as far as possible, we’re not keeping any hidden references to it.

Parameters:
  • varname (str) – The name of the variable to delete.

  • by_name (bool) – If True, delete variables with the given name in each namespace. If False (default), find the variable in the user namespace, and delete references to it.

disable_failing_post_execute

Don’t call post-execute functions that have failed in the past.

display_page

If True, anything that would be passed to the pager will be displayed as regular output instead.

drop_by_id(variables)

Remove a dict of variables from the user namespace, if they are the same as the values in the dictionary.

This is intended for use by extensions: variables that they’ve added can be taken back out if they are unloaded, without removing any that the user has overwritten.

Parameters:

variables (dict) – A dictionary mapping object names (as strings) to the objects.

enable_html_pager

(Provisional API) enables html representation in mime bundles sent to pagers.

enable_matplotlib(gui=None)

Enable interactive matplotlib and inline figure support.

This takes the following steps:

  1. select the appropriate eventloop and matplotlib backend

  2. set up matplotlib for interactive use with that backend

  3. configure formatters for inline figure display

  4. enable the selected gui eventloop

Parameters:

gui (optional, string) – If given, dictates the choice of matplotlib GUI backend to use (should be one of IPython’s supported backends, ‘qt’, ‘osx’, ‘tk’, ‘gtk’, ‘wx’ or ‘inline’), otherwise we use the default chosen by matplotlib (as dictated by the matplotlib build-time options plus the user’s matplotlibrc configuration file). Note that not all backends make sense in all contexts, for example a terminal ipython can’t display figures inline.

enable_pylab(gui=None, import_all=True, welcome_message=False)

Activate pylab support at runtime.

This turns on support for matplotlib, preloads into the interactive namespace all of numpy and pylab, and configures IPython to correctly interact with the GUI event loop. The GUI backend to be used can be optionally selected with the optional gui argument.

This method only adds preloading the namespace to InteractiveShell.enable_matplotlib.

Parameters:
  • gui (optional, string) – If given, dictates the choice of matplotlib GUI backend to use (should be one of IPython’s supported backends, ‘qt’, ‘osx’, ‘tk’, ‘gtk’, ‘wx’ or ‘inline’), otherwise we use the default chosen by matplotlib (as dictated by the matplotlib build-time options plus the user’s matplotlibrc configuration file). Note that not all backends make sense in all contexts, for example a terminal ipython can’t display figures inline.

  • import_all (optional, bool, default: True) – Whether to do from numpy import * and from pylab import * in addition to module imports.

  • welcome_message (deprecated) – This argument is ignored, no welcome message will be displayed.

ev(expr)

Evaluate python expression expr in user namespace.

Returns the result of evaluation

ex(cmd)

Execute a normal python statement in user namespace.

excepthook(etype, value, tb)

One more defense for GUI apps that call sys.excepthook.

GUI frameworks like wxPython trap exceptions and call sys.excepthook themselves. I guess this is a feature that enables them to keep running after exceptions that would otherwise kill their mainloop. This is a bother for IPython which expects to catch all of the program exceptions with a try: except: statement.

Normally, IPython sets sys.excepthook to a CrashHandler instance, so if any app directly invokes sys.excepthook, it will look to the user like IPython crashed. In order to work around this, we can disable the CrashHandler and replace it with this excepthook instead, which prints a regular traceback using our InteractiveTB. In this fashion, apps which call sys.excepthook will generate a regular-looking exception from IPython, and the CrashHandler will only be triggered by real IPython crashes.

This hook should be used sparingly, only in places which are not likely to be true IPython errors.

extract_input_lines(range_str, raw=False)

Return as a string a set of input history slices.

Parameters:
  • range_str (str) –

    The set of slices is given as a string, like “~5/6-~4/2 4:8 9”, since this function is for use by magic functions which get their arguments as strings. The number before the / is the session number: ~n goes n back from the current session.

    If empty string is given, returns history of current session without the last input.

  • raw (bool, optional) – By default, the processed input is used. If this is true, the raw input history is used instead.

Notes

Slices can be described with two notations:

  • N:M -> standard python form, means including items N…(M-1).

  • N-M -> include items N..M (closed endpoint).

find_cell_magic(magic_name)

Find and return a cell magic by name.

Returns None if the magic isn’t found.

find_line_magic(magic_name)

Find and return a line magic by name.

Returns None if the magic isn’t found.

find_magic(magic_name, magic_kind='line')

Find and return a magic of the given type by name.

Returns None if the magic isn’t found.

find_user_code(target, raw=True, py_only=False, skip_encoding_cookie=True, search_ns=False)

Get a code string from history, file, url, or a string or macro.

This is mainly used by magic functions.

Parameters:
  • target (str) –

    A string specifying code to retrieve. This will be tried respectively as: ranges of input history (see %history for syntax), url, corresponding .py file, filename, or an expression evaluating to a string or Macro in the user namespace.

    If empty string is given, returns complete history of current session, without the last line.

  • raw (bool) – If true (default), retrieve raw history. Has no effect on the other retrieval mechanisms.

  • py_only (bool (default False)) – Only try to fetch python code, do not try alternative methods to decode file if unicode fails.

Returns:

  • A string of code.

  • ValueError is raised if nothing is found, and TypeError if it evaluates

  • to an object of another type. In each case, .args[0] is a printable

  • message.

get_exception_only(exc_tuple=None)

Return as a string (ending with a newline) the exception that just occurred, without any traceback.

get_ipython()

Return the currently running IPython instance.

get_local_scope(stack_depth)

Get local scope at given stack depth.

Parameters:

stack_depth (int) – Depth relative to calling frame

Gets path links including all symlinks

Examples

In [1]: from IPython.core.interactiveshell import InteractiveShell

In [2]: import sys, pathlib

In [3]: paths = InteractiveShell.get_path_links(pathlib.Path(sys.executable))

In [4]: len(paths) == len(set(paths)) Out[4]: True

In [5]: bool(paths) Out[5]: True

getoutput(cmd, split=True, depth=0)

Get output (possibly including stderr) from a subprocess.

Parameters:
  • cmd (str) – Command to execute (can not end in ‘&’, as background processes are not supported.

  • split (bool, optional) – If True, split the output into an IPython SList. Otherwise, an IPython LSString is returned. These are objects similar to normal lists and strings, with a few convenience attributes for easier manipulation of line-based output. You can use ‘?’ on them for details.

  • depth (int, optional) – How many frames above the caller are the local variables which should be expanded in the command string? The default (0) assumes that the expansion variables are in the stack frame calling this function.

history_length

Total length of command history

history_load_length

The number of saved history entries to be loaded into the history buffer at startup.

init_completer()

Initialize the completion machinery.

This creates completion machinery that can be used by client code, either interactively in-process (typically triggered by the readline library), programmatically (such as in test suites) or out-of-process (typically over the network by remote frontends).

init_environment()

Any changes we need to make to the user’s environment.

init_history()

Sets up the command history, and starts regular autosaves.

init_logstart()

Initialize logging in case it was requested at the command line.

init_user_ns()

Initialize all user-visible namespaces to their minimum defaults.

Certain history lists are also initialized here, as they effectively act as user namespaces.

Notes

All data structures here are only filled in, they are NOT reset by this method. If they were not empty before, data will simply be added to them.

init_virtualenv()

Add the current virtualenv to sys.path so the user can import modules from it. This isn’t perfect: it doesn’t use the Python interpreter with which the virtualenv was built, and it ignores the –no-site-packages option. A warning will appear suggesting the user installs IPython in the virtualenv, but for many cases, it probably works well enough.

Adapted from code snippets online.

http://blog.ufsoft.org/2009/1/29/ipython-and-virtualenv

property input_splitter

Make this available for backward compatibility (pre-7.0 release) with existing code.

For example, ipykernel ipykernel currently uses shell.input_splitter.check_complete

input_transformers_post: List

A list of string input transformers, to be applied after IPython’s own input transformations.

inspector_class

Class to use to instantiate the shell inspector

last_execution_result

Result of executing the last command

last_execution_succeeded

Did last executed command succeeded

logappend

Start logging to the given file in append mode. Use logfile to specify a log file to overwrite logs to.

logfile

The name of the logfile to use.

logstart

Start logging to the default log file in overwrite mode. Use logappend to specify a log file to append logs to.

loop_runner

Select the loop runner that will be used to execute top-level asynchronous code

magic(arg_s)

DEPRECATED

Deprecated since IPython 0.13 (warning added in 8.1), use run_line_magic(magic_name, parameter_s).

Call a magic function by name.

Input: a string containing the name of the magic function to call and any additional arguments to be passed to the magic.

magic(‘name -opt foo bar’) is equivalent to typing at the ipython prompt:

In[1]: %name -opt foo bar

To call a magic without arguments, simply use magic(‘name’).

This provides a proper Python function to call IPython’s magics in any valid Python code you can type at the interpreter, including loops and compound statements.

mktempfile(data=None, prefix='ipython_edit_')

Make a new tempfile and return its filename.

This makes a call to tempfile.mkstemp (created in a tempfile.mkdtemp), but it registers the created filename internally so ipython cleans it up at exit time.

Optional inputs:

  • data(None): if data is given, it gets written out to the temp file immediately, and the file is closed again.

new_main_mod(filename, modname)

Return a new ‘main’ module object for user code execution.

filename should be the path of the script which will be run in the module. Requests with the same filename will get the same module, with its namespace cleared.

modname should be the module name - normally either ‘__main__’ or the basename of the file without the extension.

When scripts are executed via %run, we must keep a reference to their __main__ module around so that Python doesn’t clear it, rendering references to module globals useless.

This method keeps said reference in a private dict, keyed by the absolute path of the script. This way, for multiple executions of the same script we only keep one copy of the namespace (the last one), thus preventing memory leaks from old references while allowing the objects from the last execution to be accessible.

object_inspect(oname, detail_level=0)

Get object info about oname

object_inspect_mime(oname, detail_level=0, omit_sections=())

Get object info as a mimebundle of formatted representations.

A mimebundle is a dictionary, keyed by mime-type. It must always have the key 'text/plain'.

object_inspect_text(oname, detail_level=0)

Get object info as formatted text

pdb

Automatically call the pdb debugger after every exception.

prepare_user_module(user_module=None, user_ns=None)

Prepare the module and namespace in which user code will be run.

When IPython is started normally, both parameters are None: a new module is created automatically, and its __dict__ used as the namespace.

If only user_module is provided, its __dict__ is used as the namespace. If only user_ns is provided, a dummy module is created, and user_ns becomes the global namespace. If both are provided (as they may be when embedding), user_ns is the local namespace, and user_module provides the global namespace.

Parameters:
  • user_module (module, optional) – The current user module in which IPython is being run. If None, a clean module will be created.

  • user_ns (dict, optional) – A namespace in which to run interactive commands.

Return type:

A tuple of user_module and user_ns, each properly initialised.

push(variables, interactive=True)

Inject a group of variables into the IPython user namespace.

Parameters:
  • variables (dict, str or list/tuple of str) – The variables to inject into the user’s namespace. If a dict, a simple update is done. If a str, the string is assumed to have variable names separated by spaces. A list/tuple of str can also be used to give the variable names. If just the variable names are give (list/tuple/str) then the variable values looked up in the callers frame.

  • interactive (bool) – If True (default), the variables will be listed with the who magic.

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

register_post_execute(func)

DEPRECATED: Use ip.events.register(‘post_run_cell’, func)

Register a function for calling after code execution.

reset(new_session=True, aggressive=False)

Clear all internal namespaces, and attempt to release references to user objects.

If new_session is True, a new history session will be opened.

reset_selective(regex=None)

Clear selective variables from internal namespaces based on a specified regular expression.

Parameters:

regex (string or compiled pattern, optional) – A regular expression pattern that will be used in searching variable names in the users namespaces.

restore_sys_module_state()

Restore the state of the sys module.

async run_ast_nodes(nodelist: ~typing.List[~ast.stmt], cell_name: str, interactivity='last_expr', compiler=<built-in function compile>, result=None)

Run a sequence of AST nodes. The execution mode depends on the interactivity parameter.

Parameters:
  • nodelist (list) – A sequence of AST nodes to run.

  • cell_name (str) – Will be passed to the compiler as the filename of the cell. Typically the value returned by ip.compile.cache(cell).

  • interactivity (str) – ‘all’, ‘last’, ‘last_expr’ , ‘last_expr_or_assign’ or ‘none’, specifying which nodes should be run interactively (displaying output from expressions). ‘last_expr’ will run the last node interactively only if it is an expression (i.e. expressions in loops or other blocks are not displayed) ‘last_expr_or_assign’ will run the last expression or the last assignment. Other values for this parameter will raise a ValueError.

  • compiler (callable) – A function with the same interface as the built-in compile(), to turn the AST nodes into code objects. Default is the built-in compile().

  • result (ExecutionResult, optional) – An object to store exceptions that occur during execution.

Returns:

  • True if an exception occurred while running code, False if it finished

  • running.

run_cell(raw_cell, store_history=False, silent=False, shell_futures=True, cell_id=None)

Run a complete IPython cell.

Parameters:
  • raw_cell (str) – The code (including IPython code such as %magic functions) to run.

  • store_history (bool) – If True, the raw and translated cell will be stored in IPython’s history. For user code calling back into IPython’s machinery, this should be set to False.

  • silent (bool) – If True, avoid side-effects, such as implicit displayhooks and and logging. silent=True forces store_history=False.

  • shell_futures (bool) – If True, the code will share future statements with the interactive shell. It will both be affected by previous __future__ imports, and any __future__ imports in the code will affect the shell. If False, __future__ imports are not shared in either direction.

Returns:

result

Return type:

ExecutionResult

async run_cell_async(raw_cell: str, store_history=False, silent=False, shell_futures=True, *, transformed_cell: str | None = None, preprocessing_exc_tuple: Any | None = None, cell_id=None) ExecutionResult

Run a complete IPython cell asynchronously.

Parameters:
  • raw_cell (str) – The code (including IPython code such as %magic functions) to run.

  • store_history (bool) – If True, the raw and translated cell will be stored in IPython’s history. For user code calling back into IPython’s machinery, this should be set to False.

  • silent (bool) – If True, avoid side-effects, such as implicit displayhooks and and logging. silent=True forces store_history=False.

  • shell_futures (bool) – If True, the code will share future statements with the interactive shell. It will both be affected by previous __future__ imports, and any __future__ imports in the code will affect the shell. If False, __future__ imports are not shared in either direction.

  • transformed_cell (str) – cell that was passed through transformers

  • preprocessing_exc_tuple – trace if the transformation failed.

Returns:

run_cell_magic(magic_name, line, cell)

Execute the given cell magic.

Parameters:
  • magic_name (str) – Name of the desired magic function, without ‘%’ prefix.

  • line (str) – The rest of the first input line as a single string.

  • cell (str) – The body of the cell as a (possibly multiline) string.

async run_code(code_obj, result=None, *, async_=False)

Execute a code object.

When an exception occurs, self.showtraceback() is called to display a traceback.

Parameters:
  • code_obj (code object) – A compiled code object, to be executed

  • result (ExecutionResult, optional) – An object to store exceptions that occur during execution.

  • async (Bool (Experimental)) – Attempt to run top-level asynchronous code in a default loop.

Returns:

  • False (successful execution.)

  • True (an error occurred.)

run_line_magic(magic_name: str, line: str, _stack_depth=1)

Execute the given line magic.

Parameters:
  • magic_name (str) – Name of the desired magic function, without ‘%’ prefix.

  • line (str) – The rest of the input line as a single string.

  • _stack_depth (int) – If run_line_magic() is called from magic() then _stack_depth=2. This is added to ensure backward compatibility for use of ‘get_ipython().magic()’

async runcode(code_obj, result=None, *, async_=False)

Execute a code object.

When an exception occurs, self.showtraceback() is called to display a traceback.

Parameters:
  • code_obj (code object) – A compiled code object, to be executed

  • result (ExecutionResult, optional) – An object to store exceptions that occur during execution.

  • async (Bool (Experimental)) – Attempt to run top-level asynchronous code in a default loop.

Returns:

  • False (successful execution.)

  • True (an error occurred.)

safe_execfile(fname, *where, exit_ignore=False, raise_exceptions=False, shell_futures=False)

A safe version of the builtin execfile().

This version will never throw an exception, but instead print helpful error messages to the screen. This only works on pure Python files with the .py extension.

Parameters:
  • fname (string) – The name of the file to be executed.

  • *where (tuple) – One or two namespaces, passed to execfile() as (globals,locals). If only one is given, it is passed as both.

  • exit_ignore (bool (False)) – If True, then silence SystemExit for non-zero status (it is always silenced for zero status, as it is so common).

  • raise_exceptions (bool (False)) – If True raise exceptions everywhere. Meant for testing.

  • shell_futures (bool (False)) – If True, the code will share future statements with the interactive shell. It will both be affected by previous __future__ imports, and any __future__ imports in the code will affect the shell. If False, __future__ imports are not shared in either direction.

safe_execfile_ipy(fname, shell_futures=False, raise_exceptions=False)

Like safe_execfile, but for .ipy or .ipynb files with IPython syntax.

Parameters:
  • fname (str) – The name of the file to execute. The filename must have a .ipy or .ipynb extension.

  • shell_futures (bool (False)) – If True, the code will share future statements with the interactive shell. It will both be affected by previous __future__ imports, and any __future__ imports in the code will affect the shell. If False, __future__ imports are not shared in either direction.

  • raise_exceptions (bool (False)) – If True raise exceptions everywhere. Meant for testing.

safe_run_module(mod_name, where)

A safe version of runpy.run_module().

This version will never throw an exception, but instead print helpful error messages to the screen.

SystemExit exceptions with status code 0 or None are ignored.

Parameters:
  • mod_name (string) – The name of the module to be executed.

  • where (dict) – The globals namespace.

save_sys_module_state()

Save the state of hooks in the sys module.

This has to be called after self.user_module is created.

set_autoindent(value=None)

Set the autoindent flag.

If called with no arguments, it acts as a toggle.

set_completer_frame(frame=None)

Set the frame of the completer.

set_custom_completer(completer, pos=0) None

Adds a new custom completer function.

The position argument (defaults to 0) is the index in the completers list where you want the completer to be inserted.

completer should have the following signature:

def completion(self: Completer, text: string) -> List[str]:
    raise NotImplementedError

It will be bound to the current Completer instance and pass some text and return a list with current completions to suggest to the user.

set_custom_exc(exc_tuple, handler)

Set a custom exception handler, which will be called if any of the exceptions in exc_tuple occur in the mainloop (specifically, in the run_code() method).

Parameters:
  • exc_tuple (tuple of exception classes) –

    A tuple of exception classes, for which to call the defined handler. It is very important that you use a tuple, and NOT A LIST here, because of the way Python’s except statement works. If you only want to trap a single exception, use a singleton tuple:

    exc_tuple == (MyCustomException,)
    

  • handler (callable) –

    handler must have the following signature:

    def my_handler(self, etype, value, tb, tb_offset=None):
        ...
        return structured_traceback
    

    Your handler must return a structured traceback (a list of strings), or None.

    This will be made into an instance method (via types.MethodType) of IPython itself, and it will be called if any of the exceptions listed in the exc_tuple are caught. If the handler is None, an internal basic one is used, which just prints basic info.

    To protect IPython from crashes, if your handler ever raises an exception or returns an invalid result, it will be immediately disabled.

Notes

WARNING: by putting in your own exception handler into IPython’s main execution loop, you run a very good chance of nasty crashes. This facility should only be used if you really know what you are doing.

set_hook(name, hook) sets an internal IPython hook.

IPython exposes some of its internal API as user-modifiable hooks. By adding your function to one of these hooks, you can modify IPython’s behavior to call at runtime your own routines.

set_next_input(s, replace=False)

Sets the ‘default’ input string for the next command line.

Example:

In [1]: _ip.set_next_input("Hello Word")
In [2]: Hello Word_  # cursor is here
should_run_async(raw_cell: str, *, transformed_cell=None, preprocessing_exc_tuple=None) bool

Return whether a cell should be run asynchronously via a coroutine runner

Parameters:

raw_cell (str) – The code to be executed

Returns:

  • result (bool) – Whether the code needs to be run with a coroutine runner or not

  • .. versionadded:: 7.0

show_rewritten_input

Show rewritten input, e.g. for autocall.

show_usage()

Show a usage message

show_usage_error(exc)

Show a short message for UsageErrors

These are special exceptions that shouldn’t show a traceback.

showindentationerror()

Called by _run_cell when there’s an IndentationError in code entered at the prompt.

This is overridden in TerminalInteractiveShell to show a message about the %paste magic.

showsyntaxerror(filename=None, running_compiled_code=False)

Display the syntax error that just occurred.

This doesn’t display a stack trace because there isn’t one.

If a filename is given, it is stuffed in the exception instead of what was there before (because Python’s parser always uses “<string>” when reading from a string).

If the syntax error occurred when running a compiled code (i.e. running_compile_code=True), longer stack trace will be displayed.

showtraceback(exc_tuple=None, filename=None, tb_offset=None, exception_only=False, running_compiled_code=False)

Display the exception that just occurred.

If nothing is known about the exception, this is the method which should be used throughout the code for presenting user tracebacks, rather than directly invoking the InteractiveTB object.

A specific showsyntaxerror() also exists, but this method can take care of calling it if needed, so unless you are explicitly catching a SyntaxError exception, don’t try to analyze the stack manually and simply call this method.

sphinxify_docstring

Enables rich html representation of docstrings. (This requires the docrepr module).

system(cmd)

Call the given cmd in a subprocess, piping stdout/err

Parameters:

cmd (str) – Command to execute (can not end in ‘&’, as background processes are not supported. Should not be a command that expects input other than simple text.

system_piped(cmd)

Call the given cmd in a subprocess, piping stdout/err

Parameters:

cmd (str) – Command to execute (can not end in ‘&’, as background processes are not supported. Should not be a command that expects input other than simple text.

system_raw(cmd)

Call the given cmd in a subprocess using os.system on Windows or subprocess.call using the system shell on other platforms.

Parameters:

cmd (str) – Command to execute.

transform_ast(node)

Apply the AST transformations from self.ast_transformers

Parameters:

node (ast.Node) – The root node to be transformed. Typically called with the ast.Module produced by parsing user input.

Returns:

  • An ast.Node corresponding to the node it was called with. Note that it

  • may also modify the passed object, so don’t rely on references to the

  • original AST.

transform_cell(raw_cell)

Transform an input cell before parsing it.

Static transformations, implemented in IPython.core.inputtransformer2, deal with things like %magic and !system commands. These run on all input. Dynamic transformations, for things like unescaped magics and the exit autocall, depend on the state of the interpreter. These only apply to single line inputs.

These string-based transformations are followed by AST transformations; see transform_ast().

user_expressions(expressions)

Evaluate a dict of expressions in the user’s namespace.

Parameters:

expressions (dict) – A dict with string keys and string values. The expression values should be valid Python expressions, each of which will be evaluated in the user namespace.

Returns:

  • A dict, keyed like the input expressions dict, with the rich mime-typed

  • display_data of each value.

var_expand(cmd, depth=0, formatter=<DollarFormatter>)

Expand python variables in a string.

The depth argument indicates how many frames above the caller should be walked to look for the local namespace where to expand variables.

The global namespace for expansion is always the user’s interactive namespace.

warn_venv

Warn if running in a virtual environment with no IPython installed (so IPython from the global environment is used).

xmode

Switch modes for the IPython exception handlers.

class IPython.core.interactiveshell.InteractiveShellABC

Bases: object

An abstract base class for InteractiveShell.

2 Functions

IPython.core.interactiveshell.sphinxify(oinfo)
IPython.core.interactiveshell.is_integer_string(s: str)

Variant of “str.isnumeric()” that allow negative values and other ints.