This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (pypi.python.org).
Help us improve Python packaging - Donate today!

Django-environ allows you to utilize 12factor inspired environment variables to configure your Django application.

Project Description

Django-environ allows you to utilize 12factor inspired environment variables to configure your Django application.

This module is a merge of:

and inspired by:

This is your settings.py file before you have installed django-environ

import os
SITE_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.realpath(__file__))))

DEBUG = True
TEMPLATE_DEBUG = DEBUG

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql_psycopg2',
        'NAME': 'database',
        'USER': 'user',
        'PASSWORD': 'githubbedpassword',
        'HOST': '127.0.0.1',
        'PORT': '8458',
    },
    'extra': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': os.path.join(SITE_ROOT, 'database.sqlite')
    }
}

MEDIA_ROOT = os.path.join(SITE_ROOT, 'assets')
MEDIA_URL = 'media/'
STATIC_ROOT = os.path.join(SITE_ROOT, 'static')
STATIC_URL = 'static/'

SECRET_KEY = '...im incredibly still here...'

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.memcached.MemcachedCache',
        'LOCATION': [
            '127.0.0.1:11211', '127.0.0.1:11212', '127.0.0.1:11213',
        ]
    },
    'redis': {
        'BACKEND': 'django_redis.cache.RedisCache',
        'LOCATION': '127.0.0.1:6379/1',
        'OPTIONS': {
            'CLIENT_CLASS': 'django_redis.client.DefaultClient',
            'PASSWORD': 'redis-githubbed-password',
        }
    }
}

After:

import environ
root = environ.Path(__file__) - 3 # three folder back (/a/b/c/ - 3 = /)
env = environ.Env(DEBUG=(bool, False),) # set default values and casting
environ.Env.read_env() # reading .env file

SITE_ROOT = root()

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

DATABASES = {
    'default': env.db(), # Raises ImproperlyConfigured exception if DATABASE_URL not in os.environ
    'extra': env.db('SQLITE_URL', default='sqlite:////tmp/my-tmp-sqlite.db')
}

public_root = root.path('public/')

MEDIA_ROOT = public_root('media')
MEDIA_URL = 'media/'
STATIC_ROOT = public_root('static')
STATIC_URL = 'static/'

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

CACHES = {
    'default': env.cache(),
    'redis': env.cache('REDIS_URL')
}

You can also pass read_env() an explicit path to the .env file.

Create a .env file:

DEBUG=on
# DJANGO_SETTINGS_MODULE=myapp.settings.dev
SECRET_KEY=your-secret-key
DATABASE_URL=psql://urser:un-githubbedpassword@127.0.0.1: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=redis-un-githubbed-password

How to install

$ pip install django-environ

How to use

There are only two classes, environ.Env and environ.Path

>>> import environ
>>> env = environ.Env(
        DEBUG=(bool, False),
    )
>>> env('DEBUG')
False
>>> env('DEBUG', default=True)
True

>>> open('.myenv', 'a').write('DEBUG=on')
>>> environ.Env.read_env('.myenv') # or env.read_env('.myenv')
>>> env('DEBUG')
True

>>> open('.myenv', 'a').write('\nINT_VAR=1010')
>>> env.int('INT_VAR'), env.str('INT_VAR')
1010, '1010'

>>> open('.myenv', 'a').write('\nDATABASE_URL=sqlite:///my-local-sqlite.db')
>>> env.read_env('.myenv')
>>> env.db()
{'ENGINE': 'django.db.backends.sqlite3', 'NAME': 'my-local-sqlite.db', 'HOST': '', 'USER': '', 'PASSWORD': '', 'PORT': ''}

>>> root = env.path('/home/myproject/')
>>> root('static')
'/home/myproject/static'

See cookiecutter-django for a concrete example on using with a django project.

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://
    • SQLITE: sqlite://
    • SQLITE with SPATIALITE for GeoDjango: spatialite://
    • Oracle: oracle://
    • Redshift: redshift://
    • LDAP: ldap://
  • cache_url
    • Database: dbcache://
    • Dummy: dummycache://
    • File: filecache://
    • Memory: locmemcache://
    • Memcached: memcache://
    • Python memory: pymemcache://
    • Redis: rediscache://
  • 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:%23password@127.0.0.1:3306/dbname

See https://perishablepress.com/stop-using-unsafe-characters-in-urls/ for reference.

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.

Tests

$ git clone git@github.com:joke2k/django-environ.git
$ cd django-environ/
$ python setup.py test

License

Django-environ is licensed under the MIT License - see the LICENSE_FILE file for details

Changelog

0.4.2 - 13-April-2017

  • Confirm support for Django 1.11.
  • Support for Redshift database URL
  • Fix uwsgi settings reload problem (#55)
  • Update support for django-redis urls (#109)

0.4.1 - 13-November-2016

  • Fix for unsafe characters into URLs
  • Clarifying warning on missing or unreadable file. Thanks to @nickcatal
  • Add support for Django 1.10.
  • Fix support for Oracle urls
  • Fix support for django-redis

0.4.0 - 23-September-2015

  • Fix non-ascii values (broken in Python 2.x)
  • New email schemes - smtp+ssl and smtp+tls (smtps would be deprecated)
  • redis_cache replaced by django_redis
  • Add tuple support. Thanks to @anonymouzz
  • Add LDAP url support for database (django-ldapdb)
  • Fix psql/pgsql url

0.3 - 03-June-2014

  • Add cache url support
  • Add email url support
  • Add search url support
  • Rewriting README.rst

0.2.1 19-April-2013

  • environ/environ.py: Env.__call__ now uses Env.get_value instance method

0.2 16-April-2013

  • environ/environ.py, environ/test.py, environ/test_env.txt: add advanced float parsing (comma and dot symbols to separate thousands and decimals)
  • README.rst, docs/index.rst: fix TYPO in documentation

0.1 02-April-2013

  • initial release
Release History

Release History

This version
History Node

0.4.3

History Node

0.4.2

History Node

0.4.1

History Node

0.4.0

History Node

0.3.1

History Node

0.3.0

History Node

0.2.1

History Node

0.2

History Node

0.1

Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
django_environ-0.4.3-py2.py3-none-any.whl (25.7 kB) Copy SHA256 Checksum SHA256 3.5 Wheel Apr 19, 2017
django-environ-0.4.3.tar.gz (24.0 kB) Copy SHA256 Checksum SHA256 Source Apr 19, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting