==============
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/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.6+, and officially supports
Django 1.11, 2.2, 3.0, 3.1, 3.2, 4.0, 4.1 and 4.2.
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 you up for more
information. Please try to be as detailed as possible in your report. What is
your environment? What steps will reproduce the issue? What OS experience the
problem? What would you expect to be the outcome? All these details will help
people to fix any potential bugs.
Feature requests
----------------
Feature requests are welcome. But take a moment to find out whether your idea
fits with the scope and aims of the project. It's up to *you* to make a strong
case to convince the project's developers of the merits of this feature. Please
provide as much detail and context as possible.
Pull requests
-------------
Good pull requests - patches, improvements, new features - are a fantastic
help. They should remain focused in scope and avoid containing unrelated
commits.
Follow this process if you'd like your work considered for inclusion in the
project:
1. Check for open issues or open a fresh issue to start a discussion around a
feature idea or a bug.
2. 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).
3. Write a test which shows that the bug was fixed or that the feature works as
expected.
4. Send a pull request and bug the maintainer until it gets merged and published.
If you are intending to implement a fairly large feature we'd appreciate if you
open an issue with GitHub detailing your use case and intended solution to
discuss how it might impact other work that is in flight.
We also appreciate it if you take the time to update and write tests for any
changes you submit.
**By submitting a patch, you agree to allow the project owner to license your
work under the same license as that used by the project.**
Resources
---------
* `How to Contribute to Open Source <https://opensource.guide/how-to-contribute/>`_
* `Using Pull Requests <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests>`_
* `Writing good commit messages <https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html>`_
Release Information
===================
v0.11.2 - 1-September-2023
-------------------------------
Fixed
+++++
- Revert "Add variable expansion." feature
due to `#490 <https://github.com/joke2k/django-environ/issues/490>`_.
`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 egrep@protonmail.ch. 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>`_
Raw data
{
"_id": null,
"home_page": "https://django-environ.readthedocs.org",
"name": "django-environ",
"maintainer": "Serghei Iakovlev",
"docs_url": null,
"requires_python": ">=3.6,<4",
"maintainer_email": "egrep@protonmail.ch",
"keywords": "environment,django,variables,12factor",
"author": "Daniele Faraglia",
"author_email": "daniele.faraglia@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/d6/0b/f2c024529ee4bbf8b95176eebeb86c6e695192a9ce0e91059cb83a33c1d3/django-environ-0.11.2.tar.gz",
"platform": "any",
"description": "==============\ndjango-environ\n==============\n\n\n``django-environ`` is the Python package that allows you to use\n`Twelve-factor methodology <https://www.12factor.net/>`_ to configure your\nDjango application with environment variables.\n\n.. -teaser-end-\n\nFor that, it gives you an easy way to configure Django application using\nenvironment variables obtained from an environment file and provided by the OS:\n\n.. -code-begin-\n\n.. code-block:: python\n\n import environ\n import os\n\n env = environ.Env(\n # set casting, default value\n DEBUG=(bool, False)\n )\n\n # Set the project base directory\n BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))\n\n # Take environment variables from .env file\n environ.Env.read_env(os.path.join(BASE_DIR, '.env'))\n\n # False if not in os.environ because of casting above\n DEBUG = env('DEBUG')\n\n # Raises Django's ImproperlyConfigured\n # exception if SECRET_KEY not in os.environ\n SECRET_KEY = env('SECRET_KEY')\n\n # Parse database connection url strings\n # like psql://user:pass@127.0.0.1:8458/db\n DATABASES = {\n # read os.environ['DATABASE_URL'] and raises\n # ImproperlyConfigured exception if not found\n #\n # The db() method is an alias for db_url().\n 'default': env.db(),\n\n # read os.environ['SQLITE_URL']\n 'extra': env.db_url(\n 'SQLITE_URL',\n default='sqlite:////tmp/my-tmp-sqlite.db'\n )\n }\n\n CACHES = {\n # Read os.environ['CACHE_URL'] and raises\n # ImproperlyConfigured exception if not found.\n #\n # The cache() method is an alias for cache_url().\n 'default': env.cache(),\n\n # read os.environ['REDIS_URL']\n 'redis': env.cache_url('REDIS_URL')\n }\n\n.. -overview-\n\nThe idea of this package is to unify a lot of packages that make the same stuff:\nTake a string from ``os.environ``, parse and cast it to some of useful python\ntyped variables. To do that and to use the `12factor <https://www.12factor.net/>`_\napproach, some connection strings are expressed as url, so this package can parse\nit and return a ``urllib.parse.ParseResult``. These strings from ``os.environ``\nare loaded from a ``.env`` file and filled in ``os.environ`` with ``setdefault``\nmethod, to avoid to overwrite the real environ.\nA similar approach is used in `Two Scoops of Django <https://www.feldroy.com/books/two-scoops-of-django-3-x>`_\nbook and explained in `12factor-django <https://wellfire.co/learn/easier-12-factor-django>`_\narticle.\n\n\nUsing ``django-environ`` you can stop to make a lot of unversioned\n``settings_*.py`` to configure your app.\nSee `cookiecutter-django <https://github.com/cookiecutter/cookiecutter-django>`_\nfor a concrete example on using with a django project.\n\n**Feature Support**\n\n- Fast and easy multi environment for deploy\n- Fill ``os.environ`` with .env file variables\n- Variables casting\n- Url variables exploded to django specific package settings\n- Optional support for Docker-style file based config variables (use\n ``environ.FileAwareEnv`` instead of ``environ.Env``)\n\n.. -project-information-\n\nProject Information\n===================\n\n``django-environ`` is released under the `MIT / X11 License <https://choosealicense.com/licenses/mit/>`__,\nits documentation lives at `Read the Docs <https://django-environ.readthedocs.io/en/latest/>`_,\nthe code on `GitHub <https://github.com/joke2k/django-environ>`_,\nand the latest release on `PyPI <https://pypi.org/project/django-environ/>`_.\n\nIt\u2019s rigorously tested on Python 3.6+, and officially supports\nDjango 1.11, 2.2, 3.0, 3.1, 3.2, 4.0, 4.1 and 4.2.\n\nIf you'd like to contribute to ``django-environ`` you're most welcome!\n\n.. -support-\n\nSupport\n=======\n\nShould you have any question, any remark, or if you find a bug, or if there is\nsomething you can't do with the ``django-environ``, please\n`open an issue <https://github.com/joke2k/django-environ>`_.\n\n\nContributing\n============\n\nIf you would like to contribute to ``django-environ``, please take a look at the\n`current issues <https://github.com/joke2k/django-environ/issues>`_. If there is\na bug or feature that you want but it isn't listed, make an issue and work on it.\n\nBug reports\n-----------\n\n*Before raising an issue, please ensure that you are using the latest version\nof django-environ.*\n\nPlease provide the following information with your issue to enable us to\nrespond as quickly as possible.\n\n* The relevant versions of the packages you are using.\n* The steps to recreate your issue.\n* The full stacktrace if there is an exception.\n* An executable code example where possible\n\nGuidelines for bug reports:\n\n* **Use the GitHub issue search** \u2014 check if the issue has already been\n reported.\n* **Check if the issue has been fixed** \u2014 try to reproduce it using the latest\n ``main`` or ``develop`` branch in the repository.\n* Isolate the problem \u2014 create a reduced test case and a live example.\n\nA good bug report shouldn't leave others needing to chase you up for more\ninformation. Please try to be as detailed as possible in your report. What is\nyour environment? What steps will reproduce the issue? What OS experience the\nproblem? What would you expect to be the outcome? All these details will help\npeople to fix any potential bugs.\n\nFeature requests\n----------------\n\nFeature requests are welcome. But take a moment to find out whether your idea\nfits with the scope and aims of the project. It's up to *you* to make a strong\ncase to convince the project's developers of the merits of this feature. Please\nprovide as much detail and context as possible.\n\nPull requests\n-------------\n\nGood pull requests - patches, improvements, new features - are a fantastic\nhelp. They should remain focused in scope and avoid containing unrelated\ncommits.\n\nFollow this process if you'd like your work considered for inclusion in the\nproject:\n\n1. Check for open issues or open a fresh issue to start a discussion around a\n feature idea or a bug.\n2. Fork `the repository <https://github.com/joke2k/django-environ>`_\n on GitHub to start making your changes to the ``develop`` branch\n (or branch off of it).\n3. Write a test which shows that the bug was fixed or that the feature works as\n expected.\n4. Send a pull request and bug the maintainer until it gets merged and published.\n\nIf you are intending to implement a fairly large feature we'd appreciate if you\nopen an issue with GitHub detailing your use case and intended solution to\ndiscuss how it might impact other work that is in flight.\n\nWe also appreciate it if you take the time to update and write tests for any\nchanges you submit.\n\n**By submitting a patch, you agree to allow the project owner to license your\nwork under the same license as that used by the project.**\n\nResources\n---------\n\n* `How to Contribute to Open Source <https://opensource.guide/how-to-contribute/>`_\n* `Using Pull Requests <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests>`_\n* `Writing good commit messages <https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html>`_\n\n\nRelease Information\n===================\n\nv0.11.2 - 1-September-2023\n-------------------------------\nFixed\n+++++\n- Revert \"Add variable expansion.\" feature\n due to `#490 <https://github.com/joke2k/django-environ/issues/490>`_.\n\n`Full changelog <https://django-environ.readthedocs.org/en/latest/changelog.html>`_.\n\nSecurity Policy\n===============\n\n\nReporting a Vulnerability\n-------------------------\n\nIf you discover a security vulnerability within ``django-environ``, please\nsend an e-mail to Serghei Iakovlev via egrep@protonmail.ch. All security\nvulnerabilities will be promptly addressed.\n\n\nCredits\n=======\n\n``django-environ`` was initially created by `Daniele Faraglia <https://github.com/joke2k>`_\nand currently maintained by `Serghei Iakovlev <https://github.com/sergeyklay/>`_.\n\nA full list of contributors can be found in `GitHub <https://github.com/joke2k/django-environ/graphs/contributors>`__.\n\nAcknowledgments\n===============\n\nThe existence of ``django-environ`` would have been impossible without these\nprojects:\n\n- `rconradharris/envparse <https://github.com/rconradharris/envparse>`_\n- `jazzband/dj-database-url <https://github.com/jazzband/dj-database-url>`_\n- `migonzalvar/dj-email-url <https://github.com/migonzalvar/dj-email-url>`_\n- `ghickman/django-cache-url <https://github.com/ghickman/django-cache-url>`_\n- `dstufft/dj-search-url <https://github.com/dstufft/dj-search-url>`_\n- `julianwachholz/dj-config-url <https://github.com/julianwachholz/dj-config-url>`_\n- `nickstenning/honcho <https://github.com/nickstenning/honcho>`_\n- `rconradharris/envparse <https://github.com/rconradharris/envparse>`_\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A package that allows you to utilize 12factor inspired environment variables to configure your Django application.",
"version": "0.11.2",
"project_urls": {
"Bug Tracker": "https://github.com/joke2k/django-environ/issues",
"Changelog": "https://django-environ.readthedocs.org/en/latest/changelog.html",
"Documentation": "https://django-environ.readthedocs.org",
"Funding": "https://opencollective.com/django-environ",
"Homepage": "https://django-environ.readthedocs.org",
"Say Thanks!": "https://saythanks.io/to/joke2k",
"Source Code": "https://github.com/joke2k/django-environ"
},
"split_keywords": [
"environment",
"django",
"variables",
"12factor"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c4f1468b49cccba3b42dda571063a14c668bb0b53a1d5712426d18e36663bd53",
"md5": "5085c4ebb6e452c49a9a583f5f8f7084",
"sha256": "0ff95ab4344bfeff693836aa978e6840abef2e2f1145adff7735892711590c05"
},
"downloads": -1,
"filename": "django_environ-0.11.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "5085c4ebb6e452c49a9a583f5f8f7084",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.6,<4",
"size": 19141,
"upload_time": "2023-09-01T21:02:59",
"upload_time_iso_8601": "2023-09-01T21:02:59.880650Z",
"url": "https://files.pythonhosted.org/packages/c4/f1/468b49cccba3b42dda571063a14c668bb0b53a1d5712426d18e36663bd53/django_environ-0.11.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d60bf2c024529ee4bbf8b95176eebeb86c6e695192a9ce0e91059cb83a33c1d3",
"md5": "e09f141751614358d9a9e89f0c828e0a",
"sha256": "f32a87aa0899894c27d4e1776fa6b477e8164ed7f6b3e410a62a6d72caaf64be"
},
"downloads": -1,
"filename": "django-environ-0.11.2.tar.gz",
"has_sig": false,
"md5_digest": "e09f141751614358d9a9e89f0c828e0a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6,<4",
"size": 54326,
"upload_time": "2023-09-01T21:03:02",
"upload_time_iso_8601": "2023-09-01T21:03:02.435561Z",
"url": "https://files.pythonhosted.org/packages/d6/0b/f2c024529ee4bbf8b95176eebeb86c6e695192a9ce0e91059cb83a33c1d3/django-environ-0.11.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-01 21:03:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "joke2k",
"github_project": "django-environ",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "django-environ"
}
JSON
