docs/types.rst
The following are all type-casting methods of :py:class:.environ.Env.
~.environ.Env.str~.environ.Env.bool~.environ.Env.int~.environ.Env.float~.environ.Env.json~.environ.Env.url~.environ.Env.list: (accepts values like (FOO=a,b,c))~.environ.Env.tuple: (accepts values like (FOO=(a,b,c)))~.environ.Env.path: (accepts values like (environ.Path))~.environ.Env.dict: (see below, ":ref:environ-env-dict" section)~.environ.Env.db_url (see below, ":ref:environ-env-db-url" section)~.environ.Env.cache_url (see below, ":ref:environ-env-cache-url" section)~.environ.Env.search_url (see below, ":ref:environ-env-search-url" section)~.environ.Env.email_url (see below, ":ref:environ-env-email-url" section).. _environ-env-dict:
environ.Env.dict:py:class:.environ.Env may parse complex variables like with the complex type-casting.
For example:
.. code-block:: python
import environ
env = environ.Env()
env.parse_value('key=val,foo=bar', dict)
env.parse_value( 'key=val;foo=1.1;baz=True', dict(value=str, cast=dict(foo=float,baz=bool)) )
For more detailed example see ":ref:complex_dict_format".
.. _environ-env-db-url:
environ.Env.db_url:py:meth:~.environ.Env.db_url supports the following URL schemas:
.. glossary::
Amazon Redshift
**Database Backend:** ``django_redshift_backend``
**URL schema:** ``redshift://``
LDAP
**Database Backend:** ``ldapdb.backends.ldap``
**URL schema:** ``ldap://host:port/dn?attrs?scope?filter?exts``
MSSQL
**Database Backend:** ``sql_server.pyodbc``
**URL schema:** ``mssql://user:password@host:port/dbname``
With MySQL you can use the following schemas: ``mysql``, ``mysql2``.
MySQL (GIS)
**Database Backend:** ``django.contrib.gis.db.backends.mysql``
**URL schema:** ``mysqlgis://user:password@host:port/dbname``
MySQL
**Database Backend:** ``django.db.backends.mysql``
**URL schema:** ``mysql://user:password@host:port/dbname``
MySQL Connector Python from Oracle
**Database Backend:** ``mysql.connector.django``
**URL schema:** ``mysql-connector://``
Oracle
**Database Backend:** ``django.db.backends.oracle``
**URL schema:** ``oracle://user:password@host:port/dbname``
PostgreSQL
**Database Backend:** ``django.db.backends.postgresql``
**URL schema:** ``postgres://user:password@host:port/dbname``
With PostgreSQL you can use the following schemas: ``postgres``, ``postgresql``, ``psql``, ``pgsql``, ``postgis``.
You can also use UNIX domain sockets path instead of hostname. For example: ``postgres://path/dbname``.
The ``django.db.backends.postgresql_psycopg2`` will be used if the Django version is less than ``2.0``.
PostGIS
**Database Backend:** ``django.contrib.gis.db.backends.postgis``
**URL schema:** ``postgis://user:password@host:port/dbname``
PyODBC
**Database Backend:** ``sql_server.pyodbc``
**URL schema:** ``pyodbc://``
SQLite
**Database Backend:** ``django.db.backends.sqlite3``
**URL schema:** ``sqlite:////absolute/path/to/db/file``
SQLite connects to file based databases. URL schemas ``sqlite://`` or
``sqlite://:memory:`` means the database is in the memory (not a file on disk).
SpatiaLite
**Database Backend:** ``django.contrib.gis.db.backends.spatialite``
**URL schema:** ``spatialite:///PATH``
SQLite connects to file based databases. URL schemas ``sqlite://`` or
``sqlite://:memory:`` means the database is in the memory (not a file on disk).
db_urlQuery parameters from DATABASE_URL are mapped to Django database settings:
conn_max_age, autocommit,
atomic_requests) are promoted to top-level DB config keys;OPTIONS.For MySQL strict mode, for example:
.. code-block:: shell
DATABASE_URL=mysql://user:password@host:3306/dbname?sql_mode=STRICT_TRANS_TABLES
This produces:
.. code-block:: python
{"OPTIONS": {"sql_mode": "STRICT_TRANS_TABLES"}}
If a value needs explicit typing (for example booleans or JSON), use
options_cast with an explicit URL and expected result:
.. code-block:: python
import json import environ
url = ( "mysql://user:password@host:3306/dbname?" "reconnect=true&ssl=%7B%22ca%22%3A%22%2Fapp%2Ffoo%2Fca.pem%22%7D" ) config = environ.Env.db_url_config( url, options_cast={ "reconnect": bool, "ssl": json.loads, } )
Only mapped keys are cast with the provided type/callable. Unmapped options keep the default parsing behavior.
For values that are not practical to pass in a URL query string (for example
nested dictionaries like Django 5.1 PostgreSQL pool options), pass
extra_options and they will be merged into OPTIONS:
.. code-block:: python
config = environ.Env.db_url_config( "postgres://user:password@host:5432/dbname", extra_options={ "pool": {"min_size": 2, "max_size": 4, "timeout": 10}, }, )
.. _environ-env-cache-url:
environ.Env.cache_url:py:meth:~.environ.Env.cache_url supports the following URL schemas:
Database: dbcache://
Dummy: dummycache://
File: filecache://
Memory: locmemcache://
Memcached:
memcache:// (uses python-memcached backend, deprecated in Django 3.2)pymemcache:// (uses pymemcache backend if Django >=3.2 and package is installed, otherwise will use pylibmc backend to keep config backwards compatibility)pylibmc://Redis: rediscache://, redis://, or rediss://
Valkey: valkey://, or valkeys://
.. _environ-env-search-url:
environ.Env.search_url:py:meth:~.environ.Env.search_url supports the following URL schemas:
elasticsearch:// (http) or elasticsearchs:// (https)elasticsearch2:// (http) or elasticsearch2s:// (https)elasticsearch5:// (http) or elasticsearch5s:// (https)elasticsearch7:// (http) or elasticsearch7s:// (https)solr://whoosh://xapian://simple://.. _environ-env-email-url:
environ.Env.email_url:py:meth:~.environ.Env.email_url supports the following URL schemas:
smtp://smtp+ssl://smtp+tls://consolemail://filemail://memorymail://dummymail://