API Reference¶

This is the full list of all public classes and functions.

Core¶

Core Functions¶

Core functions for loading and working with settings.

typed_settings.default_loaders(appname, config_files=(), *, config_file_section=AUTO, config_files_var=AUTO, env_prefix=AUTO)[source]¶

Return a list of default settings loaders that are used by load().

These loaders are:

A FileLoader loader configured with the TomlFormat
An EnvLoader

The FileLoader will load files from config_files and from the environment variable config_files_var.

Parameters

appname (str) – Your application’s name – used to derive defaults for the remaining args.
config_files (Iterable[Union[str, Path]]) – Load settings from these files. The last one has the highest precedence.
config_file_section (Union[str, _Auto]) – Name of your app’s section in the config file. By default, use appname (in lower case and with “_” replaced by “-“.
config_files_var (Union[None, str, _Auto]) –
Load list of settings files from this environment variable. By default, use {APPNAME}_SETTINGS. Multiple paths have to be separated by “:”. The last file has the highest precedence. All files listed in this var have higher precedence than files from config_files.

Set to None to disable this feature.
env_prefix (Union[None, str, _Auto]) –
Load settings from environment variables with this prefix. By default, use APPNAME_.

Set to None to disable loading env vars.

Return type

List[Loader]

Returns

A list of Loader instances.

typed_settings.find(filename, stop_dir='/', stop_files=('.git', '.hg'))[source]¶

Search for a file in the current directory and its parents and return its path.

If the file cannot be found until stop_dir is reached or a directory contains stop_file, return the input filename.

Parameters

filename (str) – The name of the file to find.
stop_dir (Union[str, Path]) – Stop searching if the current search dir equals this one.
stop_file – Stop searching if the current search dir contains this file.

Return type

Path

Returns

The resolved path to filename if found, else Path(filename).

Examples

Find settings.toml until the root of the current directory is reached:

find("settings.py")

Find pyproject.toml only in the current Git project:

find("pyproject.toml", stop_file=".git")

typed_settings.load(cls, appname, config_files=(), *, config_file_section=AUTO, config_files_var=AUTO, env_prefix=AUTO)[source]¶

Load settings for appname and return an instance of cls

This function is a shortcut for load_settings() with default_loaders().

Settings are loaded from config_files and from the files specified via the config_files_var environment variable. Settings can also be overridden via environment variables named like the corresponding setting and prefixed with env_prefix.

Settings precedence (from lowest to highest priority):

Default value from cls
First file from config_files
…
Last file from config_files
First file from config_files_var
…
Last file from config_files_var
Environment variable {env_prefix}_{SETTING}

Config files (both, explicitly specified, and loaded from an environment variable) are optional by default. You can prepend an ! to their path to mark them as mandatory (e.g., !/etc/credentials.toml). An error is raised if a mandatory file does not exist.

Parameters

cls (Type[~T]) – Attrs class with default settings.
appname (str) – Your application’s name. Used to derive defaults for the remaining args.
config_files (Iterable[Union[str, Path]]) – Load settings from these files.
config_file_section (Union[str, _Auto]) – Name of your app’s section in the config file. By default, use appname (in lower case and with “_” replaced by “-“.
config_files_var (Union[None, str, _Auto]) –
Load list of settings files from this environment variable. By default, use {APPNAME}_SETTINGS. Multiple paths have to be separated by “:”. The last file has the highest precedence. All files listed in this var have higher precedence than files from config_files.

Set to None to disable this feature.
env_prefix (Union[None, str, _Auto]) –
Load settings from environment variables with this prefix. By default, use APPNAME_.

Set to None to disable loading env vars.

Return type

Returns

An instance of cls populated with settings from settings files and environment variables.

Raises

UnknownFormatError – When no FileFormat is configured for a loaded file.
ConfigFileNotFoundError – If path does not exist.
ConfigFileLoadError – If path cannot be read/loaded/decoded.
InvalidOptionsError – If invalid settings have been found.
InvalidValueError – If a value cannot be converted to the correct type.

typed_settings.load_settings(cls, loaders, converter=None)[source]¶

Load settings defined by the class cls and return an instance of it.

Parameters

cls (Type[~T]) – Attrs class with options (and default values).
loaders (List[Loader]) – A list of settings Loader’s.
converter (Optional[Converter]) –
An optional cattr.Converter used for converting option values to the required type.

By default, typed_settings.attrs.converter is used.

Return type

Returns

An instance of cls populated with settings from the defined loaders.

Raises

TsError – Depending on the configured loaders, any subclass of this exception.

Exceptions¶

Exceptions raised by Typed Settings.

exception typed_settings.exceptions.TsError[source]¶: Basse class for all typed settings exceptions.

exception typed_settings.exceptions.UnknownFormatError[source]¶: Raised when no file format loader is configured for a given config file.

exception typed_settings.exceptions.ConfigFileNotFoundError[source]¶: Raised when a mandatory config file does not exist.

exception typed_settings.exceptions.ConfigFileLoadError[source]¶: Raised when a config file exists but cannot be read or parsed/loaded.

exception typed_settings.exceptions.InvalidOptionsError[source]¶: Raised when loaded settings contain an option that is not defined in the settings class.

exception typed_settings.exceptions.InvalidValueError[source]¶: Raised the value of an option cannot be converted to the correct type.

Loaders¶

class typed_settings.loaders.Loader(*args, **kwds)[source]¶

Protocol: Methods that settings loaders must implement.

Custom settings loaders must implement this.

load(options)[source]¶

Load settings for the given options.

Parameters: options (List[OptionInfo]) – The list of available settings.
Return type: MutableMapping[str, Any]
Returns: A dict with the loaded settings.

class typed_settings.loaders.FileFormat(*args, **kwds)[source]¶

Protocol: Methods that file format loaders for FileLoader must implement.

Custom file format loaders must implement this.

load_file(path, options)[source]¶

Load settings from a given file and return them as a dict.

Parameters

path (Path) – The path to the config file.
options (List[OptionInfo]) – The list of available settings.

Return type

MutableMapping[str, Any]

Returns

A dict with the loaded settings.

Raises

ConfigFileNotFoundError – If path does not exist.
ConfigFileLoadError – If path cannot be read/loaded/decoded.

class typed_settings.loaders.EnvLoader(prefix)[source]¶

Load settings from environment variables.

Parameters: prefix (str) – Prefix for environment variables, e.g., MYAPP_.

load(options)[source]¶

Load settings for the given options.

Parameters: options (List[OptionInfo]) – The list of available settings.
Return type: MutableMapping[str, Any]
Returns: A dict with the loaded settings.

class typed_settings.loaders.FileLoader(formats, files, env_var=None)[source]¶

Load settings from config files.

Settings of multiple files will be merged. The last file has the highest precedence. Files specified via an environment variable are loaded after the files passed to this class, i.e.:

First file from files
…
Last file from files
First file from env_var
…
Last file from env_var

Mandatory files can be prefixed with !. Optional files will be ignored if they don’t exist.

Parameters

formats (Dict[str, FileFormat]) – A dict mapping glob patterns to FileFormat instances.
files (Iterable[Union[str, Path]]) – A list of filenames to try to load.
env_var (Optional[str]) – Name of the environment variable that may hold additional file paths. If it is None, only files from files will be loaded.

load(options)[source]¶

Load settings for the given options.

Parameters

options (List[OptionInfo]) – The list of available settings.

Return type

MutableMapping[str, Any]

Returns

A dict with the loaded settings.

Raises

UnknownFormat – When no FileFormat is configured for a loaded file.
ConfigFileNotFoundError – If path does not exist.
ConfigFileLoadError – If path cannot be read/loaded/decoded.
InvalidOptionError – If invalid settings have been found.

class typed_settings.loaders.PythonFormat(cls_name, key_transformer=<function PythonFormat.<lambda>>, flat=False)[source]¶

Support for TOML files. Read settings from the given section.

Parameters: section – The config file section to load settings from.

static to_lower(text)[source]¶

Transform text to lower case.

Return type: str

load_file(path, options)[source]¶

Load settings from a Python file and return them as a dict.

Parameters

path (Path) – The path to the config file.
options (List[OptionInfo]) – The list of available settings.

Return type

MutableMapping[str, Any]

Returns

A dict with the loaded settings.

Raises

ConfigFileNotFoundError – If path does not exist.
ConfigFileLoadError – If path cannot be read/loaded/decoded.

class typed_settings.loaders.TomlFormat(section)[source]¶

Support for TOML files. Read settings from the given section.

Parameters: section (str) – The config file section to load settings from.

load_file(path, options)[source]¶

Load settings from a TOML file and return them as a dict.

Parameters

path (Path) – The path to the config file.
options (List[OptionInfo]) – The list of available settings.

Return type

MutableMapping[str, Any]

Returns

A dict with the loaded settings.

Raises

ConfigFileNotFoundError – If path does not exist.
ConfigFileLoadError – If path cannot be read/loaded/decoded.

typed_settings.loaders.clean_settings(settings, options, source)[source]¶

Recursively check settings for invalid entries and raise an error.

An error is not raised until all options have been checked. It then lists all invalid options that have been found.

Parameters

settings (MutableMapping[str, Any]) – The settings to be cleaned.
options (List[OptionInfo]) – The list of available settings.
source (Any) – Source of the settings (e.g., path to a config file). It should have a useful string representation.

Return type

MutableMapping[str, Any]

Returns

The cleaned settings.

Raises

InvalidOptionError – If invalid settings have been found.

Types¶

Internal data structures.

typed_settings.types.AUTO = AUTO¶: Sentinel to indicate the lack of a value when None is ambiguous.

class typed_settings.types.OptionInfo(path, field, cls)[source]¶

Information about (possibly nested) option attributes.

Each instance represents a single attribute of an apps’s settings class.

path¶: Dotted path to the option name relative to the root settings class.

field¶: attr.Attribute instance for the option.

cls¶: The option’s settings class. This is either the root settings class or a nested one.

Attrs¶

Classes and Fields¶

Helpers for creating attrs classes and fields with sensible details for Typed Settings.

typed_settings.attrs.settings(maybe_cls=None, *, these=None, repr=None, hash=None, init=None, slots=True, frozen=True, weakref_slot=True, str=False, auto_attribs=None, kw_only=False, cache_hash=False, auto_exc=True, eq=None, order=False, auto_detect=True, getstate_setstate=None, on_setattr=None, field_transformer=<function auto_convert>)¶

An alias to attr.frozen(), configured with a field_transformer that automatically adds converters to all fields based on their annotated type.

Supported concrete types:

bool (from various strings used in env. vars., see to_bool())
datetime.datetime, (ISO format with support for Z suffix, see to_dt()).
Attrs/Settings classes (see to_attrs())
All other types use the type object itself as converter, this includes int, float, str, and Enum, pathlib.Path, ….
typing.Any (no conversion is performed)

Supported generic types:

typing.List[T], typing.Sequence[T], typing.MutableSequence[T] (converts to list, see to_iterable())
typing.Tuple[T, ...] (converts to tuple, see to_iterable())
typing.Tuple[X, Y, Z] (converts to tuple, see to_tuple())
typing.Dict[K, V], typing.Mapping[K, V], typing.MutableMapping[K, V] (converts to dict, see to_mapping())
typing.Optional[T], typing.Union[X, Y, Z] (converts to first matching type, see to_union())

typed_settings.attrs.option(*, default=NOTHING, validator=None, repr=True, hash=None, init=True, metadata=None, converter=None, factory=None, kw_only=False, eq=None, order=None, on_setattr=None, help=None)[source]¶

An alias to attr.field()

Additional Parameters: help (str): The help string for Click options

typed_settings.attrs.secret(*, default=NOTHING, validator=None, repr=***, hash=None, init=True, metadata=None, converter=None, factory=None, kw_only=False, eq=None, order=None, on_setattr=None, help=None)[source]¶

An alias to option() but with a default repr that hides screts.

When printing a settings instances, secret settings will represented with *** istead of their actual value.

Example:

>>> from typed_settings import settings, secret
>>>
>>> @settings
... class Settings:
...     password: str = secret()
...
>>> Settings(password="1234")
Settings(password=***)

Converters¶

typed_settings.attrs.default_converter()[source]¶

Get an instanceof the default converter used by Typed Settings.

Return type

GenConverter

Returns

A cattr.GenConverter configured with addional hooks for loading the follwing types:

This converter can also be used as a base for converters with custom structure hooks.

typed_settings.attrs.register_strlist_hook(converter, sep=None, fn=None)[source]¶

Register a hook factory with converter that allows structuring lists from strings (which may, e.g., come from environment variables).

Parameters

converter (Converter) – The converter to register the hooks with.
sep (Optional[str]) – A separator used for splitting strings (see str.split()). Cannot be used together with fn.
fn (Optional[Callable[[str], list]]) – A function that takes a string and returns a list, e.g., json.loads(). Cannot be used together with spe.

Example

>>> from typing import List
>>>
>>> converter = default_converter()
>>> register_strlist_hook(converter, sep=":")
>>> converter.structure("1:2:3", List[int])
[1, 2, 3]
>>>
>>> import json
>>>
>>> converter = default_converter()
>>> register_strlist_hook(converter, fn=json.loads)
>>> converter.structure("[1,2,3]", List[int])
[1, 2, 3]

Return type: None

Additional (c)attrs converters

typed_settings.attrs.converters.to_bool(val)[source]¶

Convert “boolean” strings (e.g., from env. vars.) to real booleans.

Values mapping to True:

True
"true" / "t"
"yes" / "y"
"on"
"1"
1

Values mapping to False:

False
"false" / "f"
"no" / "n"
"off"
"0"
0

Raise ValueError for any other value.

typed_settings.attrs.converters.to_dt(val)[source]¶

Convert an ISO formatted string to datetime.datetime. Leave the input untouched if it is already a datetime.

See: datetime.datetime.fromisoformat()

The Z suffix is also supported and will be replaced with +00:00.

Parameters: data (Union[str,datetime.datetime]) – The input data
Returns: A parsed datetime object
Return type: datetime.datetime
Raises: TypeError – If val is neither a str nor a datetime.

typed_settings.attrs.converters.to_enum(cls)[source]¶

Return a converter that creates an instance of the Enum cls.

If the to be converted value is not already an enum, the converter will first try to create one by name (MyEnum[val]) and, if that fails, by value (MyEnum(val)).

Click Options¶

Decorators for using Typed Settings with and as click options.

typed_settings.click_options(cls, loaders, converter=None, type_handler=None)[source]¶

Generates click options for a CLI which override settins loaded via load_settings().

A single cls instance is passed to the decorated function

Parameters

cls (Type[~T]) – Attrs class with options (and default values).
loaders (List[Loader]) – A list of settings Loader’s.
converter (Optional[Converter]) –
An optional cattr.Converter used for converting option values to the required type.

By default, typed_settings.attrs.converter is used.
type_handler (Optional[TypeHandler]) – Helps creating proper click options for option types that are not natively supported by click.

Return type

Callable[[Callable], Callable]

Returns

A decorator for a click command.

Example

>>> import click
>>> import typed_settings as ts
>>>
>>> @ts.settings
... class Settings: ...
...
>>> @click.command()
... @ts.click_options(Settings, ts.default_loaders("example"))
... def cli(settings):
...     print(settings)

typed_settings.pass_settings(f)[source]¶

Marks a callback as wanting to receive the innermost settings instance as first argument.

Return type: Callable[…, Any]

Utilities for generating Click options¶

Utilities for generating Click options

class typed_settings.click_utils.EnumChoice(enum_type)[source]¶

Click parameter type for representing enums.

convert(value, param, ctx)[source]¶

Convert the value to the correct type. This is not called if the value is None (the missing value).

This must accept string values from the command line, as well as values that are already the correct type. It may also convert other compatible types.

The param and ctx arguments may be None in certain situations, such as when converting prompt input.

If the value cannot be converted, call fail() with a descriptive message.

Parameters

value (str) – The value to convert.
param (Optional[Parameter]) – The parameter that is using this type to convert its value. May be None.
ctx (Optional[Context]) – The current context that arrived at this value. May be None.

Return type

Enum

typed_settings.click_utils.handle_datetime(type, default)[source]¶

Use click.DateTime as option type and convert the default value to an ISO string.

Return type: Dict[str, Any]

typed_settings.click_utils.handle_enum(type, default)[source]¶

Use EnumChoice as option type and use the enum value’s name as default.

Return type: Dict[str, Any]

typed_settings.click_utils.DEFAULT_TYPES = {<class 'datetime.datetime'>: <function handle_datetime>, <enum 'Enum'>: <function handle_enum>}¶: Default handlers for click option types.

class typed_settings.click_utils.TypeHandler(types=None)[source]¶

This class derives type information for Click options from an Attrs field’s type.

The class differentitates between specific and generic types (e.g., int vs. List[T].

Specific types:

Handlers for specific types can be extended and modified by passing a types dict to the class. By default, DEFAULT_TYPES is used.

This dict maps Python types to a handler function. Handler functions take the field type and default value and return a dict that is passed as keyword arguments to click.option(). This dict should contain a type key and, optionally, an updated default.

def handle_mytype(type: type, default: Any) -> Dict[str, Any]:
    type_info = {
        "type": ClickType(...)
    }
    if default is not attr.NOTHING:
        type_info["default"] = default.stringify()
    return type_info

You can use handle_datetime() and handle_enum() as a sample.

Types without a handler get no special treatment and cause options to look like this: click.option(..., type=field_type, default=field_default).

Generic types:

Handlers for generic types cannot be changed. They either create an option with multiple=True or nargs=x. Nested types are recursively resolved.

Types that cause multiple=True:

Types that cause nargs=x:

typing.Tuple
typing.NamedTuple

Dicts are not (yet) supported.

get_type(otype, default)[source]¶

Analyses the option type and returns updated options.

Return type: Dict[str, Any]