core.history

Module: core.history

Inheritance diagram for IPython.core.history:

History related magics and functionality

Classes

DummyDB

class IPython.core.history.DummyDB

Bases: object

Dummy DB that will act as a black hole for history.

Only used in the absence of sqlite

__init__()

x.__init__(...) initializes x; see help(type(x)) for signature

commit(*args, **kwargs)

execute(*args, **kwargs)

HistoryAccessor

class IPython.core.history.HistoryAccessor(profile='default', hist_file=u'', config=None, **traits)

Bases: IPython.config.configurable.Configurable

Access the history database without adding to it.

This is intended for use by standalone history tools. IPython shells use HistoryManager, below, which is a subclass of this.

__init__(profile='default', hist_file=u'', config=None, **traits)

Create a new history accessor.

Parameters :

profile : str

The name of the profile from which to open history.

hist_file : str

Path to an SQLite history database stored by IPython. If specified, hist_file overrides profile.

config : :

Config object. hist_file can also be set through this.

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

db

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.

get_range(session, start=1, stop=None, raw=True, output=False)

Retrieve input by session.

Parameters :

session : int

Session number to retrieve.

start : int

First line to retrieve.

stop : int

End of line range (excluded from output itself). If None, retrieve to the end of the session.

raw : bool

If True, return untranslated input

output : bool

If True, attempt to include output. This will be ‘real’ Python objects for the current session, or text reprs from previous sessions if db_log_output was enabled at the time. Where no output is found, None is used.

Returns :

An iterator over the desired lines. Each line is a 3-tuple, either :

(session, line, input) if output is False, or :

(session, line, (input, output)) if output is True. :

get_range_by_str(rangestr, raw=True, output=False)

Get lines of history from a string of ranges, as used by magic commands %hist, %save, %macro, etc.

Parameters :

rangestr : str

A string specifying ranges, e.g. “5 ~2/1-4”. See magic_history() for full details.

raw, output : bool

As get_range()

Returns :

Tuples as :meth:`get_range` :

get_session_info(session=0)

get info about a session

Parameters :

session : int

Session number to retrieve. The current session is 0, and negative numbers count back from current session, so -1 is previous session.

Returns :

(session_id [int], start [datetime], end [datetime], num_cmds [int], :

remark [unicode]) :

Sessions that are running or did not exit cleanly will have `end=None` :

and `num_cmds=None`. :

get_tail(n=10, raw=True, output=False, include_latest=False)

Get the last n lines from the history database.

Parameters :

n : int

The number of lines to get

raw, output : bool

See get_range()

include_latest : bool

If False (default), n+1 lines are fetched, and the latest one is discarded. This is intended to be used where the function is called by a user command, which it should not return.

Returns :

Tuples as :meth:`get_range` :

hist_file

A trait for unicode strings.

init_db()

Connect to the database, and create tables if necessary.

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.

search(pattern='*', raw=True, search_raw=True, output=False)

Search the database using unix glob-style matching (wildcards * and ?).

Parameters :

pattern : str

The wildcarded pattern to match when searching

search_raw : bool

If True, search the raw input, otherwise, the parsed input

raw, output : bool

See get_range()

Returns :

Tuples as :meth:`get_range` :

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.

writeout_cache()

Overridden by HistoryManager to dump the cache before certain database lookups.

HistoryManager

class IPython.core.history.HistoryManager(shell=None, config=None, **traits)

Bases: IPython.core.history.HistoryAccessor

A class to organize all history-related functionality in one place.

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

Create a new history manager associated with a shell instance.

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

db

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.

db_cache_size

An integer trait.

Longs that are unnecessary (<= sys.maxint) are cast to ints.

db_input_cache

An instance of a Python list.

db_log_output

A boolean (True, False) trait.

db_output_cache

An instance of a Python list.

dir_hist

An instance of a Python list.

end_session()

Close the database session, filling in the end time and line count.

get_range(session=0, start=1, stop=None, raw=True, output=False)

Retrieve input by session.

Parameters :

session : int

Session number to retrieve. The current session is 0, and negative numbers count back from current session, so -1 is previous session.

start : int

First line to retrieve.

stop : int

End of line range (excluded from output itself). If None, retrieve to the end of the session.

raw : bool

If True, return untranslated input

output : bool

If True, attempt to include output. This will be ‘real’ Python objects for the current session, or text reprs from previous sessions if db_log_output was enabled at the time. Where no output is found, None is used.

Returns :

An iterator over the desired lines. Each line is a 3-tuple, either :

(session, line, input) if output is False, or :

(session, line, (input, output)) if output is True. :

get_range_by_str(rangestr, raw=True, output=False)

Get lines of history from a string of ranges, as used by magic commands %hist, %save, %macro, etc.

Parameters :

rangestr : str

A string specifying ranges, e.g. “5 ~2/1-4”. See magic_history() for full details.

raw, output : bool

As get_range()

Returns :

Tuples as :meth:`get_range` :

get_session_info(session=0)

get info about a session

Parameters :

session : int

Session number to retrieve. The current session is 0, and negative numbers count back from current session, so -1 is previous session.

Returns :

(session_id [int], start [datetime], end [datetime], num_cmds [int], :

remark [unicode]) :

Sessions that are running or did not exit cleanly will have `end=None` :

and `num_cmds=None`. :

get_tail(n=10, raw=True, output=False, include_latest=False)

Get the last n lines from the history database.

Parameters :

n : int

The number of lines to get

raw, output : bool

See get_range()

include_latest : bool

If False (default), n+1 lines are fetched, and the latest one is discarded. This is intended to be used where the function is called by a user command, which it should not return.

Returns :

Tuples as :meth:`get_range` :

hist_file

A trait for unicode strings.

init_db()

Connect to the database, and create tables if necessary.

input_hist_parsed

An instance of a Python list.

input_hist_raw

An instance of a Python list.

name_session(name)

Give the current session a name in the history database.

new_session(conn=None)

Get a new session number.

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.

output_hist

An instance of a Python dict.

output_hist_reprs

An instance of a Python dict.

reset(new_session=True)

Clear the session history, releasing all object references, and optionally open a new session.

save_flag

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.

save_thread

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.

search(pattern='*', raw=True, search_raw=True, output=False)

Search the database using unix glob-style matching (wildcards * and ?).

Parameters :

pattern : str

The wildcarded pattern to match when searching

search_raw : bool

If True, search the raw input, otherwise, the parsed input

raw, output : bool

See get_range()

Returns :

Tuples as :meth:`get_range` :

session_number

An integer trait.

Longs that are unnecessary (<= sys.maxint) are cast to ints.

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.

store_inputs(line_num, source, source_raw=None)

Store source and raw input in history and create input cache variables _i*.

Parameters :

line_num : int

The prompt number of this input.

source : str

Python input.

source_raw : str, optional

If given, this is the raw input without any IPython transformations applied to it. If not given, source is used.

store_output(line_num)

If database output logging is enabled, this saves all the outputs from the indicated prompt number to the database. It’s called by run_cell after code has been executed.

Parameters :

line_num : int

The line number from which to save outputs

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.

writeout_cache(conn=None)

Write any entries in the cache to the database.

HistorySavingThread

class IPython.core.history.HistorySavingThread(history_manager)

Bases: threading.Thread

This thread takes care of writing history to the database, so that the UI isn’t held up while that happens.

It waits for the HistoryManager’s save_flag to be set, then writes out the history cache. The main thread is responsible for setting the flag when the cache size reaches a defined threshold.

__init__(history_manager)

daemon = True

getName()

ident

isAlive()

isDaemon()

is_alive()

join(timeout=None)

name

run()

setDaemon(daemonic)

setName(name)

start()

stop()

This can be called from the main thread to safely stop this thread.

Note that it does not attempt to write out remaining history before exiting. That should be done by calling the HistoryManager’s end_session method.

stop_now = False

Functions

IPython.core.history.extract_hist_ranges(ranges_str)

Turn a string of history ranges into 3-tuples of (session, start, stop).

Examples

list(extract_input_ranges(“~8/5-~7/4 2”)) [(-8, 5, None), (-7, 1, 4), (0, 2, 3)]

IPython.core.history.needs_sqlite(f)

return an empty list in the absence of sqlite