API

Basic

envbox.base.get_environment(default: Union[str, envbox.envs.Environment, None] = 'development', detectors: List[envbox.detectors.Detector] = None, detectors_opts: dict = None, use_envfiles: bool = True) → Optional[envbox.envs.Environment]

Returns current environment type object.

Parameters:
  • default – Default environment type or alias.
  • detectors – List of environment detectors to be used in chain. If not set, default builtin chain is used.
  • detectors_opts – Detectors options dictionary. Where keys are detector names and values are keyword arguments dicts.
  • use_envfiles – Whether to set environment variables (if not already set) using data from .env files.
envbox.base.import_by_environment(environment: envbox.envs.Environment = None, module_name_pattern: str = 'settings_%s', silent: bool = False, package_name: str = None) → Optional[envbox.envs.Environment]

Automatically imports symbols of a submodule of a package for given (or detected) environment into globals of an entry-point submodule.

Returns``Environment`` object if module is imported or None.

Example:

- project
--- __init__.py
--- settings.py
--- settings_development.py
  • Here project is a package available for import (note __init__.py).
  • settings.py is an entry point module for settings using import_by_environment().
  • settings_development.py is one of module files for certain environment (development).
  • import_by_environment() call in settings.py makes symbols from settings_development.py available from settings.py.
Parameters:
  • environment –
  • module_name_pattern – Environment submodule name pattern. %s will be replaced with environment name.
  • silent – If True no import error (if any) will be raised.
  • package_name –

    Name of the package holding settings file. We’ll try to guess it if not provided.

    E.g.:
    • someproject.settings
    • someproject.inner.settings

Environments

class envbox.envs.Development(name: str = None, type_cast: bool = None)

Development (local) environment.

Parameters:
  • name –

    Environment name.

    Note

    This will prevail over class attribute.

  • type_cast –

    Whether to cast values into Python natives in .get() and .getmany() by default.

    Note

    This will prevail over class attribute.
drop(key: str)

Removes key from environment.

dropmany(keys: Sequence[str] = None, prefix: str = '')

Drops keys in batch mode.

Parameters:
  • keys – Keys to drop. If not set current env keys will be used.
  • prefix –
get(key: str, default: Any = None, type_cast: bool = None) → Any

Get environment variable value.

Parameters:
  • key –
  • default – Default value to return if no value found.
  • type_cast – Try to cast value into Python native type.
get_casted(key: str, default: Any = None) → Any

The same as get but tries to cast values into Python natives.

getmany(prefix: str = '', type_cast: bool = None) → dict

Returns a dictionary of values for keys the given prefix.

Parameters:
  • prefix –
  • type_cast – Try to cast value into Python native type.
getmany_casted(prefix: str = '') → dict

The same as getnamy but tries to cast values into Python natives.

set(key: str, value: Any, overwrite: bool = True)

Set environment variable.

Parameters:
  • key –
  • value –
  • overwrite – Whether to overwrite value if it’s already set.
setmany(key_val: dict, prefix: str = '', overwrite: bool = True)

Sets values in batch mode.

Parameters:
  • key_val –
  • prefix –
  • overwrite – Whether to overwrite value if it’s already set.
update_from_envfiles()

Updates environment variables (if not already set) using data from .env files.

Files used (as they read; values read later override previous values):
  • .env
  • .env.<env_name>
  • .env.local
  • .env.<env_name>.local

<env_name> - Environment name (e.g. production, development etc.)

class envbox.envs.Production(name: str = None, type_cast: bool = None)

Production (stable) environment.

Parameters:
  • name –

    Environment name.

    Note

    This will prevail over class attribute.

  • type_cast –

    Whether to cast values into Python natives in .get() and .getmany() by default.

    Note

    This will prevail over class attribute.
drop(key: str)

Removes key from environment.

dropmany(keys: Sequence[str] = None, prefix: str = '')

Drops keys in batch mode.

Parameters:
  • keys – Keys to drop. If not set current env keys will be used.
  • prefix –
get(key: str, default: Any = None, type_cast: bool = None) → Any

Get environment variable value.

Parameters:
  • key –
  • default – Default value to return if no value found.
  • type_cast – Try to cast value into Python native type.
get_casted(key: str, default: Any = None) → Any

The same as get but tries to cast values into Python natives.

getmany(prefix: str = '', type_cast: bool = None) → dict

Returns a dictionary of values for keys the given prefix.

Parameters:
  • prefix –
  • type_cast – Try to cast value into Python native type.
getmany_casted(prefix: str = '') → dict

The same as getnamy but tries to cast values into Python natives.

set(key: str, value: Any, overwrite: bool = True)

Set environment variable.

Parameters:
  • key –
  • value –
  • overwrite – Whether to overwrite value if it’s already set.
setmany(key_val: dict, prefix: str = '', overwrite: bool = True)

Sets values in batch mode.

Parameters:
  • key_val –
  • prefix –
  • overwrite – Whether to overwrite value if it’s already set.
update_from_envfiles()

Updates environment variables (if not already set) using data from .env files.

Files used (as they read; values read later override previous values):
  • .env
  • .env.<env_name>
  • .env.local
  • .env.<env_name>.local

<env_name> - Environment name (e.g. production, development etc.)

class envbox.envs.Staging(name: str = None, type_cast: bool = None)

Staging (prestable) environment.

Parameters:
  • name –

    Environment name.

    Note

    This will prevail over class attribute.

  • type_cast –

    Whether to cast values into Python natives in .get() and .getmany() by default.

    Note

    This will prevail over class attribute.
drop(key: str)

Removes key from environment.

dropmany(keys: Sequence[str] = None, prefix: str = '')

Drops keys in batch mode.

Parameters:
  • keys – Keys to drop. If not set current env keys will be used.
  • prefix –
get(key: str, default: Any = None, type_cast: bool = None) → Any

Get environment variable value.

Parameters:
  • key –
  • default – Default value to return if no value found.
  • type_cast – Try to cast value into Python native type.
get_casted(key: str, default: Any = None) → Any

The same as get but tries to cast values into Python natives.

getmany(prefix: str = '', type_cast: bool = None) → dict

Returns a dictionary of values for keys the given prefix.

Parameters:
  • prefix –
  • type_cast – Try to cast value into Python native type.
getmany_casted(prefix: str = '') → dict

The same as getnamy but tries to cast values into Python natives.

set(key: str, value: Any, overwrite: bool = True)

Set environment variable.

Parameters:
  • key –
  • value –
  • overwrite – Whether to overwrite value if it’s already set.
setmany(key_val: dict, prefix: str = '', overwrite: bool = True)

Sets values in batch mode.

Parameters:
  • key_val –
  • prefix –
  • overwrite – Whether to overwrite value if it’s already set.
update_from_envfiles()

Updates environment variables (if not already set) using data from .env files.

Files used (as they read; values read later override previous values):
  • .env
  • .env.<env_name>
  • .env.local
  • .env.<env_name>.local

<env_name> - Environment name (e.g. production, development etc.)

class envbox.envs.Testing(name: str = None, type_cast: bool = None)

Testing environment.

Parameters:
  • name –

    Environment name.

    Note

    This will prevail over class attribute.

  • type_cast –

    Whether to cast values into Python natives in .get() and .getmany() by default.

    Note

    This will prevail over class attribute.
drop(key: str)

Removes key from environment.

dropmany(keys: Sequence[str] = None, prefix: str = '')

Drops keys in batch mode.

Parameters:
  • keys – Keys to drop. If not set current env keys will be used.
  • prefix –
get(key: str, default: Any = None, type_cast: bool = None) → Any

Get environment variable value.

Parameters:
  • key –
  • default – Default value to return if no value found.
  • type_cast – Try to cast value into Python native type.
get_casted(key: str, default: Any = None) → Any

The same as get but tries to cast values into Python natives.

getmany(prefix: str = '', type_cast: bool = None) → dict

Returns a dictionary of values for keys the given prefix.

Parameters:
  • prefix –
  • type_cast – Try to cast value into Python native type.
getmany_casted(prefix: str = '') → dict

The same as getnamy but tries to cast values into Python natives.

set(key: str, value: Any, overwrite: bool = True)

Set environment variable.

Parameters:
  • key –
  • value –
  • overwrite – Whether to overwrite value if it’s already set.
setmany(key_val: dict, prefix: str = '', overwrite: bool = True)

Sets values in batch mode.

Parameters:
  • key_val –
  • prefix –
  • overwrite – Whether to overwrite value if it’s already set.
update_from_envfiles()

Updates environment variables (if not already set) using data from .env files.

Files used (as they read; values read later override previous values):
  • .env
  • .env.<env_name>
  • .env.local
  • .env.<env_name>.local

<env_name> - Environment name (e.g. production, development etc.)

envbox.envs.get_type(cls_or_alias: Union[Type[Environment], str]) → Type[envbox.envs.Environment]

Returns environment type by alias (or class itself)

Parameters:cls_or_alias –
envbox.envs.register_type(env_type: Union[Type[Environment], str], alias: str = None) → Type[envbox.envs.Environment]

Registers environment type.

Parameters:
  • env_type – Environment type or its alias (for already registered types).
  • alias – Alias to register type under. If not set type name is used.

Environment detection

class envbox.detectors.Environ(**kwargs)

Gets environment from OS environment variable.

class envbox.detectors.File(**kwargs)

Gets environment from file.

envbox.detectors.get_detector(cls_or_name: Union[Type[envbox.detectors.Detector], str]) → Type[envbox.detectors.Detector]

Returns detector by alias (or class itself)

Parameters:cls_or_name –
envbox.detectors.register_detector(detector: Type[envbox.detectors.Detector])

Registers an environment detector.

Parameters:detector –

Settings container

class envbox.settings.SettingsBase

Use this class as base for your classes containing settings.

Note

Settings are per-thread.

Every uppercase attribute of of a heir class will be treated as a setting.

Accessing any setting which was not set in the session, will lead to appropriate environment variable probing, thus:

  1. current session value
  2. environment value
  3. default value
class _Settings(SettingsBase):

    ONE = 1
    SOME = 'two'
    ANOTHER = True

Settings = _Settings()

if Settings.ANOTHER:
    Settings.SOME = 'three'
get_environment() → Optional[Environment]

Return current environment.

This could be customized by a child if required.