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

Get an instanceof the default converter used by Typed Settings.

Return type

GenConverter

Returns

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

The converter can also structure attrs instances from existing attrs instances (normaly, it would only work with dicts). This allows using instances of nested class es of default values for options. See register_structure_hook_factory().

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

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[TypeVar(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

TypeVar(T)

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[TypeVar(T)]) – Attrs class with options (and default values).
loaders (Sequence[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

TypeVar(T)

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.

Changed in version 1.0.0: Renamed load() to __call__() and also pass the settings class.

__call__(settings_cls, options)[source]#

Load settings for the given options.

Parameters

options (List[OptionInfo]) – The list of available settings.
settings_cls (type) – The base settings class for all options.

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.

Changed in version 1.0.0: Renamed load_file() to __call__() and also pass the settings class.

__call__(path, settings_cls, 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.
settings_cls (type) – The base settings class for all options.

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.InstanceLoader(instance)[source]#

Load settings from an instance of the settings class.

Parameters: instance (object) – The settings instance from which to load option values.

New in version 1.0.0.

__call__(settings_cls, options)[source]#

Load settings for the given options.

Parameters

options (List[OptionInfo]) – The list of available settings.
settings_cls (type) – The base settings class for all options.

Return type

MutableMapping[str, Any]

Returns

A dict with the loaded settings.

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

Load settings from environment variables.

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

__call__(settings_cls, options)[source]#

Load settings for the given options.

Parameters

options (List[OptionInfo]) – The list of available settings.
settings_cls (type) – The base settings class for all options.

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.

__call__(settings_cls, options)[source]#

Load settings for the given options.

Parameters

options (List[OptionInfo]) – The list of available settings.
settings_cls (type) – The base settings class for all options.

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 Python 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

__call__(path, settings_cls, 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.
settings_cls (type) – The base settings class for all options.

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.

__call__(path, settings_cls, 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.
settings_cls (type) – The base settings class for all options.

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: str#: Dotted path to the option name relative to the root settings class.

field: attr._make.Attribute#: attr.Attribute instance for the option.

cls: type#: 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. They are all also available directly from the typed_settings module.

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 attrs.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, click=None)[source]#

An alias to attrs.field()

Additional Parameters:

help (str): The help string for Click options
click (dict): Additional keyword arguments to pass to click.option(). They can override everything that Typed Settings automatically generated for you. If that dict contains a help, it overrides the value of the help argument. In addition, it can contain the key param_decls: str | Sequence(str) to override the automatically generated ones.

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, click=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.

See option() for help on the addional parameters.

Example:

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

typed_settings.attrs.evolve(inst, **changes)[source]#

Create a new instance, based on inst with changes applied.

If the old value of an attribute is an attrs class and the new value is a dict, the old value is updated recursively.

Warning

This function is very similar to attrs.evolve(), but the attrs version is not updating values recursively. Instead, it will just replace attrs instances with a dict.

Parameters

inst – Instance of a class with attrs attributes.
changes – Keyword changes in the new copy.

Returns

A copy of inst with changes incorporated.

Raises

TypeError – If attr_name couldn’t be found in the class __init__.
attr.exceptions.NotAnAttrsClassError – If cls is not an attrs class.

New in version 1.0.0.

Converters#

Converters and helpers for cattr.

typed_settings.converters.default_converter()[source]#

Get an instanceof the default converter used by Typed Settings.

Return type

GenConverter

Returns

A cattrs.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.converters.register_attrs_hook_factory(converter)[source]#

These instances are then returned as-is and without further processing.

Return type: None

typed_settings.converters.register_strlist_hook(converter, sep=None, fn=None)[source]#

Register a hook factory with converter that allows structuring lists, (frozen) sets and tuples 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

typed_settings.converters.from_dict(settings, cls, converter)[source]#

Convert a settings dict to an attrs class instance using a cattrs converter.

Parameters

settings (MutableMapping[str, Any]) – Dictionary with settings
cls (Type[TypeVar(T)]) – Attrs class to which the settings are converted to
converter (Converter) – Cattrs convert to use for the conversion

Return type

TypeVar(T)

Returns

An instance of cls.

Raises

InvalidValueError – If a value cannot be converted to the correct type.

typed_settings.converters.to_dt(value, _type=<class 'datetime.datetime'>)[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

value (Union[datetime, str]) – The input data
_type (type) – The desired output type, will be ignored

Return type

datetime

Returns

The converted datetime instance

Raises

TypeError – If val is neither a string nor a datetime

typed_settings.converters.to_bool(value, _type=<class 'bool'>)[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.

Return type: bool

typed_settings.converters.to_enum(value, 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 create one by name (MyEnum[val]).

Parameters

value (Any) – The input data
cls (Type[TypeVar(ET, bound= Enum)]) – The enum type

Return type

TypeVar(ET, bound= Enum)

Returns

An instance of cls

Raises

KeyError – If value is not a valid member of cls

Click Options#

Decorators for using Typed Settings with and as click options.

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

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

A single cls instance is passed to the decorated function – by default as positional argument.

Parameters

cls (Type[TypeVar(T)]) – Attrs class with options (and default values).
loaders (Union[str, Sequence[Loader]]) – Either a string with your app name or a list of settings Loader’s. If it is a string, use it with default_loaders() to get the defalt loaders.
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.
argname (Optional[str]) –
An optional argument name. If it is set, the settings instances is no longer passed as positional argument but as key word argument.

This allows a function to be decorated with this function multiple times.

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, "example")
... def cli(settings):
...     print(settings)

Changed in version 1.0.0: Instead of a list of loaders, you can also just pass an application name.

Changed in version 1.1.0: Add the argname parameter.

typed_settings.pass_settings(f=None, *, argname=None)[source]#

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

If you specifiy an argname in click_options(), you must specify the same name here in order to get the correct settings instance. The settings instance is then passed as keyword argument.

Parameters: argname (Optional[str]) – An optional argument name. If it is set, the settings instances is no longer passed as positional argument but as key word argument.
Return type: Callable[..., Any]
Returns: A decorator for a click command.

Example

>>> import click
>>> import typed_settings as ts
>>>
>>> @ts.settings
... class Settings: ...
...
>>> @click.group()
... @click_options(Settings, "example", argname="my_settings")
... def cli(my_settings):
...     pass
...
>>> @cli.command()
... # Use the same "argname" as above!
... @pass_settings(argname="my_settings")
... def sub_cmd(*, my_settings):
...     print(my_settings)

Changed in version 1.1.0: Add the argname parameter.

Utilities for generating Click options#

Utilities for generating Click options

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

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

t.Types that cause multiple=True:

t.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]