Note

This documentation is for a development version of IPython. There may be significant differences from the latest stable release (1.2.1).

Module: config.loader

A simple configuration system.

Inheritance diagram:

Authors

• Brian Granger
• Fernando Perez
• Min RK

15 Classes

class IPython.config.loader.ConfigError

Bases: exceptions.Exception

class IPython.config.loader.ConfigLoaderError

Bases: IPython.config.loader.ConfigError

class IPython.config.loader.ConfigFileNotFound

Bases: IPython.config.loader.ConfigError

class IPython.config.loader.ArgumentError

Bases: IPython.config.loader.ConfigLoaderError

class IPython.config.loader.ArgumentParser(prog=None, usage=None, description=None, epilog=None, version=None, parents=, []formatter_class=<class 'argparse.HelpFormatter'>, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True)

Bases: argparse.ArgumentParser

Simple argparse subclass that prints help to stdout by default.

class IPython.config.loader.LazyConfigValue(*args, **kw)

Bases: IPython.utils.traitlets.HasTraits

Proxy object for exposing methods on configurable containers

Exposes:

• append, extend, insert on lists
• update on dicts
• update, add on sets

get_value(initial)

construct the value from the initial one

after applying any insert / extend / update changes

prepend(other)

like list.extend, but for the front

to_dict()

return JSONable dict form of my data

Currently update as dict or set, extend, prepend as lists, and inserts as list of tuples.

class IPython.config.loader.Config(*args, **kwds)

Bases: dict

An attribute based dict that can do smart merges.

__init__(*args, **kwds)

merge(other)

merge another config object into this one

class IPython.config.loader.ConfigLoader(log=None)

Bases: object

A object for loading configurations from just about anywhere.

The resulting configuration is packaged as a Config.

Notes

A ConfigLoader does one thing: load a config from a source (file, command line arguments) and returns the data as a Config object. There are lots of things that ConfigLoader does not do. It does not implement complex logic for finding config files. It does not handle default values or merge multiple configs. These things need to be handled elsewhere.

__init__(log=None)

A base class for config loaders.

log : instance of logging.Logger to use.

By default loger of IPython.config.application.Application.instance() will be used

Examples

>>> cl = ConfigLoader()
>>> config = cl.load_config()
>>> config
{}

load_config()

Load a config from somewhere, return a Config instance.

Usually, this will cause self.config to be set and then returned. However, in most cases, ConfigLoader.clear() should be called to erase any previous state.

class IPython.config.loader.FileConfigLoader(filename, path=None, **kw)

Bases: IPython.config.loader.ConfigLoader

A base class for file based configurations.

As we add more file based config loaders, the common logic should go here.

__init__(filename, path=None, **kw)

Build a config loader for a filename and path.

Parameters:

filename : str

The file name of the config file.

path : str, list, tuple

The path to search for the config file on, or a sequence of paths to try in order.

class IPython.config.loader.JSONFileConfigLoader(filename, path=None, **kw)

Bases: IPython.config.loader.FileConfigLoader

A Json file loader for config

load_config()

Load the config from a file and return it as a Config object.

class IPython.config.loader.PyFileConfigLoader(filename, path=None, **kw)

Bases: IPython.config.loader.FileConfigLoader

A config loader for pure python files.

This is responsible for locating a Python config file by filename and path, then executing it to construct a Config object.

load_config()

Load the config from a file and return it as a Config object.

class IPython.config.loader.CommandLineConfigLoader(log=None)

Bases: IPython.config.loader.ConfigLoader

A config loader for command line arguments.

As we add more command line based loaders, the common logic should go here.

class IPython.config.loader.KeyValueConfigLoader(argv=None, aliases=None, flags=None, **kw)

Bases: IPython.config.loader.CommandLineConfigLoader

A config loader that loads key value pairs from the command line.

This allows command line options to be gives in the following form:

ipython --profile="foo" --InteractiveShell.autocall=False

__init__(argv=None, aliases=None, flags=None, **kw)

Create a key value pair config loader.

Parameters:

argv : list

A list that has the form of sys.argv[1:] which has unicode elements of the form u”key=value”. If this is None (default), then sys.argv[1:] will be used.

aliases : dict

A dict of aliases for configurable traits. Keys are the short aliases, Values are the resolved trait. Of the form: {‘alias’ : ‘Configurable.trait’}

flags : dict

A dict of flags, keyed by str name. Vaues can be Config objects, dicts, or “key=value” strings. If Config or dict, when the flag is triggered, The flag is loaded as self.config.update(m).

Returns:

config : Config

The resulting Config object.

Examples

>>> from IPython.config.loader import KeyValueConfigLoader
>>> cl = KeyValueConfigLoader()
>>> d = cl.load_config(["--A.name='brian'","--B.number=0"])
>>> sorted(d.items())
[('A', {'name': 'brian'}), ('B', {'number': 0})]

load_config(argv=None, aliases=None, flags=None)

Parse the configuration and generate the Config object.

After loading, any arguments that are not key-value or flags will be stored in self.extra_args - a list of unparsed command-line arguments. This is used for arguments such as input files or subcommands.

Parameters:

argv : list, optional

A list that has the form of sys.argv[1:] which has unicode elements of the form u”key=value”. If this is None (default), then self.argv will be used.

aliases : dict

A dict of aliases for configurable traits. Keys are the short aliases, Values are the resolved trait. Of the form: {‘alias’ : ‘Configurable.trait’}

flags : dict

A dict of flags, keyed by str name. Values can be Config objects or dicts. When the flag is triggered, The config is loaded as self.config.update(cfg).

class IPython.config.loader.ArgParseConfigLoader(argv=None, aliases=None, flags=None, log=None, *parser_args, **parser_kw)

Bases: IPython.config.loader.CommandLineConfigLoader

A loader that uses the argparse module to load from the command line.

__init__(argv=None, aliases=None, flags=None, log=None, *parser_args, **parser_kw)

Create a config loader for use with argparse.

Parameters:

argv : optional, list

If given, used to read command-line arguments from, otherwise sys.argv[1:] is used.

parser_args : tuple

A tuple of positional arguments that will be passed to the constructor of argparse.ArgumentParser.

parser_kw : dict

A tuple of keyword arguments that will be passed to the constructor of argparse.ArgumentParser.

Returns:

config : Config

The resulting Config object.

load_config(argv=None, aliases=None, flags=None)

Parse command line arguments and return as a Config object.

Parameters:

args : optional, list

If given, a list with the structure of sys.argv[1:] to parse arguments from. If not given, the instance’s self.argv attribute (given at construction time) is used.

class IPython.config.loader.KVArgParseConfigLoader(argv=None, aliases=None, flags=None, log=None, *parser_args, **parser_kw)

Bases: IPython.config.loader.ArgParseConfigLoader

A config loader that loads aliases and flags with argparse, but will use KVLoader for the rest. This allows better parsing of common args, such as ipython -c ‘print 5’, but still gets arbitrary config with ipython –InteractiveShell.use_readline=False

1 Function

IPython.config.loader.load_pyconfig_files(config_files, path)

Load multiple Python config files, merging each of them in turn.

Parameters:

config_files : list of str

List of config files names to load and merge into the config.

path : unicode

The full path to the location of the config files.