Basic

Read the settings contained in ./.env into os.environ:

from speckenv import read_speckenv

read_speckenv()

Note that read_speckenv uses os.environ.setdefault to set new values, which means that if a particular key exists more than once in the file the first value is retained, not the last.

If the file is named differently or resides in a different path, pass the full path as first argument to read_speckenv.

Read individual values:

from speckenv import env

# Standard usage:
SETTING1 = env("SETTING1")

# Fallback if SETTING2 does not exist:
SETTING2 = env("SETTING2", default="bla")

# Fail hard if missing:
SETTING3 = env("SETTING3", required=True)

# Coerce the value before returning it (coercion is also applied to
# default values):
SETTING4 = env(
    "SETTING4",
    coerce=lambda value: date(*(int(part) for part in value.split("-"))),
    default="1970-01-01",
)

The following values are evaluated as Python literals, therefore coercing values may be useful less often than you might think:

BOOL=True  # And False, None etc.
NUMBER=42
SWEET_HOME=["localhost", "127.0.0.1"]

Additional whitespace around the equals sign is supported. Empty lines and lines starting with a # are ignored:

THIS_IS_IGNORED
# COMMENTED_OUT=VALUE
THIS = WORKS

You shouldn’t use comments in lines though. They sometimes work by accident but it’s a bad idea.

If a value looks like a Python type but you want to load it as a string you have to add quote characters (" or ') around the value or use coercion, e.g.

NUMBER_AS_STRING = env("NUMBER", coerce=str)

# Alternatively, read the value directly from os.environ:
NUMBER_AS_STRING = os.environ["NUMBER"]

Custom mapping instead of os.environ

It may be useful to use a mapping separate from os.environ. This is easily possible by overriding the default mapping argument:

from speckenv import env, read_speckenv

mapping = {}
read_speckenv("file_with_variables.env", mapping=mapping)
setting1 = env("SETTING1", mapping=mapping)

django_cache_url

Covers configuring a Redis, locmem or dummy cache backend with optional authentication credentials. The Redis configuration only supports Django 4 or better. redis:// and hiredis:// are equivalent since recent enough versions of redis-py automatically select the hiredis parser if it is available.

from speckenv import env
from speckenv_django import django_cache_url

# CACHE_URL=hiredis://localhost:6379/1/?key_prefix=example_com"
CACHES = {"default": django_cache_url(env("CACHE_URL", default="locmem://"))}
# NOTE! locmem:// may be a bad default, but that's up to you really.

django_database_url

Covers configuring a PostgreSQL, PostGIS or sqlite database engine with authentication credentials.

from speckenv import env
from speckenv_django import django_database_url

# DATABASE_URL=postgres://localhost:5432/example_com
DATABASES = {"default": django_database_url(env("DATABASE_URL", required=True))}

django_email_url

Covers configuring an email backend. Known backends are smtp://, submission:// (same as smtp:// but with TLS and a default port of 587), locmem://, console:// and dummy:.

The utility also supports explicitly requesting SSL (?ssl=true), TLS (?tls=true), SMTP timeouts (?timeout=10), setting a DEFAULT_FROM_EMAIL address (?_default_from_email=info@example.com) and setting a SERVER_EMAIL address (?_server_email=info@example.com). Note that since Django uses individual variables instead of a dictionary you have to pass the return value to globals().update().

from speckenv import env
from speckenv_django import django_email_url

# EMAIL_URL=smtp://
if DEBUG:
    globals().update(django_email_url(env("EMAIL_URL", default="console://")))
else:
    globals().update(django_email_url(env("EMAIL_URL", default="smtp://")))

Django 6.1 deprecated the individual EMAIL_* settings in favor of the MAILERS dictionary; use django_mailer_url below instead when you’re using Django 6.1 or better.

django_mailer_url

Returns an entry for the MAILERS dictionary introduced in Django 6.1. Supports the same URLs as django_email_url, and additionally accepts ?ssl_keyfile=... and ?ssl_certfile=.... SERVER_EMAIL isn’t a part of a mailer’s configuration, so _server_email raises a ValueError. _default_from_email is passed on as a default_from_email option; Django’s own backends reject it, but custom backends may support it. Use the backend keyword argument to select such a backend, e.g. django_mailer_url(url, backend="email_hosts.backends.EmailHostsBackend").

from speckenv import env
from speckenv_django import django_mailer_url

# MAILER_URL=submission://user:password@smtp.example.com
MAILERS = {
    "default": django_mailer_url(
        env("MAILER_URL", default="console://" if DEBUG else "smtp://")
    )
}
DEFAULT_FROM_EMAIL = env("DEFAULT_FROM_EMAIL", default="webmaster@localhost")