API

Config

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

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 to set the default search path.
  • sources (iterable) –

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

  • 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.
__call__(key, cast=None, default=<object object>, help_text=None)[source]

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.
  • default – A default value to use if this value is not provided. (Note that the default value is not passed to the cast function.)
  • help_text (str) – Help text to display to the user, explaining the usage of this parameter.

Note

As a special case, when the bool builtin is passed to cast, the value returned will be True if the input is a case-insensitive match for y, yes, t, or true, False for a case-insensitive match for n, no, f, or false, and an error otherwise. In every other case, the function (or constructor) passed in is called itself.

__weakref__

list of weak references to the object (if defined)

get(*args, **kwargs)[source]

Compatibility alias of __call__().

Sources

Built-In

class walter.sources.EnvironmentSource(prefix='')[source]

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]

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 sources

class walter.sources.Source[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)[source]

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)[source]

Return a new source with the given file object.

Returns:A new source object.
match_filename(filename)[source]

Test a filename to see if it matches this source.

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

The NA object

Note

I’m sorry. It was the only way.

Warning

That’s a lie. I’m actually quite proud of this.

walter.na.NA

A singleton object representing an unavailable value, of type NaType.

Used to allow execution to continue when a value is unset or invalid, so that Walter can discover the remaining values.

class walter.na.NaType[source]

Type representing an unavailable value.

There is only one instance of NaType, NA.

NA is semantically similar to None, but unlike None it is designed to propagate through a program that isn’t expecting it, without ever causing an exception to be thrown. NA can be treated like a boolean, string, container or numeric value.

NA is falsy, unequal to anything including itself, and compares less than anything including negative infinity. It returns itself on function calls, attribute and item access, or when used on either side of any operator. It can be formatted by str.format() or in a f-string with any format spec. Setting or deleting attributes or items is a no-op. When used as a context manager it returns itself, suppressing exceptions on exit. When iterated over, iteration stops immediately (as if it is empty).

It is awaitable (returning itself), and acts as an asynchronous context manager and iterator (behaving identically to the synchronous versions).