This is a pre-production deployment of Warehouse, however changes made here WILL affect the production instance of PyPI.
Latest Version Dependencies status unknown Test status unknown Test coverage unknown
Project Description

One-stop shop for configuring 12-factor Django apps

  • Simple API for getting settings from environment variables.
  • Supports wide variety of email, cache and database backends.
  • Easily customisable and extensible.
  • One line auto-config for many Heroku add-ons.

Basic Settings

In your Django project’s settings.py:

import envsettings

SECRET_KEY = envsettings.get('DJANGO_SECRET_KEY', 'development_key_not_a_secret')

# Accepts the strings "True" and "False"
DEBUG = envsettings.get_bool('DJANGO_DEBUG', default=True)

FILE_UPLOAD_MAX_MEMORY_SIZE = envsettings.get_int('MAX_UPLOAD_SIZE', default=2621440)

Email Settings

Because of the way Django’s email settings work, this requires a bit of a hack with locals():

import envsettings

locals().update(
    envsettings.email.get('MAIL_URL', default='file:///dev/stdout'))

This sets EMAIL_BACKEND and whatever other values are needed to configure the selected backend.

Example URLs

Standard SMTP backend:

# SMTP without TLS
smtp://username:password@host.example.com:25
# SMTP with TLS
smtps://username:password@host.example.com:587

Special Django backends for use in development:

# Console backend
file:///dev/stdout

# Dummy packend
file:///dev/null

# File-based backend
file:///path/to/output/dir

Proprietary backends (each requires the appropriate package installed):

# Requires `django-mailgun`
mailgun://api:api_key@my-sending-domain.com

# Requires `sendgrid-django`
sendgrid://username:password@sendgrid.com

# Requires `djrill`
mandrill://:api_key@mandrillapp.com
mandrill://subaccount_name:api_key@mandrillapp.com

# Requires `django-ses-backend`
ses://access_key_id:access_key@us-east-1
ses://access_key_id:access_key@email.eu-west-1.amazonaws.com

# Requires `django-postmark`
postmark://api:api_key@postmarkapp.com

Heroku Auto-Config

Pass auto_config=True like so:

locals().update(
    envsettings.email.get(default='file:///dev/stdout', auto_config=True))

This will automatically detect and configure any of the following Heroku email add-ons: Mailgun, Sendgrid, Mandrill, Postmark.

So, for instance, you can configure your app to send email via Mailgun simply by running:

heroku addons:add mailgun:starter

By default it will use each provider’s SMTP endpoint, however if it detects that the appropriate backend is installed (see list above) it will configure Django to use the HTTP endpoint which will be faster.

Cache Settings

import envsettings

CACHES = {'default': envsettings.cache.get('CACHE_URL', 'locmem://')}

Example URLs

Django backends for use in development:

# Local memory
locmem://
# Local memory with prefix
locmem://some-prefix

# File based
file:///path/to/cache/directory

# Dummy cache
file:///dev/null

Redis (requires django-redis package):

# Basic Redis configuration
redis://example.com:6379
# With password
redis://:secret@example.com:6379
# Specifying database number
redis://example.com:6379/3
# Using UNIX socket
redis:///path/to/socket
# Using UNIX socket with password and database number
redis://:secret@/path/to/socket:3

To use Memcached you need one of the following packages installed: django_pylibmc, django_bmemcached, pylibmc, mecached

Only django_pylibmc and django_bmemcachd support authentication and the memcached binary protocol, so if you want to use either of these featues you’ll need one of those packages.

# Basic Memcached configuration
memcached://example.com:11211
# Multiple servers
memcached://example.com:11211,another.com:11211,onemore.com:11211
# With authentication
memcached://username:password@example.com
# Using the binary protocol
memcached-binary://example.com:11211

Heroku Auto-Config

Pass auto_config=True like so:

CACHES = {'default': envsettings.cache.get(default='locmen://', auto_config=True)}

This will automatically detect and configure any of the following Heroku cache add-ons: Memcachier, MemcachedCloud, RedisToGo, RedisCloud, OpenRedis, RedisGreen.

Customising & Extending

Django EnvSettings is designed to be easily extensible by subclassing one of the existing settings providers: CacheSettings, EmailSettings, or DatabaseSettings.

Changing default configuration

Obviously you can modify the configuration dictionary after it’s returned from envsettings. However you can also set default values for each backend, while letting the environment determine which backend to use. For example:

envsettings.database.CONFIG['postgres']['OPTIONS'] = {
    'isolation_level': psycopg2.extensions.ISOLATION_LEVEL_SERIALIZABLE}

Supporting new backends

To add a new backend, subclass the appropriate settings class. You will then need to add a key to the CONFIG dictionary which maps the URL scheme you want to use for your backend to the default config for that backend. You will also need to add a method named handle_<URL_SCHEME>_url which will be passed the output from urlparse and the default config. The method should use the values from the parsed URL to update the config appropriately.

For example:

import envsettings

class CacheSettings(envsettings.CacheSettings):

    CONFIG = dict(envsettings.CacheSettings.CONFIG, **{
        'my-proto': {'BACKEND': 'my_cache_backend.MyCacheBackend'}
    })

    def handle_my_proto_url(self, parsed_url, config):
        config['HOST'] = parsed_url.hostname or 'localhost'
        config['PORT'] = parsed_url.port or 9000
        config['USERNAME'] = parsed_url.username
        config['PASSWORD'] = parsed_url.password
        return config

cachesettings = CacheSettings()

CACHES = {'default': cachesettings.get('CACHE_URL')}

Supporting new auto configuration options

To add a new auto-configuration provider, subclass the appropriate settings class and add a method named auto_config_<PROVIDER_NAME>. This will be passed a dictionary of environment variables and should return either an appropriate configuration URL, or None.

The auto config methods are tried in lexical order, so if you want to force a method to be tried first you could call it auto_config_00_my_provider, or something like that.

Here’s an example:

import envsettings

class CacheSettings(envsettings.CacheSettings):

    def auto_config_my_redis(self, env):
        try:
            host = env['MY_REDIS_HOST']
            password = env['MY_REDIS_PASSWORD']
        except KeyError:
            return None
        else:
            return 'redis://:{password}@{host}'.format(
                host=host, password=password)

cachesettings = CacheSettings()

CACHES = {'default': cachesettings.get('CACHE_URL', auto_config=True)}

Compatibility

Tested on Python 2.7, 3.3, 3.4 and PyPy, with Django versions 1.41.7

Issues & Contributing

Raise an issue on the GitHub project or feel free to nudge @_EvansD on Twitter.

License

MIT Licensed

Release History

Release History

1.1.0

This version

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

1.0

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

0.1

History Node

TODO: Figure out how to actually get changelog content.

Changelog content for this version goes here.

Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue. Nam tincidunt congue enim, ut porta lorem lacinia consectetur. Donec ut libero sed arcu vehicula ultricies a non tortor. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Show More

Download Files

Download Files

TODO: Brief introduction on what you do with files - including link to relevant help section.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
django_envsettings-1.1.0-py2.py3-none-any.whl (13.3 kB) Copy SHA256 Checksum SHA256 2.7 Wheel Aug 20, 2015
django-envsettings-1.1.0.tar.gz (12.6 kB) Copy SHA256 Checksum SHA256 Source Aug 20, 2015

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS HPE HPE Development 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