API¶

Basic¶

Functions¶

get_environment¶

get_environment(
    default: str | Environment | None = DEVELOPMENT,  # (1)!
    detectors: list[Detector] | None = None,  # (2)!
    detectors_opts: dict | None = None,  # (3)!
    use_envfiles: bool = True,  # (4)!
) -> Environment | None

Default environment type or alias.
List of environment detectors to be used in chain. If not set, default builtin chain is used.
Detectors options dictionary. Where keys are detector names and values are keyword arguments dicts.
Whether to set environment variables (if not already set) using data from .env files.

Returns current environment type object.

import_by_environment¶

import_by_environment(
    environment: Environment = None, 
    module_name_pattern: str = 'settings_%s',  # (1)!
    silent: bool = False,  # (2)!
    package_name: str = '',  # (3)!
) -> Environment | None

Environment submodule name pattern. %s will be replaced with environment name.
If True no import error (if any) will be raised.
Name of the package holding settings file. We'll try to guess it if not provided.

E.g.: * someproject.settings * someproject.inner.settings

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.

Environments¶

Functions¶

get_type¶

get_type(cls_or_alias: TypeEnvArg) -> type[Environment]

Returns environment type by alias (or class itself)

register_type¶

register_type(
    env_type: TypeEnvArg,  # (1)!
    alias: str = '',  # (2)!
) -> type[Environment]

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

Registers environment type.

Classes¶

Development¶

Development(name: str = '', type_cast: bool | None = None)

Environment

Development (local) environment.

is_production ¶

.is_production: bool = False

Indicates whether this environment is production.

is_staging ¶

.is_staging: bool = False

Indicates whether this environment is staging.

is_testing ¶

.is_testing: bool = False

Indicates whether this environment is testing.

type_cast ¶

.self.type_cast = type_cast or self.type_cast

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

drop ¶

.drop(key: str)

Removes key from environment.

dropmany ¶

.dropmany(
    keys: Sequence[str] | None = None,  # (1)!
    prefix: str = ''
)

Keys to drop. If not set current env keys will be used.

Drops keys in batch mode.

get ¶

.get(
    key: str, 
    default: Any = None,  # (1)!
    type_cast: bool | None = None,  # (2)!
) -> Any

Default value to return if no value found.
Try to cast value into Python native type.

Get environment variable value.

get_casted ¶

.get_casted(key: str, default: Any = None) -> Any

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

getmany ¶

.getmany(
    prefix: str = '', 
    type_cast: bool | None = None,  # (1)!
) -> dict

Try to cast value into Python native type.

Returns a dictionary of values for keys the given prefix.

getmany_casted ¶

.getmany_casted(prefix: str = '') -> dict

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

set ¶

.set(
    key: str, 
    value: Any, 
    overwrite: bool = True,  # (1)!
)

Whether to overwrite value if it's already set.

Set environment variable.

setmany ¶

.setmany(
    key_val: dict, 
    prefix: str = '', 
    overwrite: bool = True,  # (1)!
)

Whether to overwrite value if it's already set.

Sets values in batch mode.

update_from_envfiles ¶

.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.local * .env..local

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

Production¶

Production(name: str = '', type_cast: bool | None = None)

Environment

Production (stable) environment.

is_development ¶

.is_development: bool = False

Indicates whether this environment is development.

is_staging ¶

.is_staging: bool = False

Indicates whether this environment is staging.

is_testing ¶

.is_testing: bool = False

Indicates whether this environment is testing.

type_cast ¶

.self.type_cast = type_cast or self.type_cast

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

drop ¶

.drop(key: str)

Removes key from environment.

dropmany ¶

.dropmany(
    keys: Sequence[str] | None = None,  # (1)!
    prefix: str = ''
)

Keys to drop. If not set current env keys will be used.

Drops keys in batch mode.

get ¶

.get(
    key: str, 
    default: Any = None,  # (1)!
    type_cast: bool | None = None,  # (2)!
) -> Any

Default value to return if no value found.
Try to cast value into Python native type.

Get environment variable value.

get_casted ¶

.get_casted(key: str, default: Any = None) -> Any

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

getmany ¶

.getmany(
    prefix: str = '', 
    type_cast: bool | None = None,  # (1)!
) -> dict

Try to cast value into Python native type.

Returns a dictionary of values for keys the given prefix.

getmany_casted ¶

.getmany_casted(prefix: str = '') -> dict

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

set ¶

.set(
    key: str, 
    value: Any, 
    overwrite: bool = True,  # (1)!
)

Whether to overwrite value if it's already set.

Set environment variable.

setmany ¶

.setmany(
    key_val: dict, 
    prefix: str = '', 
    overwrite: bool = True,  # (1)!
)

Whether to overwrite value if it's already set.

Sets values in batch mode.

update_from_envfiles ¶

.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.local * .env..local

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

Staging¶

Staging(name: str = '', type_cast: bool | None = None)

Environment

Staging (prestable) environment.

is_development ¶

.is_development: bool = False

Indicates whether this environment is development.

is_production ¶

.is_production: bool = False

Indicates whether this environment is production.

is_testing ¶

.is_testing: bool = False

Indicates whether this environment is testing.

type_cast ¶

.self.type_cast = type_cast or self.type_cast

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

drop ¶

.drop(key: str)

Removes key from environment.

dropmany ¶

.dropmany(
    keys: Sequence[str] | None = None,  # (1)!
    prefix: str = ''
)

Keys to drop. If not set current env keys will be used.

Drops keys in batch mode.

get ¶

.get(
    key: str, 
    default: Any = None,  # (1)!
    type_cast: bool | None = None,  # (2)!
) -> Any

Default value to return if no value found.
Try to cast value into Python native type.

Get environment variable value.

get_casted ¶

.get_casted(key: str, default: Any = None) -> Any

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

getmany ¶

.getmany(
    prefix: str = '', 
    type_cast: bool | None = None,  # (1)!
) -> dict

Try to cast value into Python native type.

Returns a dictionary of values for keys the given prefix.

getmany_casted ¶

.getmany_casted(prefix: str = '') -> dict

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

set ¶

.set(
    key: str, 
    value: Any, 
    overwrite: bool = True,  # (1)!
)

Whether to overwrite value if it's already set.

Set environment variable.

setmany ¶

.setmany(
    key_val: dict, 
    prefix: str = '', 
    overwrite: bool = True,  # (1)!
)

Whether to overwrite value if it's already set.

Sets values in batch mode.

update_from_envfiles ¶

.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.local * .env..local

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

Testing¶

Testing(name: str = '', type_cast: bool | None = None)

Environment

Testing environment.

is_development ¶

.is_development: bool = False

Indicates whether this environment is development.

is_production ¶

.is_production: bool = False

Indicates whether this environment is production.

is_staging ¶

.is_staging: bool = False

Indicates whether this environment is staging.

type_cast ¶

.self.type_cast = type_cast or self.type_cast

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

drop ¶

.drop(key: str)

Removes key from environment.

dropmany ¶

.dropmany(
    keys: Sequence[str] | None = None,  # (1)!
    prefix: str = ''
)

Keys to drop. If not set current env keys will be used.

Drops keys in batch mode.

get ¶

.get(
    key: str, 
    default: Any = None,  # (1)!
    type_cast: bool | None = None,  # (2)!
) -> Any

Default value to return if no value found.
Try to cast value into Python native type.

Get environment variable value.

get_casted ¶

.get_casted(key: str, default: Any = None) -> Any

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

getmany ¶

.getmany(
    prefix: str = '', 
    type_cast: bool | None = None,  # (1)!
) -> dict

Try to cast value into Python native type.

Returns a dictionary of values for keys the given prefix.

getmany_casted ¶

.getmany_casted(prefix: str = '') -> dict

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

set ¶

.set(
    key: str, 
    value: Any, 
    overwrite: bool = True,  # (1)!
)

Whether to overwrite value if it's already set.

Set environment variable.

setmany ¶

.setmany(
    key_val: dict, 
    prefix: str = '', 
    overwrite: bool = True,  # (1)!
)

Whether to overwrite value if it's already set.

Sets values in batch mode.

update_from_envfiles ¶

.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.local * .env..local

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

Environment detection¶

Functions¶

get_detector¶

get_detector(cls_or_name: TypeDetectorArg) -> type[Detector]

Returns detector by alias (or class itself)

register_detector¶

register_detector(detector: type[Detector])

Registers an environment detector.

Classes¶

Environ¶

Environ(**kwargs)

Detector

Gets environment from OS environment variable.

File¶

File(**kwargs)

Detector

Gets environment from file.

Settings container¶

Classes¶

SettingsBase¶

1	`SettingsBase()`

Use this class as base for your classes containing settings.

Note

Settings are per-thread.

Every uppercase attribute of an 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:

current session value
environment value
default value

class _Settings(SettingsBase):

    ONE = 1
    SOME = 'two'
    ANOTHER = True

Settings = _Settings()

if Settings.ANOTHER:
    Settings.SOME = 'three'

get_environment¶

.get_environment() -> Optional[Environment]

Return current environment.

This could be customized by a child if required.