{"id":45345283,"url":"https://github.com/deeprave/django-settings-env","last_synced_at":"2026-02-21T11:08:02.741Z","repository":{"id":117668579,"uuid":"560765393","full_name":"deeprave/django-settings-env","owner":"deeprave","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-26T23:24:34.000Z","size":364,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-27T08:05:52.394Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/deeprave.png","metadata":{"files":{"readme":"README.md","changelog":"ChangeLog.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-11-02T08:06:35.000Z","updated_at":"2025-08-26T23:24:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"f0c69c10-52f0-4952-a423-0d071203f700","html_url":"https://github.com/deeprave/django-settings-env","commit_stats":null,"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"purl":"pkg:github/deeprave/django-settings-env","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deeprave%2Fdjango-settings-env","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deeprave%2Fdjango-settings-env/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deeprave%2Fdjango-settings-env/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deeprave%2Fdjango-settings-env/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deeprave","download_url":"https://codeload.github.com/deeprave/django-settings-env/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deeprave%2Fdjango-settings-env/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29679148,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T09:33:50.764Z","status":"ssl_error","status_checked_at":"2026-02-21T09:33:19.949Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-21T11:08:02.032Z","updated_at":"2026-02-21T11:08:02.727Z","avatar_url":"https://github.com/deeprave.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# django-settings-env\n\n12-factor.net settings handler for Django.\n\n[![PyPI version](https://badge.fury.io/py/django-settings-env.svg)](https://badge.fury.io/py/django-settings-env)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)\n\n## [envex](https://pypi.org/project/envex/)\n\n[![PyPI version](https://badge.fury.io/py/envex.svg)](https://badge.fury.io/py/envex)\n\n## Introduction\n\nThe primary functionality of this module is provided by the dependency `envex`,\nwhich provides settings via the OS environment, `.env` files, encrypted `.env` files (since `envex` v4.0),\nand optionally, HashiCorp vault (since `envex` v2.0).\n\n## Inherited envex Features\n\n`envex` provides a convenient type-smart interface for handling the OS environment, and therefore\nconfiguration of any application using 12factor.net principals removing many environment-specific\nvariables and/or security-sensitive information from application code and source code repositories.\n\nSettings may be sourced from .env files, encrypted .env.enc files, directly from the environment,\nor from a HashiCorp vault. By default, values set in the environment take priority over those set\nin .env files, and those take priority of any corresponding values stored in Vault.\nThis can be changed by setting `ENVEX_SOURCE` to a value such as `file`, `vault`, or any other value except `env`.\n\nSome features not supported by other dotenv handlers (python-dotenv, etc.) are available\nincluding expansion of template variables, which can enhance Don't Repeat Yourself.\n\n## Installation\n\n```shell\npip install django-settings-env\n...\npoetry add django-settings-env\n...\nuv add django-settings-env\n```\n\n## Usage\n\nThis module doesn't need to be added to `INSTALLED_APPS` as it isn't a Django app, but is an add-on module available\nfor import.\n\n```python\nimport django_settings_env\n```\n\nor\n\n```python\nfrom django_settings_env import Env\n```\n\n### Basic Usage\n\n```python\nfrom django_settings_env import Env\n\n...\nenv = Env(options...)\n```\n\nBy default, the env object will check both the operating system environment and any .env files in the project root for\nsettings; this can be customised by:\n\n- passing readenv=False to prevent reading from any .env files\n- passing a search_path to specify the location of the .env file\n- adding parents=True to also search parent directories for the .env file\n- adding env_file arg to override the name of the default `.env`\n- passing decrypt=True and a password source to decrypt encrypted .env files\n\nThese options are all available via the `envex` module.\n\nWherever an Env instance is available, the environment can be accessed with env[\"VAR_NAME\"], or env(\"VAR_NAME\").\nThe latter is a convenience method that will return the value of the variable or None if it is not set.\nA `default=\u003cvalue\u003e\\\u003cvalue\\\u003e` kwarg may also be used and is returned if the specified variable is not set.\nThe \"call\" syntax also has another advantage in that it can be used to set a default value if the variable is currently unset.\nWhen assigned to a variable of the same name as the variable in the current scope, the variable does not need to be\nspecified, for example:\n\n```python\nfrom django_settings_env import Env\n\nenv = Env()\n...\nDEBUG = env(default=False)\n```\n\nThe value of `DEBUG` is deferred until used or referenced.\nThe `default` keyword is required to set the default, because the first positional argument is reserved for the variable\nname.\n\nNote that this functionality only works at the same scope level as the declaration of the variable: class, module (aka\n\"global\") or function.\nIt will not work for cross-scope assignments (assigning a class variable from a method, for example).\nExplicitly specifying the variable name, however, will still work in this case.\n\n## Django Settings\n\n`django-settings-env` adds features to `envex` and specifically aims to bring full 12-factor.net compliance to\nDjango settings.\nIt will typically avoid the need to separate local/development configuration settings from production settings, as values are determined at runtime by the content of the environment, `.env` and `.env.enc` files, or values obtained from a HashiCorp vault.\n\nBy default, the DjangoEnv class can apply a given prefix (default is \"DJANGO_\") to environment variables names, but will only be used in that form if the raw (no prefix) variable name is not in use in the environment.\nTo change the prefix including setting it to an empty string, pass the prefix= kwarg to `Env()`, and many of the methods can also accept a `prefix=` keyword argument if required.\n\nOne key difference between `envex` and `django-settings-env` is that the latter will read .env files by default, and will automatically search parent directories if one is not found where initially expected. This default behaviour needs to be explicitly enabled in `envex`.\n\n## django-settings-env API\n\nThis module provides a number of type-safe methods to help in retrieving values from the environment (including `.env`\nand `.env.enc` files or from vault).\nThe `env.get()` method assumes a string should be returned, but other methods are available to handle other types, such\nas `env.int()`, `env.bool()`, `env.float()`, `env.list()` etc.\nAll provide seamless conversion of the environment variable to the desired type, or return a default value if the\nvariable is not set.\nThe `env()` call syntax also provides a `type` parameter that can be used to specify the type of the variable to be\nreturned, which can be either a class, or the name of the class.\nOnly primitive types and `list` (comma separated values) are currently supported.\n\n### Django Specific Methods\n\nSome django specific functionality is included in this module, added via plugins:\n\n\n| Default Var  | Parser               |\n| ------------ | -------------------- |\n| DATABASE_URL | `env.database_url()` |\n| CACHE_URL    | `env.cache_url()`    |\n| EMAIL_URL    | `env.email_url()`    |\n| SEARCH_URL   | `env.search_url()`   |\n\nEach of these values can be injected into django settings via the environment, typically from a `.env(.enc)` file at the project root, or set from a variable in vault.\nIndividual components of these URLs can also be set, but passing the URL provides a way of setting all the required\ncomponents, including options as query parameters.\n\nThe url specified includes a scheme that determines the \"backend\" class, engine or module that handles the\ncorresponding functionality as documented below.\nThis can be overridden using the `backend=` parameter even if the scheme is not known by `django-settings-env`.\n\nURLs may include options, in the form of query options, i.e. `?option=value\u0026option2=value2` etc. that are specific to\nthe engine or backend being used.\nOptions are usually case-sensitive, and must use the same case as expected by the backend.\n\n### `database_url`\n\n- Provided by the `plugin_database` module.\n\nEvaluate a URL in the form\n\n```\nschema://[username:[password]@]host_or_path[:port]/name[?...options]\n```\n\nSupported schemas:\n\n| Scheme          | Database                                    |\n| --------------- | ------------------------------------------- |\n| postgres        | Postgres (psycopg2 or psycopg)              |\n| postgresql      | Postgres (psycopg2 or psycopg)              |\n| psql            | Postgres (psycopg2 or psycopg)              |\n| pgsql           | Postgres (psycopg2 or psycopg)              |\n| postgis         | Postgres (psycopg2 or psycopg) + PostGIS    |\n| mysql           | MySql (mysqlclient)                         |\n| mysql2          | MySql (mysqlclient)                         |\n| mysql-connector | MySql (mysql-connector)                     |\n| mysqlgis        | MySql (mysqlclient) using GIS extensions    |\n| mssql           | SqlServer (sql_server.pyodbc)               |\n| oracle          | Oracle (cx_Oracle)                          |\n| pyodbc          | ODBC (pyodbc)                               |\n| redshift        | Amazon Redshift                             |\n| spatialite      | Sqlite with spatial extensions (spatialite) |\n| sqlite          | Sqlite                                      |\n| ldap            | django-ldap                                 |\n\n#### Examples (snippets from settings.py)\n\n```python\nfrom django_settings_env import Env\n\nenv = Env()\n...\nDATABASES = {\n    \"default\": env.database_url(),\n    \"backup\": env.database_url(\"DATABASE_BACKUP_URL\"),\n}\n```\n\n### `cache_url`\n\n- Provided by the `plugin_cache` module.\n\nEvaluate a URL in the form\n\n```\nschema://[username:[password]@]host_or_path[:port]/[name][?...options]\n```\n\nSupported schemas:\n\n| Scheme      | Cache                        |\n| ----------- | ---------------------------- |\n| dbcache     | cache in database            |\n| dummycache  | dummy cache - \"no cache\"     |\n| filecache   | cache data in files          |\n| locmemcache | cache in memory              |\n| memcache    | memcached (python-memcached) |\n| pymemcache  | memcached (pymemcache)       |\n| rediscache  | redis                        |\n| redis       | redis                        |\n| rediss      | redis (ssl connection)       |\n\n### `email_url`\n\n- Provided by the `plugin_email` module.\n\nEvaluate a URL in the form\n\n```\nschema://[username[@domain]:[password]@]host_or_path[:port]/[?...options]\n```\n\nSupported schemas:\n\n| Scheme      | Service                       |\n| ----------- | ----------------------------- |\n| smtp        | smtp, no SSL                  |\n| smtps       | smtp over SSL                 |\n| smtp+tls    | smtp over SSL                 |\n| smtp+ssl    | smtp over SSL                 |\n| consolemail | publish mail to console (dev) |\n| filemail    | append email to file (dev)    |\n| memorymail  | store emails in memory        |\n| dummymail   | do-nothing email backend      |\n| amazonses   | Amazon Wimple Email Service   |\n| amazon-ses  | Amazon Wimple Email Service   |\n\n### `search_url`\n\n- Provided by the `plugin_search` module.\n\nEvaluate a URL in the form\n\n```\nschema://[username:[password]@]host_or_path[:port]/[index]\n```\n\nSupported schemas:\n\n| Scheme            | Engine                                       |\n| ----------------- | -------------------------------------------- |\n| elasticsearch     | elasticsearch (django-haystack)              |\n| elasticsearch2    | elasticsearch2 (django-haystack)             |\n| elasticsearch-dsl | elasticsearch-dsl                            |\n| solr              | Apache solr (django-haystack)                |\n| whoosh            | Whoosh search engine (pure python, haystack) |\n| xapian            | Xapian search engine (haystack)              |\n| simple            | Simple search engine (haystack)              |\n\nNote that django-haystack may require many additional settings not supported by this module.\n`elasticsearch-dsl` is recommended as a suitable replacement, and in general integrates well with Django's ORM,\nproviding the ability to easily relate ES documents+indexes to Django models.\nThe DSL version also supports more contemporary versions of Elasticsearch and is well maintained.\n\n## Django Class Settings\n\nSupport for the [`django-class-settings`](https://pypi.org/project/django-class-settings/) module is dynamically added to the env handler, allowing a much simplified use withing a class_settings.Settings class, e.g.:\n\n```python\nfrom django_settings_env import Env\n# noinspection PyUnresolvedReferences\nfrom class_settings import Settings\n\nenv = Env(prefix='DJANGO_')  # redundant, this is the default\n\n\nclass MySettings(Settings):\n    MYSETTING = env()\n```\n\nThis usage will look for 'MYSETTING' or 'DJANGO_MYSETTING' in the environment and lazily\nassign it to the MYSETTING value for the settings class.\n\n\n## Connection to Vault\n\nConnecting to vault is optional, and handled by the `envex` module.\nThe connection is determined by the presence of VAULT_ADDR in the environment.\nIt can't be set from a `.env` as typically the connection to Vault determined when the env object is instantiated,\nbefore it scans and reads any `.env` files.\n\n\u003e :warning: If $VAULT_ADDR is set but the vault server is not running or is unavailable, there may be a considerable\n\u003e startup delay until the connection times out.\n\nIn addition, $VAULT_TOKEN is required to be set in the environment to authenticate with the vault\nserver.\nOther environment variables may also be required, depending on the vault configuration.\n\n| Variable          | Description                                         |\n| ----------------- | --------------------------------------------------- |\n| VAULT_ADDR        | URL of the vault server                             |\n| VAULT_TOKEN       | Token to authenticate with the vault server         |\n| VAULT_CACERT      | Path to the CA certificate for the vault server     |\n| VAULT_SKIP_VERIFY | Skip verification of the vault server certificate   |\n| VAULT_CLIENT_CERT | Path to the client certificate for the vault server |\n| VAULT_CLIENT_KEY  | Path to the client key for the vault server         |\n| VAULT_TIMEOUT     | Timeout for the vault connection (in seconds)       |\n\nWhile setting the `VAULT_TIMEOUT` item can reduce the startup delay if the vault server is not available, the vault\nmodule retries multiple times before giving up, so the delay may still be considerable.\nThis variable is provided to *increase* the connection timeout should the default of 5 seconds be insufficient to\nsuccessfully establish the connection.\nReducing it even further is not recommended.\n\nVAULT_CACERT is useful when running vault with TLS is enabled (**highly recommended**), and the certificate is not\nsigned by a recognised Certificate Authority, i.e. self-signed or an internal CA.\nAlternatively, `VAULT_SKIP_VERIFY=true` in the environment will disable verification of the vault server certificate (*\n*not recommended**).\n\nVAULT_CLIENT_CERT and VAULT_CLIENT_KEY are optional and are only required if the vault server requires client\ncertificates.\nIf used, both variables must be set and provide valid paths to the client certificate and key.\n\nThe vault store contains a single object containing all values in a dictionary format, and is cached by default.\nThe cache is used to return individual values by key (same key as the environment variable) with the assumption that the\nvault secrets remain unchanged during the application runtime.\nConsequently, any changes to vault require an application restart, so it is wise to consider which items to put in vault\nand which to put in the environment.\nIt is recommended to only place items in the vault that contain secrets or are otherwise sensitive.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeeprave%2Fdjango-settings-env","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeeprave%2Fdjango-settings-env","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeeprave%2Fdjango-settings-env/lists"}