Quickstart¶
Basic usage¶
from envbox import get_environment
# Let's detect current environment type and get its object.
# * See and use `get_environment` function arguments to impose restrictions upon detection system.
#
# Default detection sources:
# 1. ``PYTHON_ENV`` env variable
# 2. ``environment`` file contents
#
# By default this function will also try to read env variables from .env files.
env = get_environment()
env.name
# >> development
env.is_production
# >> False
env.get('HOME')
# The same as env['HOME'] and env.HOME
# >> /home/idle/
env.getmany('PYTHON')
# {'UNBUFFERED': '1', 'IOENCODING': 'UTF-8', 'PATH': ...}
# We can also try to cast env values into Python natives.
env.getmany_casted('PYTHON')
# Note that `UNBUFFERED` is int now.
# {'UNBUFFERED': 1, 'IOENCODING': 'UTF-8', 'PATH': ...}
.env files as a source¶
You may want to put your environment vars into .env
files
(e.g.: .env
, .env.development
.env.production
)
to be read by envbox
:
MY_VAR_1 = value1
HOME = /home/other/
# comments are ignored, just as lines without definitions
# mathing quotes (" and ') are stripped
MY_QUOTED = "some quoted "
# ${VARNAME} will be replaced by value from env (if available)
MY_VAR_2 = ${MY_QUOTED}
# multiline with dangling quotes
MULTI_1 = "
line1
line2
"
# multiline classic
MULTI_2 = "line1
line2
line3"
# multiline as one line
MULTI_3 = "one\ntwo"
envbox
will try to load such files from the current working directory
for the current environment type automatically.
Settings container¶
If you need a per-thread settings storage you can do the following:
# Somewhere in your setting module declare settings:
class _Settings(SettingsBase):
ONE = 1
SOME = 'two'
ANOTHER = True
Settings = _Settings()
# Now access those settings from other modules(s).
if Settings.ANOTHER:
Settings.SOME = 'three'
Accessing any setting which was not set in the session, will lead to appropriate environment variable probing.
Environment type aliases¶
from envbox import get_environment, PRODUCTION
# Let's make `prod` string identify production environment.
register_type(PRODUCTION, alias='prod')
# Now if someone has used `prod`
# we correctly identify it as production environment.
get_environment().is_production # True
Automatic submodule import¶
envbox features import_by_environment()
function which automatically imports symbols of a submodule
of a package for the given (or detected) environment into globals of an entry-point submodule.
Note
This could be useful not only for Django-projects where submodule-based settings definition is rather usual but also for various other cases.
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 usingimport_by_environment()
.from envbox import import_by_environment current_env = import_by_environment() print(f'Environment type: {current_env}')
settings_development.py
is one of module files for certain environment (development).import_by_environment()
call insettings.py
makes symbols fromsettings_development.py
available fromsettings.py
.