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 of APP will be used and environ-config will look for an environment variable called APP_VAR.

  • from_environ – If not None, attach a config loading method with the name from_environ to the class. See to_config for more information.

  • generate_help – If not None, attach a config loading method with the name generate_help to the class. See generate_help for more information.

  • frozen – The configuration will be immutable after instantiation, if True.

New in version 19.1.0: from_environ

New in version 19.1.0: generate_help

New 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 a bool.

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 using APP_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

New 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:

str

This is equivalent to calling config_cls.generate_help().

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

Parameters:
  • path (str | Path) – A path to an INI file.

  • section – The section in the INI file to read the secrets from.

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.

Parameters:
  • env_name (str) – Environment variable that is used to determine the path of the secrets file.

  • default (str | None) – The default path to load from.

  • section (str) – The section in the INI file to read the secrets from.

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.

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.

New in version 21.1.0.

classmethod from_path(path)#

Look for secrets in path directory.

Parameters:

path (str | Path) – A path to directory containing secrets as files.

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.

Parameters:
  • env_name (str) – Environment variable that is used to determine the path of the secrets directory.

  • default (str | Path | None) – The default path to load from.

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 -m pip install environ-config[aws]

New 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 class

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