### Navigation

- index
- modules |
- next |
- previous |
- home|
- search|
- documentation »
- The IPython API »

# 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`

    Thread identifier of this thread or None if it has not been started.

    This is a nonzero integer. See the thread.get_ident() function. Thread identifiers may be recycled when a thread exits and another thread is created. The identifier is available even after the thread has exited.

  `isAlive`()

    Return whether the thread is alive.

    This method returns True just before the run() method starts until just after the run() method terminates. The module function enumerate() returns a list of all alive threads.

  `isDaemon`()
  `is_alive`()

    Return whether the thread is alive.

    This method returns True just before the run() method starts until just after the run() method terminates. The module function enumerate() returns a list of all alive threads.

  `join`(timeout=None)

    Wait until the thread terminates.

    This blocks the calling thread until the thread whose join() method is called terminates – either normally or through an unhandled exception or until the optional timeout occurs.

    When the timeout argument is present and not None, it should be a floating point number specifying a timeout for the operation in seconds (or fractions thereof). As join() always returns None, you must call isAlive() after join() to decide whether a timeout happened – if the thread is still alive, the join() call timed out.

    When the timeout argument is not present or None, the operation will block until the thread terminates.

    A thread can be join()ed many times.

    join() raises a RuntimeError if an attempt is made to join the current thread as that would cause a deadlock. It is also an error to join() a thread before it has been started and attempts to do so raises the same exception.

  `name`

    A string used for identification purposes only.

    It has no semantics. Multiple threads may be given the same name. The initial name is set by the constructor.

  `run`()
  `setDaemon`(daemonic)
  `setName`(name)
  `start`()

    Start the thread’s activity.

    It must be called at most once per thread object. It arranges for the object’s run() method to be invoked in a separate thread of control.

    This method will raise a RuntimeError if called more than once on the same thread object.

  `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

### Navigation

- index
- modules |
- next |
- previous |
- home|
- search|
- documentation »
- The IPython API »