diff --git a/docs/_static/.gitkeep b/docs/_static/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/changelog.rst b/docs/changelog.rst new file mode 100644 index 00000000..565b0521 --- /dev/null +++ b/docs/changelog.rst @@ -0,0 +1 @@ +.. include:: ../CHANGELOG.rst diff --git a/docs/conf.py b/docs/conf.py index 0c0e051c..f11a4d50 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -44,7 +44,7 @@ def find_version(meta_file): # General information about the project. project = 'django-environ' -copyright = '2021, Daniele Faraglia and other contributors' +copyright = '2013-2021, Daniele Faraglia and other contributors' author = u"Daniele Faraglia" # diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 00000000..e582053e --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1 @@ +.. include:: ../CONTRIBUTING.rst diff --git a/docs/getting-started.rst b/docs/getting-started.rst new file mode 100644 index 00000000..ae2f6af7 --- /dev/null +++ b/docs/getting-started.rst @@ -0,0 +1,76 @@ +=============== +Getting Started +=============== + +Installation +============ + + +Requirements +------------ + +* `Django `_ >= 1.11 +* `Python `_ >= 3.4 + +Installing django-environ +_________________________ + +``django-environ`` is a Python-only package `hosted on PyPI `_. +The recommended installation method is `pip `_-installing into a virtualenv: + +.. code-block:: shell + + $ python -m pip install django-environ + +.. note:: + + After installing ``django-environ``, no need to add it to ``INSTALLED_APPS``. + +Then create a ``.env`` file. The file format can be understood from the example below: + +.. code-block:: shell + + DEBUG=on + SECRET_KEY=your-secret-key + DATABASE_URL=psql://user:un-githubbedpassword@127.0.0.1:8458/database + SQLITE_URL=sqlite:///my-local-sqlite.db + CACHE_URL=memcache://127.0.0.1:11211,127.0.0.1:11212,127.0.0.1:11213 + REDIS_URL=rediscache://127.0.0.1:6379/1?client_class=django_redis.client.DefaultClient&password=ungithubbed-secret + +And use it with ``settings.py`` as follows: + +.. include:: ../README.rst + :start-after: -code-begin- + :end-before: -overview- + +.. warning:: + + Don't forget to add ``.env`` in your ``.gitignore``. You can also add + ``.env.dist`` with a template of your variables to the project repo. + +Unstable version +________________ + +The master of all the material is the Git repository at https://github.com/joke2k/django-environ. +So, can also install the latest unreleased development version directly from the ``develop`` branch on +GitHub. It is a work-in-progress of a future stable release so the experience might be not as smooth.: + +.. code-block:: shell + + $ pip install -e git://github.com/joke2k/django-environ.git#egg=django-environ + # OR + $ pip install --upgrade https://github.com/joke2k/django-environ.git/archive/develop.tar.gz + +This command will download the latest version of ``django-environ`` from the +`Python Package Index `_ and install it to your system. + +.. note:: + + The ``develop`` branch will always contain the latest unstable version, so the experience + might be not as smooth. If you wish to check older versions or formal, tagged release, + please switch to the relevant `tag `_. + +More information about ``pip`` and PyPI can be found here: + +* `Install pip `_ +* `Python Packaging User Guide `_ diff --git a/docs/index.rst b/docs/index.rst index 9d113eb3..cd128863 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,64 +1,49 @@ -Welcome to Django-environ's documentation! -========================================== +======================================= +Welcome to django-environ documentation +======================================= -.. automodule:: environ.environ +Release v\ |release| (`What's new? `). .. include:: ../README.rst + :start-after: -teaser-begin- + :end-before: -teaser-end- -environ.Env -=========== - -.. autoclass:: environ.environ.Env +Overview +======== - .. autoattribute:: BOOLEAN_TRUE_STRINGS - .. autoattribute:: DB_SCHEMES - .. autoattribute:: DEFAULT_DATABASE_ENV - .. autoattribute:: CACHE_SCHEMES - .. autoattribute:: DEFAULT_CACHE_ENV - .. autoattribute:: EMAIL_SCHEMES - .. autoattribute:: DEFAULT_EMAIL_ENV - .. autoattribute:: SEARCH_SCHEMES - .. autoattribute:: DEFAULT_SEARCH_ENV +.. include:: ../README.rst + :start-after: -overview- + :end-before: -project-information- - .. automethod:: __call__ - .. automethod:: str - .. automethod:: bool - .. automethod:: int - .. automethod:: float - .. automethod:: json - .. automethod:: list - .. automethod:: dict - .. automethod:: url - .. automethod:: db_url - .. automethod:: cache_url - .. automethod:: email_url - .. automethod:: search_url - .. automethod:: path +Quick Start +=========== - .. automethod:: read_env - .. automethod:: db_url_config - .. automethod:: cache_url_config - .. automethod:: email_url_config - .. automethod:: search_url_config - .. automethod:: get_value - .. automethod:: parse_value +.. include:: ../README.rst + :start-after: -code-begin- + :end-before: -overview- +.. include:: ../README.rst + :start-after: -support- -environ.Path -============ +---- -.. autoclass:: environ.environ.Path +Full Table of Contents +====================== - .. py:attribute:: root -> Retrieve absolute path - .. automethod:: __call__ - .. automethod:: path - .. automethod:: file +.. toctree:: + :maxdepth: 2 + getting-started + types + tips + contributing -Indices and tables -================== +.. include:: ../README.rst + :start-after: -project-information- + :end-before: -support- -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +.. toctree:: + :maxdepth: 1 + license + changelog diff --git a/docs/license.rst b/docs/license.rst new file mode 100644 index 00000000..feb5b5de --- /dev/null +++ b/docs/license.rst @@ -0,0 +1,9 @@ +=================== +License and Credits +=================== + +``django-environ`` is open source software licensed under the +`MIT / X11 License `_. +The full license text can be also found in the `source code repository `_. + +.. include:: ../AUTHORS.rst diff --git a/docs/tips.rst b/docs/tips.rst new file mode 100644 index 00000000..77d792f8 --- /dev/null +++ b/docs/tips.rst @@ -0,0 +1,124 @@ +==== +Tips +==== + + +Using unsafe characters in URLs +=============================== + +In order to use unsafe characters you have to encode with ``urllib.parse.encode`` before you set into ``.env`` file. + +.. code-block:: shell + + DATABASE_URL=mysql://user:%23password@127.0.0.1:3306/dbname + +See https://perishablepress.com/stop-using-unsafe-characters-in-urls/ for reference. + +Smart Casting +============= + +``django-environ`` has a "Smart-casting" enabled by default, if you don't provide a ``cast`` type, it will be detected from ``default`` type. +This could raise side effects (see `#192 `_). +To disable it use ``env.smart_cast = False``. + +.. note:: + + The next major release will disable it by default. + + +Multiple redis cache locations +============================== + +For redis cache, `multiple master/slave or shard locations `_ can be configured as follows: + +.. code-block:: shell + + CACHE_URL='rediscache://master:6379,slave1:6379,slave2:6379/1' + + +Email settings +============== + +In order to set email configuration for django you can use this code: + +.. code-block:: python + + # The email() method is an alias for email_url(). + EMAIL_CONFIG = env.email( + 'EMAIL_URL', + default='smtp://user:password@localhost:25' + ) + + vars().update(EMAIL_CONFIG) + + +SQLite urls +=========== + +SQLite connects to file based databases. The same URL format is used, omitting the hostname, +and using the "file" portion as the filename of the database. +This has the effect of four slashes being present for an absolute + +file path: ``sqlite:////full/path/to/your/database/file.sqlite``. + + +Nested lists +============ + +Some settings such as Django's ``ADMINS`` make use of nested lists. You can use something like this to handle similar cases. + +.. code-block:: python + + # DJANGO_ADMINS=John:john@admin.com,Jane:jane@admin.com + ADMINS = [x.split(':') for x in env.list('DJANGO_ADMINS')] + + # or use more specific function + + from email.utils import getaddresses + + # DJANGO_ADMINS=Full Name ,anotheremailwithoutname@example.com + ADMINS = getaddresses([env('DJANGO_ADMINS')]) + + +Multiline value +=============== + +You can set a multiline variable value: + +.. code-block:: python + + # MULTILINE_TEXT=Hello\\nWorld + >>> print env.str('MULTILINE_TEXT', multiline=True) + Hello + World + + +Proxy value +=========== + +Values that being with a ``$`` may be interpolated. Pass ``interpolate=True`` to +``environ.Env()`` to enable this feature: + +.. code-block:: python + + import environ + + env = environ.Env(interpolate=True) + + # BAR=FOO + # PROXY=$BAR + >>> print env.str('PROXY') + FOO + + +Multiple env files +================== + +It is possible to have multiple env files and select one using environment variables. + +.. code-block:: python + + env = environ.Env() + env.read_env(env.str('ENV_PATH', '.env')) + +Now ``ENV_PATH=other-env ./manage.py runserver`` uses ``other-env`` while ``./manage.py runserver`` uses ``.env``. diff --git a/docs/types.rst b/docs/types.rst new file mode 100644 index 00000000..b2144d06 --- /dev/null +++ b/docs/types.rst @@ -0,0 +1,57 @@ +=============== +Supported types +=============== + +* ``str`` +* ``bool`` +* ``int`` +* ``float`` +* ``json`` +* ``list``: ``(FOO=a,b,c)`` +* ``tuple``: ``(FOO=(a,b,c))`` +* ``dict``: ``(BAR=key=val,foo=bar)``, ``environ.Env(BAR=(dict, {}))`` +* ``dict``: ``(BAR=key=val;foo=1.1;baz=True)``, ``environ.Env(BAR=(dict(value=unicode, cast=dict(foo=float,baz=bool)), {}))`` +* ``url`` +* ``path``: ``(environ.Path)`` +* ``db_url`` + + * PostgreSQL: ``postgres://``, ``pgsql://``, ``psql://`` or ``postgresql://`` + * PostGIS: ``postgis://`` + * MySQL: ``mysql://`` or ``mysql2://`` + * MySQL for GeoDjango: ``mysqlgis://`` + * MySQL Connector Python from Oracle: ``mysql-connector://`` + * SQLite: ``sqlite://`` + * SQLite with SpatiaLite for GeoDjango: ``spatialite://`` + * Oracle: ``oracle://`` + * Microsoft SQL Server: ``mssql://`` + * PyODBC: ``pyodbc://`` + * Amazon Redshift: ``redshift://`` + * LDAP: ``ldap://`` + +* ``cache_url`` + + * Database: ``dbcache://`` + * Dummy: ``dummycache://`` + * File: ``filecache://`` + * Memory: ``locmemcache://`` + * Memcached: ``memcache://`` + * Python memory: ``pymemcache://`` + * Redis: ``rediscache://``, ``redis://``, or ``rediss://`` + +* ``search_url`` + + * Elasticsearch: ``elasticsearch://`` + * Solr: ``solr://`` + * Whoosh: ``whoosh://`` + * Xapian: ``xapian://`` + * Simple cache: ``simple://`` + +* ``email_url`` + + * SMTP: ``smtp://`` + * SMTP+SSL: ``smtp+ssl://`` + * SMTP+TLS: ``smtp+tls://`` + * Console mail: ``consolemail://`` + * File mail: ``filemail://`` + * LocMem mail: ``memorymail://`` + * Dummy mail: ``dummymail://``