IPython Documentation

Table Of Contents

Previous topic

Module: config.application

Next topic

Module: config.loader

This Page


This documentation is for an old version of IPython. You can find docs for newer versions here.

Module: config.configurable

A base class for objects that are configurable.

Inheritance diagram:

Inheritance diagram of IPython.config.configurable


  • Brian Granger
  • Fernando Perez
  • Min RK

5 Classes

class IPython.config.configurable.ConfigurableError

Bases: exceptions.Exception

class IPython.config.configurable.MultipleInstanceError

Bases: IPython.config.configurable.ConfigurableError

class IPython.config.configurable.Configurable(**kwargs)

Bases: IPython.utils.traitlets.HasTraits


Create a configurable given a config config.


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.


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 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 section_names()

return section names as a list


Fire the traits events when the config is updated.

class IPython.config.configurable.SingletonConfigurable(**kwargs)

Bases: IPython.config.configurable.Configurable

A configurable that only allows one instance.

This class is for classes that should only have one instance of itself or any subclass. To create and retrieve such a class use the SingletonConfigurable.instance() method.

classmethod clear_instance()

unset _instance for this class and singleton parents.

classmethod initialized()

Has an instance been created?

classmethod instance(*args, **kwargs)

Returns a global instance of this class.

This method create a new instance if none have previously been created and returns a previously created instance is one already exists.

The arguments and keyword arguments passed to this method are passed on to the __init__() method of the class upon instantiation.


Create a singleton class using instance, and retrieve it:

>>> from IPython.config.configurable import SingletonConfigurable
>>> class Foo(SingletonConfigurable): pass
>>> foo = Foo.instance()
>>> foo == Foo.instance()

Create a subclass that is retrived using the base class instance:

>>> class Bar(SingletonConfigurable): pass
>>> class Bam(Bar): pass
>>> bam = Bam.instance()
>>> bam == Bar.instance()
class IPython.config.configurable.LoggingConfigurable(**kwargs)

Bases: IPython.config.configurable.Configurable

A parent class for Configurables that log.

Subclasses have a log trait, and the default behavior is to get the logger from the currently running Application via Application.instance().log.