API

Config

class walter.config.Config(author, name, sources=None, search_path=None)

Creates a config object.

Parameters:

• author (str) – Name of the person or company that created this program. Used on Windows to set the default search path.
• name (str) – Name of this program. Used on Windows to set the default search path.
• sources (iterable) –

  An iterable of Source objects to pull configuration from. Defaults to the following:

  • EnvironmentSource
  • IniFileSource
• search_path (iterable) – An iterable of directories to search for configuration files. Defaults to the current directory, followed by an appropriate user and site config directory depending on the operating system.

get(key, cast=None, help_text=None)

Get a configuration parameter.

Parameters:

• key (str) – The name of the configuration parameter to get.
• cast (function) – A function to call on the returned parameter to convert it to the appropriate value.
• help_text (str) – Help text to display to the user, explaining the usage of this parameter.

Sources

Built-In

class walter.sources.EnvironmentSource(prefix='')

Source that extracts values from environment variables.

Parameters:prefix (str) – Prefix to expect at the beginning of environment variable names.

class walter.sources.IniFileSource(filename=None, **kwargs)

Source that extracts values from .ini files.

Files should be in the format expected by configparser.ConfigParser.

Parameters:section – Section header to look for settings under. Defaults

to settings. :type section: str

Creating Your Own

class walter.sources.Source

Base class for configuration sources.

To implement a simple (non-file-based) configuration source, subclass this class and override __getitem__.

__getitem__ should return a string, or raise KeyError if a key isn’t found in the configuration source.

If you are implementing an ambient configuration source (e.g. one that reads from environment variables, command-line args, a single file in a well-known location, or something else that doesn’t depend on Walter’s search path), you can expose your Source subclass to users directly. If instead you are implementing a file-based source, see also FileSource.

class walter.sources.FileSource(filename=None, **kwargs)

Base class for file-based configuration sources.

Because Walter implements searching for configuration files internally, and allows for a mix of different types of configuration files, a file-based configuration source consists of two classes.

One is the actual source itself. This is a subclass of Source — not this class — and behaves like a normal source, except it takes a file-like object as its first positional argument, and it is an implementation detail that is not exposed to your users.

The other is the “meta-source”, which is a subclass of FileSource. It is responsible for two things: determining which filenames match the source, and creating new source objects from files. Users will create an instance of the meta-source and pass that to Walter, which will use it to create source instances.

While it is possible to override match_filename() and create() entirely, most meta-sources should be able to get by with simply setting two properties and adding a docstring:

• source_class, your actual source class.
• pattern, a default file pattern to match on, which can be either a shell glob or a compiled regular expression.

Unless you override __init__, your meta-source will accept a filename arg that allows users to override pattern; any other keyword arguments given to the meta-source will be passed through to the source itself.

create(file_obj)

Return a new source with the given file object.

Returns:A new source object.

match_filename(filename)

Test a filename to see if it matches this source.

Returns:Whether the filename matches this source. Return type:bool