IPython Documentation

Table Of Contents

Previous topic


Next topic


This Page


Module: core.magics.logging

Inheritance diagram for IPython.core.magics.logging:

Implementation of magic functions for IPython’s own logging.


class IPython.core.magics.logging.LoggingMagics(shell)

Bases: IPython.core.magic.Magics

Magics related to all logging machinery.


Print docstring if incorrect arguments were passed

default_option(fn, optstr)

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


Format a string for latex inclusion.


Temporarily stop logging.

You must have previously started logging.


Restart logging.

This function is for restarting logging which you’ve temporarily stopped with %logoff. For starting logging for the first time, you must use the %logstart function, which allows you to specify an optional log filename.


Start logging anywhere in a session.

%logstart [-o|-r|-t] [log_name [log_mode]]

If no name is given, it defaults to a file named ‘ipython_log.py’ in your current directory, in ‘rotate’ mode (see below).

‘%logstart name’ saves to file ‘name’ in ‘backup’ mode. It saves your history up to that point and then continues logging.

%logstart takes a second optional parameter: logging mode. This can be one of (note that the modes are given unquoted):

append: well, that says it.backup: rename (if exists) to name~ and start name.global: single logfile in your home dir, appended to.over : overwrite existing log.rotate: create rotating logs name.1~, name.2~, etc.


-o: log also IPython’s output. In this mode, all commands which generate an Out[NN] prompt are recorded to the logfile, right after their corresponding input line. The output lines are always prepended with a ‘#[Out]# ‘ marker, so that the log remains valid Python code.

Since this marker is always the same, filtering only the output from a log is very easy, using for example a simple awk call:

awk -F'#\[Out\]# ' '{if($2) {print $2}}' ipython_log.py

-r: log ‘raw’ input. Normally, IPython’s logs contain the processed input, so that user lines are logged in their final form, converted into valid Python. For example, %Exit is logged as _ip.magic(“Exit”). If the -r flag is given, all input is logged exactly as typed, with no transformations applied.

-t: put timestamps before each input line logged (these are put in comments).


Print the status of the logging system.


Fully stop logging and close log file.

In order to start logging again, a new %logstart call needs to be made, possibly (though not necessarily) with a new filename, mode and other options.

magics = {'cell': {}, 'line': {'logstop': 'logstop', 'logoff': 'logoff', 'logon': 'logon', 'logstate': 'logstate', 'logstart': 'logstart'}}
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.


-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 = True
shell = None