Warning

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

Module: config.loader

A simple configuration system.

Inheritance diagram:

Authors

• Brian Granger
• Fernando Perez
• Min RK

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

Bases: object

A object for loading configurations from just about anywhere.

The resulting configuration is packaged as a Struct.

Notes

A ConfigLoader does one thing: load a config from a source (file, command line arguments) and returns the data as a Struct. 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__()

A base class for config loaders.

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

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.

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

Bases: IPython.config.loader.FileConfigLoader

A config loader for pure python files.

This calls execfile on a plain python file and looks for attributes that are all caps. These attribute are added to the config Struct.

__init__(filename, path=None)

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.

load_config()

Load the config from a file and return it as a Struct.

class IPython.config.loader.CommandLineConfigLoader

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)

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)

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, *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, *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, *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.