API Reference¶
The __init__
module¶
The top-level module for django-environ package.
This module tracks the version of the package as well as the base package info used by various functions within django-environ.
Refer to the documentation for details on the use of this package.
- environ.__copyright__ = 'Copyright (C) 2013-2023 Daniele Faraglia'¶
The copyright notice of the package.
- environ.__version__ = '0.11.3'¶
The version of the package.
- environ.__license__ = 'MIT'¶
The license of the package.
- environ.__author__ = 'Daniele Faraglia'¶
The author of the package.
- environ.__author_email__ = 'daniele.faraglia@gmail.com'¶
The email of the author of the package.
- environ.__maintainer__ = 'Serghei Iakovlev'¶
The maintainer of the package.
- environ.__maintainer_email__ = 'egrep@protonmail.ch'¶
The email of the maintainer of the package.
- environ.__url__ = 'https://django-environ.readthedocs.org'¶
The URL of the package.
- environ.__description__ = 'A package that allows you to utilize 12factor inspired environment variables to configure your Django application.'¶
The description of the package.
The compat
module¶
This module handles import compatibility issues.
- environ.compat.REDIS_DRIVER = 'redis_cache.RedisCache'¶
The name of the RedisCache driver.
- environ.compat.DJANGO_POSTGRES = 'django.db.backends.postgresql'¶
The name of the PostgreSQL driver.
- environ.compat.PYMEMCACHE_DRIVER = 'django.core.cache.backends.memcached.PyLibMCCache'¶
The name of the Pymemcache driver.
The environ
module¶
- class environ.Env(**scheme)[source]¶
Provide scheme-based lookups of environment variables so that each caller doesn’t have to pass in
cast
anddefault
parameters.Usage::
import environ import os env = environ.Env( # set casting, default value MAIL_ENABLED=(bool, False), SMTP_LOGIN=(str, 'DEFAULT') ) # Set the project base directory BASE_DIR = os.path.dirname( os.path.dirname(os.path.abspath(__file__)) ) # Take environment variables from .env file environ.Env.read_env(os.path.join(BASE_DIR, '.env')) # False if not in os.environ due to casting above MAIL_ENABLED = env('MAIL_ENABLED') # 'DEFAULT' if not in os.environ due to casting above SMTP_LOGIN = env('SMTP_LOGIN')
- URL_CLASS¶
alias of
urllib.parse.ParseResult
- db_url(var='DATABASE_URL', default=<NoValue>, engine=None)[source]¶
Returns a config dictionary, defaulting to DATABASE_URL.
The db method is an alias for db_url.
- Return type
- db(var='DATABASE_URL', default=<NoValue>, engine=None)¶
Returns a config dictionary, defaulting to DATABASE_URL.
The db method is an alias for db_url.
- Return type
- cache_url(var='CACHE_URL', default=<NoValue>, backend=None)[source]¶
Returns a config dictionary, defaulting to CACHE_URL.
The cache method is an alias for cache_url.
- Return type
- cache(var='CACHE_URL', default=<NoValue>, backend=None)¶
Returns a config dictionary, defaulting to CACHE_URL.
The cache method is an alias for cache_url.
- Return type
- email_url(var='EMAIL_URL', default=<NoValue>, backend=None)[source]¶
Returns a config dictionary, defaulting to EMAIL_URL.
The email method is an alias for email_url.
- Return type
- email(var='EMAIL_URL', default=<NoValue>, backend=None)¶
Returns a config dictionary, defaulting to EMAIL_URL.
The email method is an alias for email_url.
- Return type
- search_url(var='SEARCH_URL', default=<NoValue>, engine=None)[source]¶
Returns a config dictionary, defaulting to SEARCH_URL.
- Return type
- get_value(var, cast=None, default=<NoValue>, parse_default=False)[source]¶
Return value for given environment variable.
- Parameters
var (str) – Name of variable.
cast (collections.abc.Callable or None) – Type to cast return value as.
default – If var not present in environ, return this instead.
parse_default (bool) – Force to parse default.
- Returns
Value from environment or default (if set).
- Return type
- classmethod parse_value(value, cast)[source]¶
Parse and cast provided value
- Parameters
value – Stringed value.
cast – Type to cast return value as.
- Returns
Casted value
- classmethod db_url_config(url, engine=None)[source]¶
Parse an arbitrary database URL.
Supports the following URL schemas:
PostgreSQL:
postgres[ql]?://
orp[g]?sql://
PostGIS:
postgis://
MySQL:
mysql://
ormysql2://
MySQL (GIS):
mysqlgis://
MySQL Connector Python from Oracle:
mysql-connector://
SQLite:
sqlite://
SQLite with SpatiaLite for GeoDjango:
spatialite://
Oracle:
oracle://
Microsoft SQL Server:
mssql://
PyODBC:
pyodbc://
Amazon Redshift:
redshift://
LDAP:
ldap://
- Parameters
url (urllib.parse.ParseResult or str) – Database URL to parse.
engine (str or None) – If None, the database engine is evaluates from the
url
.
- Returns
Parsed database URL.
- Return type
- classmethod cache_url_config(url, backend=None)[source]¶
Parse an arbitrary cache URL.
- Parameters
url (urllib.parse.ParseResult or str) – Cache URL to parse.
backend (str or None) – If None, the backend is evaluates from the
url
.
- Returns
Parsed cache URL.
- Return type
- classmethod email_url_config(url, backend=None)[source]¶
Parse an arbitrary email URL.
- Parameters
url (urllib.parse.ParseResult or str) – Email URL to parse.
backend (str or None) – If None, the backend is evaluates from the
url
.
- Returns
Parsed email URL.
- Return type
- classmethod search_url_config(url, engine=None)[source]¶
Parse an arbitrary search URL.
- Parameters
url (urllib.parse.ParseResult or str) – Search URL to parse.
engine (str or None) – If None, the engine is evaluates from the
url
.
- Returns
Parsed search URL.
- Return type
- classmethod read_env(env_file=None, overwrite=False, parse_comments=False, encoding='utf8', **overrides)[source]¶
Read a .env file into os.environ.
If not given a path to a dotenv path, does filthy magic stack backtracking to find the dotenv in the same directory as the file that called
read_env
.Existing environment variables take precedent and are NOT overwritten by the file content.
overwrite=True
will force an overwrite of existing environment variables.Refs:
- Parameters
env_file – The path to the
.env
file your application should use. If a path is not provided,read_env
will attempt to import the Django settings module from the Django project root.overwrite –
overwrite=True
will force an overwrite of existing environment variables.parse_comments – Determines whether to recognize and ignore inline comments in the .env file. Default is False.
encoding – The encoding to use when reading the environment file.
**overrides – Any additional keyword arguments provided directly to read_env will be added to the environment. If the key matches an existing environment variable, the value will be overridden.
- class environ.FileAwareEnv(**scheme)[source]¶
First look for environment variables with
_FILE
appended. If found, their contents will be read from the file system and used instead.Use as a drop-in replacement for the standard
environ.Env
:python env = environ.FileAwareEnv()
For example, if a
SECRET_KEY_FILE
environment variable was set,env("SECRET_KEY")
would find the related variable, returning the file contents rather than ever looking up aSECRET_KEY
environment variable.
- class environ.Path(start='', *paths, **kwargs)[source]¶
Inspired to Django Two-scoops, handling File Paths in Settings.
- path(*paths, **kwargs)[source]¶
Create new Path based on self.root and provided paths.
- Parameters
paths – List of sub paths
kwargs – required=False
- Return type
- property root¶
Current directory for this Path
The fileaware_mapping
module¶
- class environ.fileaware_mapping.FileAwareMapping(env=None, cache=True)[source]¶
A mapping that wraps os.environ, first checking for the existence of a key appended with
_FILE
whenever reading a value. If a matching file key is found then the value is instead read from the file system at this location.By default, values read from the file system are cached so future lookups do not hit the disk again.
A
_FILE
key has higher precedence than a value is set directly in the environment, and an exception is raised if the file can not be found.