### Navigation

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

# config.configurable

## Module: `config.configurable`

Inheritance diagram for `IPython.config.configurable`:

A base class for objects that are configurable.

Authors:

- Brian Granger
- Fernando Perez
- Min RK

## Classes

### `Configurable`

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

  Bases: `IPython.utils.traitlets.HasTraits`

  `__init__`(**kwargs)

    Create a configurable given a config config.

    Parameters :

    config : Config

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

    Notes

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

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

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

### `ConfigurableError`

class `IPython.config.configurable.``ConfigurableError`

  Bases: `exceptions.Exception`

  `__init__`()

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

  `args`
  `message`

### `LoggingConfigurable`

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.

  `__init__`(**kwargs)

    Create a configurable given a config config.

    Parameters :

    config : Config

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

    Notes

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

  `log`

    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.

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

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

### `MultipleInstanceError`

class `IPython.config.configurable.``MultipleInstanceError`

  Bases: `IPython.config.configurable.ConfigurableError`

  `__init__`()

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

  `args`
  `message`

### `SingletonConfigurable`

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.

  `__init__`(**kwargs)

    Create a configurable given a config config.

    Parameters :

    config : Config

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

    Notes

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

  classmethod `clear_instance`()

    unset _instance for this class and singleton parents.

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

  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.

    Examples

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

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

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

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

### Navigation

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