python-environ 0.4.54

Description:

pythonenviron 0.4.54

Django-environ

django-environ allows you to use Twelve-factor methodology to configure your Django application with environment variables.

import environ
env = environ.Env(
# set casting, default value
DEBUG=(bool, False)
)
# reading .env file
environ.Env.read_env()

# False if not in os.environ
DEBUG = env('DEBUG')

# Raises django's ImproperlyConfigured exception if SECRET_KEY not in os.environ
SECRET_KEY = env('SECRET_KEY')

# Parse database connection url strings like psql://user:[email protected]:8458/db
DATABASES = {
# read os.environ['DATABASE_URL'] and raises ImproperlyConfigured exception if not found
'default': env.db(),
# read os.environ['SQLITE_URL']
'extra': env.db('SQLITE_URL', default='sqlite:////tmp/my-tmp-sqlite.db')
}

CACHES = {
# read os.environ['CACHE_URL'] and raises ImproperlyConfigured exception if not found
'default': env.cache(),
# read os.environ['REDIS_URL']
'redis': env.cache('REDIS_URL')
}
See the similar code, sans django-environ.
_ _ _
| (_) (_)
__| |_ __ _ _ __ __ _ ___ ______ ___ _ ____ ___ _ __ ___ _ __
/ _` | |/ _` | '_ \ / _` |/ _ \______/ _ \ '_ \ \ / / | '__/ _ \| '_ \
| (_| | | (_| | | | | (_| | (_) | | __/ | | \ V /| | | | (_) | | | |
\__,_| |\__,_|_| |_|\__, |\___/ \___|_| |_|\_/ |_|_| \___/|_| |_|
_/ | __/ |
|__/ |___/
The idea of this package is to unify a lot of packages that make the same stuff:
Take a string from os.environ, parse and cast it to some of useful python typed variables.
To do that and to use the 12factor approach, some connection strings are expressed as url,
so this package can parse it and return a urllib.parse.ParseResult.
These strings from os.environ are loaded from a .env file and filled in os.environ with setdefault method,
to avoid to overwrite the real environ.
A similar approach is used in Two Scoops of Django book and explained in 12factor-django article.
Using django-environ you can stop to make a lot of unversioned settings_*.py to configure your app.
See cookiecutter-django for a concrete example on using with a django project.

Feature Support

Fast and easy multi environment for deploy
Fill os.environ with .env file variables
Variables casting (see supported_types below)
Url variables exploded to django specific package settings

Django-environ officially supports Django 1.8 ~ 2.0.


Installation
$ pip install django-environ
NOTE: No need to add it to INSTALLED_APPS.
Then create a .env file:
DEBUG=on
SECRET_KEY=your-secret-key
DATABASE_URL=psql://user:[email protected]:8458/database
SQLITE_URL=sqlite:///my-local-sqlite.db
CACHE_URL=memcache://127.0.0.1:11211,127.0.0.1:11212,127.0.0.1:11213
REDIS_URL=rediscache://127.0.0.1:6379/1?client_class=django_redis.client.DefaultClient&password=ungithubbed-secret
And use it with settings.py above.
Don’t forget to add .env in your .gitignore (tip: add .env.example with a template of your variables).


Documentation
Documentation is available at RTFD.


Supported types

str
bool
int
float
json
list (FOO=a,b,c)
tuple (FOO=(a,b,c))
dict (BAR=key=val,foo=bar) #environ.Env(BAR=(dict, {}))
dict (BAR=key=val;foo=1.1;baz=True) #environ.Env(BAR=(dict(value=unicode, cast=dict(foo=float,baz=bool)), {}))
url
path (environ.Path)

db_url

PostgreSQL: postgres://, pgsql://, psql:// or postgresql://
PostGIS: postgis://
MySQL: mysql:// or mysql2://
MySQL for GeoDjango: mysqlgis://
Mysql Connector Python from Oracle: mysql-connector://
SQLITE: sqlite://
SQLITE with SPATIALITE for GeoDjango: spatialite://
Oracle: oracle://
MSSQL: mssql://
PyODBC: pyodbc://
Redshift: redshift://
LDAP: ldap://





cache_url

Database: dbcache://
Dummy: dummycache://
File: filecache://
Memory: locmemcache://
Memcached: memcache://
Python memory: pymemcache://
Redis: rediscache://, redis://, or rediss://





search_url

ElasticSearch: elasticsearch://
Solr: solr://
Whoosh: whoosh://
Xapian: xapian://
Simple cache: simple://





email_url

SMTP: smtp://
SMTP+SSL: smtp+ssl://
SMTP+TLS: smtp+tls://
Console mail: consolemail://
File mail: filemail://
LocMem mail: memorymail://
Dummy mail: dummymail://







Tips

Using unsafe characters in URLs
In order to use unsafe characters you have to encode with urllib.parse.encode before you set into .env file.
DATABASE_URL=mysql://user:%[email protected]:3306/dbname
See https://perishablepress.com/stop-using-unsafe-characters-in-urls/ for reference.


Smart Casting
django-environ has a “Smart-casting” enabled by default, if you don’t provide a cast type, it will be detected from default type.
This could raise side effects (see #192).
To disable it use env.smart_caset = False.
New major release will disable it as default.


Multiple redis cache locations
For redis cache, multiple master/slave or shard locations can be configured as follows:
CACHE_URL='rediscache://master:6379,slave1:6379,slave2:6379/1'


Email settings
In order to set email configuration for django you can use this code:
EMAIL_CONFIG = env.email_url(
'EMAIL_URL', default='smtp://user:password@localhost:25')

vars().update(EMAIL_CONFIG)


SQLite urls
SQLite connects to file based databases. The same URL format is used, omitting the hostname,
and using the “file” portion as the filename of the database.
This has the effect of four slashes being present for an absolute
file path: sqlite:////full/path/to/your/database/file.sqlite.



Nested lists
Some settings such as Django’s ADMINS make use of nested lists. You can use something like this to handle similar cases.
# DJANGO_ADMINS=John:[email protected],Jane:[email protected]
ADMINS = [x.split(':') for x in env.list('DJANGO_ADMINS')]

# or use more specific function

from email.utils import getaddresses

# DJANGO_ADMINS=Full Name <[email protected]>,[email protected]
ADMINS = getaddresses([env('DJANGO_ADMINS')])


Multiline value
You can set a multiline variable value:
# MULTILINE_TEXT=Hello\\nWorld
>>> print env.str('MULTILINE_TEXT', multiline=True)
Hello
World


Proxy value
You can set a value prefixed by $ to use as a proxy to another variable value:
# BAR=FOO
# PROXY=$BAR
>>> print env.str('PROXY')
FOO


Multiple env files
It is possible to have multiple env files and select one using environment variables.
env = environ.Env()
env.read_env(env.str('ENV_PATH', '.env'))
Now ENV_PATH=other-env ./manage.py runserver uses other-env while ./manage.py runserver uses .env.



Tests
$ git clone [email protected]:joke2k/django-environ.git
$ cd django-environ/
$ python setup.py test

How to Contribute

Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug. There is a Contributor Friendly tag for issues that should be ideal for people who are not very familiar with the codebase yet.
Fork the repository on GitHub to start making your changes to the develop branch (or branch off of it).
Write a test which shows that the bug was fixed or that the feature works as expected.
Send a pull request and bug the maintainer until it gets merged and published. :) Make sure to add yourself to Authors file.



License
This project is licensed under the MIT License - see the License file file for details


Changelog
See the Changelog file which format is inspired by Keep a Changelog.


Credits

See Authors file
12factor
12factor-django
Two Scoops of Django
rconradharris / envparse
migonzalvar / dj-email-url
ghickman / django-cache-url
dstufft / dj-search-url
julianwachholz / dj-config-url
nickstenning / honcho
rconradharris / envparse
Distribute
modern-package-template



Contributors
Thank you to all the people who have already contributed.



Backers
Thank you to all our backers!



Sponsors
Support this project by becoming a sponsor. Your logo will show up here with a link to your website. Became sponsor.