config.loader

Module: config.loader

Inheritance diagram for IPython.config.loader:

A simple configuration system.

Authors

• Brian Granger
• Fernando Perez
• Min RK

Classes

ArgParseConfigLoader

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.

clear()

get_extra_args()

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.

ArgumentError

class IPython.config.loader.ArgumentError

Bases: IPython.config.loader.ConfigLoaderError

__init__()

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

args

message

ArgumentParser

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.

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

add_argument(dest, ..., name=value, ...) add_argument(option_string, option_string, ..., name=value, ...)

add_argument_group(*args, **kwargs)

add_mutually_exclusive_group(**kwargs)

add_subparsers(**kwargs)

convert_arg_line_to_args(arg_line)

error(message: string)

Prints a usage message incorporating the message to stderr and exits.

If you override this in a subclass, it should not return – it should either exit or raise an exception.

exit(status=0, message=None)

format_help()

format_usage()

format_version()

get_default(dest)

parse_args(args=None, namespace=None)

parse_known_args(args=None, namespace=None)

print_help(file=None)

print_usage(file=None)

print_version(file=None)

register(registry_name, value, object)

set_defaults(**kwargs)

CommandLineConfigLoader

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.

__init__()

A base class for config loaders.

Examples

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

clear()

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.

Config

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

Bases: dict

An attribute based dict that can do smart merges.

__init__(*args, **kwds)

clear() → None. Remove all items from D.

copy()

static fromkeys(S[, v]) → New dict with keys from S and values equal to v.

v defaults to None.

get(k[, d]) → D[k] if k in D, else d. d defaults to None.

has_key(key)

items() → list of D's (key, value) pairs, as 2-tuples

iteritems() → an iterator over the (key, value) items of D

iterkeys() → an iterator over the keys of D

itervalues() → an iterator over the values of D

keys() → list of D's keys

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised

popitem() → (k, v), remove and return some (key, value) pair as a

2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

update([E], **F) → None. Update D from dict/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → list of D's values

viewitems() → a set-like object providing a view on D's items

viewkeys() → a set-like object providing a view on D's keys

viewvalues() → an object providing a view on D's values

ConfigError

class IPython.config.loader.ConfigError

Bases: exceptions.Exception

__init__()

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

args

message

ConfigFileNotFound

class IPython.config.loader.ConfigFileNotFound

Bases: IPython.config.loader.ConfigError

__init__()

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

args

message

ConfigLoader

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
{}

clear()

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.

ConfigLoaderError

class IPython.config.loader.ConfigLoaderError

Bases: IPython.config.loader.ConfigError

__init__()

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

args

message

FileConfigLoader

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.

__init__()

A base class for config loaders.

Examples

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

clear()

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.

KVArgParseConfigLoader

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

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

clear()

get_extra_args()

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.

KeyValueConfigLoader

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})]

clear()

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

PyFileConfigLoader

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.

clear()

load_config()

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

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.