API Reference¶
- environ.config(*, prefix: str | Sentinel = PREFIX_NOT_SET, from_environ: str = 'from_environ', generate_help: str = 'generate_help', frozen: bool = False) Callable[[type[T]], type[T]] ¶
- environ.config(maybe_cls: type[T]) type[T]
Make a class a configuration class.
- Parameters:
prefix – The prefix that is used for the env variables. If you have an
var
attribute on the class and you leave the default argument value of PREFIX_NOT_SET, the DEFAULT_PREFIX value ofAPP
will be used and environ-config will look for an environment variable calledAPP_VAR
.from_environ – If not
None
, attach a config loading method with the name from_environ to the class. Seeto_config
for more information.generate_help – If not
None
, attach a config loading method with the name generate_help to the class. Seegenerate_help
for more information.frozen – The configuration will be immutable after instantiation, if
True
.
Added in version 19.1.0: from_environ
Added in version 19.1.0: generate_help
Added in version 20.1.0: frozen
Changed in version 21.1.0: prefix now defaults to PREFIX_NOT_SET instead of
APP
.
- environ.var(default=Raise(), converter=None, name=None, validator=None, help=None)¶
Declare a configuration attribute on the body of
config
-decorated class.It will be attempted to be filled from an environment variable based on the prefix and name.
- Parameters:
default (Any) – Setting this to a value makes the config attribute optional.
name (str | None) – Overwrite name detection with a string. If not set, the name of the attribute is used.
converter (Callable | None) – A callable that is run with the found value and its return value is used. Please not that it is also run for default values.
validator (Callable | None) – A callable that is run with the final value. See attrs’s chapter on validation for details. You can also use any validator that is shipped with attrs.
help (str | None) – A help string that is used by
generate_help
.
- environ.bool_var(default=Raise(), name=None, help=None)¶
Like
var
, but converts the value to abool
.The following values are considered
True
:True
(if you set a default)"1"
"true"
"yes"
Every other value is interpreted as
False
. Leading and trailing whitespace is ignored.
- environ.group(cls, optional=False)¶
A configuration attribute that is another configuration class.
This way you can nest your configuration hierarchically although the values are coming from a flat source.
The group’s name is used to build a namespace:
@environ.config class Cfg: @environ.config class Sub: x = environ.var() sub = environ.group(Sub)
The value of
x
is looked up usingAPP_SUB_X
.You can nest your configuration as deeply as you wish.
The optional keyword argument can be used to mark a group referencing a “child” config object so that if all variables defined in the child (including sub-groups) are not present in the environment being parsed, the attribute corresponding to the optional group will be set to
None
.- Parameters:
optional (bool) – Mark this group as optional. Defaults to
False
.- Returns:
An attribute which will be used as a nested group of variables.
- Return type:
T
Added in version 21.1.0: optional
- environ.to_config(config_cls, environ=os.environ)¶
Load the configuration as declared by config_cls from environ.
- Parameters:
config_cls (type[T]) – The configuration class to fill.
environ (dict[str, str]) – Source of the configuration.
os.environ
by default.
- Returns:
An instance of config_cls.
- Return type:
T
This is equivalent to calling
config_cls.from_environ()
.
- environ.generate_help(config_cls, formatter=None, **kwargs)¶
Autogenerate a help string for a config class.
- Parameters:
formatter (Callable | None) – A callable that will be called with the help dictionaries as an argument and the remaining kwargs. It should return the help string.
display_defaults (bool) – When using the default formatter, passing
True
for display_defaults makes the default values part of the output.
- Returns:
A help string that can be printed to the user.
- Return type:
This is equivalent to calling
config_cls.generate_help()
.Added in version 19.1.0.
Secrets¶
Handling of sensitive data.
- class environ.secrets.INISecrets(section, cfg=None, env_name=None, env_default=None)¶
Load secrets from an INI file using
configparser.RawConfigParser
.- classmethod from_path(path, section='secrets')¶
Look for secrets in section of path.
- classmethod from_path_in_env(env_name, default=None, section='secrets')¶
Get the path from the environment variable env_name at runtime and then load the secrets from it.
This allows you to overwrite the path to the secrets file in development.
- secret(default=Raise(), converter=None, name=None, section=None, help=None)¶
Declare a secret on an
environ.config
-decorated class.- Parameters:
section (str | None) – Overwrite the section where to look for the values.
Other parameters work just like in
environ.var
.
- class environ.secrets.VaultEnvSecrets(vault_prefix)¶
Loads secrets from environment variables that follow the naming style from envconsul.
Warning
Please note that it’s a bad idea to store secrets in environment variables.
- secret(default=Raise(), converter=None, name=None, help=None)¶
Almost identical to
environ.var
except that it takes envconsul naming into account.
- class environ.secrets.DirectorySecrets(secrets_dir, env_name=None)¶
Load secrets from a directory containing secrets in separate files. Suitable for reading Docker or Kubernetes secrets from the filesystem inside a container.
Added in version 21.1.0.
- classmethod from_path(path)¶
Look for secrets in path directory.
- classmethod from_path_in_env(env_name, default)¶
Get the path from the environment variable env_name and then load the secrets from that directory at runtime.
This allows you to overwrite the path to the secrets directory in development.
- class environ.secrets.SecretsManagerSecrets(client=None)¶
Load secrets from the AWS Secrets Manager.
The secret name should be stored in the environment variable
Warning
Requires boto3! Please install environ-config with the
aws
extra:python -Im pip install environ-config[aws]
Added in version 21.4.0.
- secret(default=Raise(), converter=<function convert_secret.<locals>.converter>, name=None, help=None)¶
Declare a secrets manager secret on an
environ.config
-decorated classAll parameters work just like in
environ.var
.
Exceptions¶
Exceptions raised by environ-config.
- exception environ.exceptions.MissingEnvValueError¶
A mandatory environment variable can’t be found.
- exception environ.exceptions.MissingSecretError¶
A mandatory secret can’t be found.