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:datetime.datetime
usingto_dt()
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 theTomlFormat
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
- 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
- Return type
- 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()
withdefault_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
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.
Exceptions#
Exceptions raised by Typed Settings.
- 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.
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
- 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
- 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
- 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
- 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 toFileFormat
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 isNone
, 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
- 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.
- __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
- 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
- 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
- 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.
- field: attr._make.Attribute#
attr.Attribute
instance for the option.
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., seeto_bool()
)datetime.datetime
, (ISO format with support forZ
suffix, seeto_dt()
).Attrs/Settings classes (see
to_attrs()
)All other types use the type object itself as converter, this includes
int
,float
,str
, andEnum
,pathlib.Path
, ….typing.Any
(no conversion is performed)
- Supported generic types:
typing.List[T]
,typing.Sequence[T]
,typing.MutableSequence[T]
(converts tolist
, seeto_iterable()
)typing.Tuple[T, ...]
(converts totuple
, seeto_iterable()
)typing.Tuple[X, Y, Z]
(converts totuple
, seeto_tuple()
)typing.Dict[K, V]
,typing.Mapping[K, V]
,typing.MutableMapping[K, V]
(converts todict
, seeto_mapping()
)typing.Optional[T]
,typing.Union[X, Y, Z]
(converts to first matching type, seeto_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 ahelp
, it overrides the value of the help argument. In addition, it can contain the keyparam_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 theattrs
version is not updating values recursively. Instead, it will just replaceattrs
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:datetime.datetime
usingto_dt()
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.converters.register_attrs_hook_factory(converter)[source]#
Register a hook factory that allows using instances of attrs classes where cattrs would normally expect a dictionary.
These instances are then returned as-is and without further processing.
- Return type
- 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 (seestr.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
- typed_settings.converters.from_dict(settings, cls, converter)[source]#
Convert a settings dict to an attrs class instance using a cattrs converter.
- Parameters
- 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
.
- 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
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 viaload_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 settingsLoader
’s. If it is a string, use it withdefault_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.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
- 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
- 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.
- typed_settings.click_utils.handle_enum(type, default)[source]#
Use
EnumChoice
as option type and use the enum value’s name as default.
- 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 atype
key and, optionally, an updateddefault
.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()
andhandle_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
ornargs=x
. Nested types are recursively resolved.t.Types that cause
multiple=True
:t.Types that cause
nargs=x
:typing.Tuple
Dicts are not (yet) supported.