Description

============== django-environ ============== ``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/two-scoops-of-django>`_ book and explained in `12factor-django <https://dev.to/ale_jacques/django-drf-12-factor-app-with-examples-36jg>`_ 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.9+, and officially supports Django 2.2, 3.0, 3.1, 3.2, 4.0, 4.1, 4.2, 5.0, 5.1, 5.2, and 6.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. Bug reports ----------- *Before raising an issue, please ensure that you are using the latest version of django-environ.* Please provide the following information with your issue to enable us to respond as quickly as possible. * The relevant versions of the packages you are using. * The steps to recreate your issue. * The full stacktrace if there is an exception. * An executable code example where possible Guidelines for bug reports: * **Use the GitHub issue search** — check if the issue has already been reported. * **Check if the issue has been fixed** — try to reproduce it using the latest ``main`` or ``develop`` branch in the repository. * Isolate the problem — create a reduced test case and a live example. A good bug report shouldn't leave others needing to chase y