django-environ-plus

=================== django-environ-plus

django-environ is the Python package that allows you to use Twelve-factor methodology <https://www.12factor.net/>_ to configure your Django application with environment variables.

.. -teaser-end-

For that, it gives you an easy way to configure Django application using environment variables obtained from an environment file and provided by the OS:

.. -code-begin-

.. code-block:: python

import environ import os

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

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 because of casting above

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:pass@127.0.0.1:8458/db

DATABASES = { # read os.environ['DATABASE_URL'] and raises # ImproperlyConfigured exception if not found # # The db() method is an alias for db_url(). 'default': env.db(),

   # read os.environ['SQLITE_URL']
   'extra': env.db_url(
       'SQLITE_URL',
       default='sqlite:////tmp/my-tmp-sqlite.db'
   )

}

CACHES = { # Read os.environ['CACHE_URL'] and raises # ImproperlyConfigured exception if not found. # # The cache() method is an alias for cache_url(). 'default': env.cache(),

   # read os.environ['REDIS_URL']
   'redis': env.cache_url('REDIS_URL')

}

.. -overview-

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 <https://www.12factor.net/>_ 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 <https://www.feldroy.com/books/two-scoops-of-django-3-x>_ book and explained in 12factor-django <https://wellfire.co/learn/easier-12-factor-django>_ article.

Using django-environ you can stop to make a lot of unversioned settings_*.py to configure your app. See cookiecutter-django <https://github.com/cookiecutter/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
• Url variables exploded to django specific package settings
• Optional support for Docker-style file based config variables (use environ.FileAwareEnv instead of environ.Env)

.. -project-information-

Project Information

django-environ is released under the MIT / X11 License <https://choosealicense.com/licenses/mit/>__, its documentation lives at Read the Docs <https://django-environ.readthedocs.io/en/latest/>, the code on GitHub <https://github.com/joke2k/django-environ>, and the latest release on PyPI <https://pypi.org/project/django-environ/>_.

It’s rigorously tested on Python 3.5+, and officially supports Django 1.11, 2.2, 3.0, 3.1, 3.2 and 4.0.

If you'd like to contribute to django-environ you're most welcome!

.. -support-

Support

Should you have any question, any remark, or if you find a bug, or if there is something you can't do with the django-environ, please open an issue <https://github.com/joke2k/django-environ>_.

Contributing

If you would like to contribute to django-environ, please take a look at the current issues <https://github.com/joke2k/django-environ/issues>_. If there is a bug or feature that you want but it isn't listed, make an issue and work on it.

How to Contribute

• Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug.
• Fork the repository <https://github.com/joke2k/django-environ>_ 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.

Release Information

v0.9.0 - 15-June-2022

Added +++++

• Added support for Postgresql cluster URI #355 <https://github.com/joke2k/django-environ/pull/355>_.
• Added support for Django 4.0 #371 <https://github.com/joke2k/django-environ/issues/371>_.
• Added support for prefixed variables #362 <https://github.com/joke2k/django-environ/issues/362>_.
• Amended documentation.

Deprecated ++++++++++

• Env.unicode() is deprecated and will be removed in the next major release. Use Env.str() instead.

Changed +++++++

• Attach cause to ImproperlyConfigured exception #360 <https://github.com/joke2k/django-environ/issues/360>_.

Fixed +++++

• Fixed _cast_urlstr unquoting #357 <https://github.com/joke2k/django-environ/issues/357>_.
• Fixed documentation regarding unsafe characters in URLs #220 <https://github.com/joke2k/django-environ/issues/220>_.
• Fixed environ.Path.__eq__() to compare paths correctly #86 <https://github.com/joke2k/django-environ/issues/86>, #197 <https://github.com/joke2k/django-environ/issues/197>.

Full changelog <https://django-environ.readthedocs.org/en/latest/changelog.html>_.

Security Policy

Reporting a Vulnerability

If you discover a security vulnerability within django-environ, please send an e-mail to Serghei Iakovlev via [e-mail]. All security vulnerabilities will be promptly addressed.

Credits

django-environ was initially created by Daniele Faraglia <https://github.com/joke2k>_ and currently maintained by Serghei Iakovlev <https://github.com/sergeyklay/>_.

A full list of contributors can be found in GitHub <https://github.com/joke2k/django-environ/graphs/contributors>__.

Acknowledgments

The existence of django-environ would have been impossible without these projects:

• rconradharris/envparse <https://github.com/rconradharris/envparse>_
• jazzband/dj-database-url <https://github.com/jazzband/dj-database-url>_
• migonzalvar/dj-email-url <https://github.com/migonzalvar/dj-email-url>_
• ghickman/django-cache-url <https://github.com/ghickman/django-cache-url>_
• dstufft/dj-search-url <https://github.com/dstufft/dj-search-url>_
• julianwachholz/dj-config-url <https://github.com/julianwachholz/dj-config-url>_
• nickstenning/honcho <https://github.com/nickstenning/honcho>_
• rconradharris/envparse <https://github.com/rconradharris/envparse>_