API Reference


class metakernel.MetaKernel(**kwargs)[source]

The base MetaKernel class.

Create a configurable given a config config.


If this is empty, default values are used. If config is a Config instance, it will be used to configure the instance.

parentConfigurable instance, optional

The parent Configurable instance of this object.


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.

classmethod run_as_main(*args, **kwargs)[source]

Launch or install a metakernel.

Modules implementing a metakernel subclass can use the following lines:

if __name__ == ‘__main__’:



Run this method in an IPython kernel to set this kernel’s input/output settings.

set_variable(name, value)[source]

Set a variable to a Python-typed value.


Lookup a variable name and return a Python-typed value.


The repr of the kernel.


Get the usage statement for the kernel.

get_kernel_help_on(info, level=0, none_on_fail=False)[source]

Get help on an object. Called by the help magic.


Handle the current plot settings


Returns the path to local magics dir (eg ~/.ipython/metakernel/magics)


Get completions from kernel based on info dict.

do_execute_direct(code, silent=False)[source]

Execute code in the kernel language.


Default code for running a file. Just opens the file, and sends the text to do_execute_direct.


Execute meta code in the kernel. This uses the execute infrastructure but allows JavaScript to talk directly to the kernel bypassing normal processing.

When responding to the %%debug magic, the step and reset meta commands can answer with a string in the format:

“highlight: [start_line, start_col, end_line, end_col]”

for highlighting expressions in the frontend.


This function is used with the %%debug magic for highlighting lines of code, and for initializing debug functions.

Return the empty string if highlighting is not supported.

do_function_direct(function_name, arg)[source]

Call a function in the kernel language with args (as a single item).


Restart the kernel

do_execute(code, silent=False, store_history=True, user_expressions=None, allow_stdin=False)[source]

Handle code execution.


post_execute(retval, code, silent)[source]

Post-execution actions

Handle special kernel variables and display response if not silent.

do_history(hist_access_type, output, raw, session=None, start=None, stop=None, n=None, pattern=None, unique=False)[source]

Access history at startup.



Shut down the app gracefully, saving history.



Given code as string, returns dictionary with ‘status’ representing whether code is ready to evaluate. Possible values for status are:

‘complete’ - ready to evaluate ‘incomplete’ - not yet ready ‘invalid’ - invalid code ‘unknown’ - unknown; the default unless overridden

Optionally, if ‘status’ is ‘incomplete’, you may indicate an indentation string.


return {‘status’‘incomplete’,

‘indent’: ‘ ‘ * 4}


do_complete(code, cursor_pos)[source]

Handle code completion for the kernel.


do_inspect(code, cursor_pos, detail_level=0, omit_sections=())[source]

Object introspection.



Clear the output of the kernel.

Display(*objects, **kwargs)[source]

Display one or more objects using rich display.

Supports a clear_output keyword argument that clears the output before displaying.

See https://ipython.readthedocs.io/en/stable/config/integrating.html?highlight=display#rich-display

Print(*objects, **kwargs)[source]

Print objects to the iopub stream, separated by sep and followed by end.

Items can be strings or Widget instances.


Write message directly to the iopub stdout with no added end character.

Error(*objects, **kwargs)[source]

Print objects to stdout, separated by sep and followed by end.

Objects are cast to strings.

Error_display(*objects, **kwargs)[source]

Print objects to stdout is they area strings, separated by sep and followed by end. All other objects are rendered using the Display method Objects are cast to strings.


Reload all of the line and cell magics.


Register magics for a given magic_klass.

send_response(*args, **kwargs)[source]

Send a response to the message we’re currently processing.

This accepts all the parameters of jupyter_client.session.Session.send() except parent.

This relies on set_parent() having been called for the current message.


Given an line, such as “%download http://example.com/”, parse and execute magic.

get_help_on(expr, level=0, none_on_fail=False, cursor_pos=- 1)[source]

Get help for an expression using the help magic.

parse_code(code, cursor_start=0, cursor_end=- 1)[source]

Parse code using our parser.

class metakernel.Magic(kernel)[source]

Base class to define magics for MetaKernel based kernels.

Users can redefine the default magics provided by Metakernel by creating a module with the exact same name as the Metakernel magic.

For example, you can override %matplotlib in your kernel by writing a new magic inside magics/matplotlib_magic.py


Get completions based on info dict from magic.

metakernel.option(*args, **kwargs)[source]

Return decorator that adds a magic option to a function.