dj-email-url

Use an URL to configure email backend settings in your Django Application.

BSD-2-Clause AND CC-BY-4.0 AND CC0-1.0 19 个版本
Miguel Gonzalez <migonzalvar@gmail.com>
主页
Homepage
安装
pip install dj-email-url
poetry add dj-email-url
pipenv install dj-email-url
conda install dj-email-url
描述

.. SPDX-FileCopyrightText: 2013-2022 Miguel Gonzalez migonzalvar@gmail.com .. .. SPDX-License-Identifier: CC-BY-4.0

============================= dj-email-url |latest-version|

|ci| |python-support|

This utility is based on dj-database-url by Kenneth Reitz.

It allows to utilize the 12factor_ inspired environments variable to configure the email backend in a Django application.

.. |latest-version| image:: https://img.shields.io/pypi/v/dj-email-url.svg :alt: Latest version on PyPI :target: https://pypi.org/project/dj-email-url/

.. |ci| image:: https://github.com/migonzalvar/dj-email-url/workflows/CI/badge.svg :alt: CI status :target: https://github.com/migonzalvar/dj-email-url

.. |python-support| image:: https://img.shields.io/pypi/pyversions/dj-email-url.svg :target: https://pypi.python.org/pypi/dj-email-url :alt: Python versions

.. _12factor: http://www.12factor.net/backing-services

Usage

Import the package in settings.py:

.. code:: python

import dj_email_url

Fetch your email configuration values. The default option is fetch them from EMAIL_URL environment variable:

.. code:: python

email_config = dj_email_url.config()

Other option is parse an arbitrary email URL:

.. code:: python

email_config = dj_email_url.parse('smtp://...')

Finally, it is necessary to assign values to settings:

.. code:: python

EMAIL_FILE_PATH = email_config['EMAIL_FILE_PATH']
EMAIL_HOST_USER = email_config['EMAIL_HOST_USER']
EMAIL_HOST_PASSWORD = email_config['EMAIL_HOST_PASSWORD']
EMAIL_HOST = email_config['EMAIL_HOST']
EMAIL_PORT = email_config['EMAIL_PORT']
EMAIL_BACKEND = email_config['EMAIL_BACKEND']
EMAIL_USE_TLS = email_config['EMAIL_USE_TLS']
EMAIL_USE_SSL = email_config['EMAIL_USE_SSL']
EMAIL_TIMEOUT = email_config['EMAIL_TIMEOUT']

Alternatively, it is possible to use this less explicit shortcut:

.. code:: python

vars().update(email_config)

Supported backends

Currently, dj-email-url supports:

+-----------+--------------------------------------------------+-----------------------------------------------------------+ | Backend | EMAIL_URL | Description | +===========+==================================================+===========================================================+ | Console | console: | Writes to stdout (development) | +-----------+--------------------------------------------------+-----------------------------------------------------------+ | SMTP | smtp: | Sends using a mail transfer agent at localhost on port 25 | +-----------+--------------------------------------------------+-----------------------------------------------------------+ | SMTP | submission://USER:PASSWORD@smtp.sendgrid.com | Sends using SendGrid_ SMTP on port 587 (STARTTLS) | +-----------+--------------------------------------------------+-----------------------------------------------------------+ | File | file: | Writes to a file | +-----------+--------------------------------------------------+-----------------------------------------------------------+ | In-memory | memory: | | +-----------+--------------------------------------------------+-----------------------------------------------------------+ | Dummy | dummy: | | +-----------+--------------------------------------------------+-----------------------------------------------------------+

.. _SendGrid: https://sendgrid.com/docs/Integrate/Frameworks/django.html

.. warning:: Using special characters on passwords

To use characters that have a special meaning in an URL (think of ``&``)
you should use `percent encoding <https://en.wikipedia.org/wiki/Percent-encoding>`_.
For example, ``m&m`` would become ``m%26m``.

Because the percent character itself (``%``) serves as the indicator for
percent-encoded octets, it must be percent-encoded as ``%25``.

.. code:: pycon

    >>> from urllib.parse import quote_plus
    >>> import dj_email_url
    >>> quote_plus("!@#$%^&*")
    '%21%40%23%24%25%5E%26%2A'
    >>> dj_email_url.parse("smtp://user:%21%40%23%24%25%5E%26%2A@localhost")["EMAIL_HOST_PASSWORD"]
    '!@#$%^&*'

Set from email addresses

dj-email-url also supports to optionally specify origin email addresses.

+--------------------+-------------------------+ | Setting | Query parameter | +====================+=========================+ | SERVER_EMAIL | _server_email | +--------------------+-------------------------+ | DEFAULT_FROM_EMAIL | _default_from_email | +--------------------+-------------------------+

For example: smtp://USER:PASSWORD@smtp.example.com/?_server_email=error@example.com

Do not forget to assign values to settings:

.. code:: python

SERVER_EMAIL = email_config.get('SERVER_EMAIL', 'root@localhost')
DEFAULT_FROM_EMAIL = email_config.get('DEFAULT_FROM_EMAIL', 'webmaster@localhost')

Other settings

There are other settings available to set from query param.

+--------------------+-------------------------+-----------------------+ | Setting | Query parameter | Comments | +====================+=========================+=======================+ | EMAIL_TIMEOUT | timeout | New in v1.0.5. | +--------------------+-------------------------+-----------------------+

More info

SMTP backend

The SMTP backend__ is selected when the scheme in the URL if one these:

__ https://docs.djangoproject.com/en/dev/topics/email/#smtp-backend

============================ ============ ========================= Value Default port Comment ============================ ============ ========================= smtp 25 Local mail transfer agent submission or submit 587 SMTP with STARTTLS ============================ ============ =========================

Changed in version 0.1: The use of smtps is now discouraged__ The value smtps was used to indicate to use TLS connections, that is to set EMAIL_USE_TLS to True. Now is recommended to use submission or submit (see service name for port numbers_ or Uniform Resource Identifier Schemes_ at IANA).

__ SMTPS_

.. _SMTPS: https://en.wikipedia.org/wiki/SMTPS

.. _service name for port numbers: https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?search=587

.. _Uniform Resource Identifier Schemes: https://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml

On the most popular mail configuration option is to use a third party SMTP server to relay emails.

.. code:: pycon

>>> url = 'submission://user@example.com:pass@smtp.example.com'
>>> url = dj_email_url.parse(url)
>>> assert url['EMAIL_PORT'] == 587
>>> assert url['EMAIL_USE_SSL'] is False
>>> assert url['EMAIL_USE_TLS'] is True

Other common option is to use a local mail transfer agent Postfix or Exim. In this case it as easy as:

.. code:: pycon

>>> url = 'smtp://'
>>> url = dj_email_url.parse(url)
>>> assert url['EMAIL_HOST'] == 'localhost'
>>> assert url['EMAIL_PORT'] == 25
>>> assert url['EMAIL_USE_SSL'] is False
>>> assert url['EMAIL_USE_TLS'] is False

It is also possible to configure SMTP-over-SSL (usually on 465). This configuration is not generally recommended but might be needed for legacy systems. To apply use this configuration specify SSL using a ssl=True as a query parameter and indicate the port explicitly:

.. code:: pycon

>>> url = 'smtp://user@domain.com:pass@smtp.example.com:465/?ssl=True'
>>> url = dj_email_url.parse(url)
>>> assert url['EMAIL_PORT'] == 465
>>> assert url['EMAIL_USE_SSL'] is True
>>> assert url['EMAIL_USE_TLS'] is False

File backend

The file backend is the only one which needs a path. The url path is store in EMAIL_FILE_PATH key.

License

This work is licensed under several licences.

  • All original source code is licensed under BSD-2-Clause.
  • All documentation is licensed under CC-BY-4.0.
  • Some configuration and data files are licensed under CC0-1.0.

For more accurate information, check the individual files.

You can check the compliance with REUSE helper tool <https://github.com/fsfe/reuse-tool>_.

.. SPDX-FileCopyrightText: 2013-2022 Miguel Gonzalez migonzalvar@gmail.com .. .. SPDX-License-Identifier: CC-BY-4.0

Change Log

Unreleased

1.0.6_ - 2022-09-24

.. _1.0.6: https://pypi.python.org/pypi/dj-email-url/1.0.6

  • Remove unnecessary code (thanks @matthiask).

  • Improve license metadata. No changes on license itself.

1.0.5_ - 2022-02-05

.. _1.0.5: https://pypi.python.org/pypi/dj-email-url/1.0.5

  • Added support for the timeout setting.

1.0.4_ - 2022-01-16

.. _1.0.4: https://pypi.python.org/pypi/dj-email-url/1.0.4

  • Post release version to update change log.

1.0.3_ - 2022-01-16

.. _1.0.3: https://pypi.python.org/pypi/dj-email-url/1.0.3

  • Added support for Python 3.10.

  • Changed continuos integration infrastructure from Travis to GitHub Actions.

  • Switched to PyPA build frontend.

1.0.2_ - 2021-01-23

.. _1.0.2: https://pypi.python.org/pypi/dj-email-url/1.0.2

  • Add support for Python 3.9 (@pauloxnet)

1.0.1_ - 2020-06-03

.. _1.0.1: https://pypi.python.org/pypi/dj-email-url/1.0.1

  • Included LICENSE file in tarball. Thanks to @fabaff.

1.0.0_ - 2020-02-16

.. _1.0.0: https://pypi.python.org/pypi/dj-email-url/1.0.0

  • Removed support for Python versions which reached end-of-life.

  • Fixed typo. Thanks to @jeffmacdonald.

0.2.0_ - 2019-04-08

.. _0.2.0: https://pypi.python.org/pypi/dj-email-url/0.2.0

  • Added support for DEFAULT_FROM_EMAIL and SERVER_EMAIL in the URL as query parameters.

0.1.0_ - 2018-03-24

.. _0.1.0: https://pypi.python.org/pypi/dj-email-url/0.1.0

  • Added new schemes submission and submit to select SMTP backend on port 587 with STARTTLS. Thanks to @LEW21 to suggest to include new submit URI.

  • Discouraged the use of scheme smtps and add a user warning. Thanks to @LEW21 to alert about this confusing usage.

  • Expand which values are considered as truthy on a query string param. Now, 1, on, true, and yes, as a single character or in all case variants (lower, upper and title case) are considered as True.

0.0.10_ - 2016-10-14

  • Post release version to fix release date in change log.

0.0.9_ - 2016-10-14

  • Fix case when user sets ssl=False in its url (thanks bogdal)

0.0.8_ - 2016-06-07

  • Allow universal wheel

0.0.7_ - 2016-05-31

  • Add EMAIL_USE_SSL setting to docs and set a default value (thanks iraycd).
  • Add coverage (thanks iraycd).

0.0.6_ - 2016-04-18

  • Fix error parsing URL without credentials (thanks martinmaillard).

0.0.5_ - 2016-04-17

  • Allow URL encoded credentials (thanks kane-c).

0.0.4_ - 2015-03-05

  • Fix README.

0.0.3_ - 2015-03-05

  • Add change log.

  • Add ssl= option as a query parameter for SMTP backend.

  • Add Travis continuous integration.

0.0.2_ - 2014-03-12

  • Add Python 3 support.

0.0.1_ - 2013-02-12

  • Initial version.

.. _0.0.1: https://pypi.python.org/pypi/dj-email-url/0.0.1 .. _0.0.2: https://pypi.python.org/pypi/dj-email-url/0.0.2 .. _0.0.3: https://pypi.python.org/pypi/dj-email-url/0.0.3 .. _0.0.4: https://pypi.python.org/pypi/dj-email-url/0.0.4 .. _0.0.5: https://pypi.python.org/pypi/dj-email-url/0.0.5 .. _0.0.6: https://pypi.python.org/pypi/dj-email-url/0.0.6 .. _0.0.7: https://pypi.python.org/pypi/dj-email-url/0.0.7 .. _0.0.8: https://pypi.python.org/pypi/dj-email-url/0.0.8 .. _0.0.9: https://pypi.python.org/pypi/dj-email-url/0.0.9 .. _0.0.10: https://pypi.python.org/pypi/dj-email-url/0.0.10

分类
Environment :: Web Environment Intended Audience :: Developers License :: OSI Approved :: BSD License Operating System :: OS Independent Programming Language :: Python Programming Language :: Python :: 3 Programming Language :: Python :: 3.10 Programming Language :: Python :: 3.5 Programming Language :: Python :: 3.6 Programming Language :: Python :: 3.7 Programming Language :: Python :: 3.8 Programming Language :: Python :: 3.9 Topic :: Internet :: WWW/HTTP :: Dynamic Content Topic :: Software Development :: Libraries :: Python Modules
版本列表
1.0.6 2022-09-24
1.0.5 2022-02-05
1.0.4 2022-01-16
1.0.3 2022-01-16
1.0.2 2021-01-23
1.0.1 2020-06-03
1.0.0 2020-02-16
0.2.0 2019-04-08
0.1.0 2018-03-24
0.0.10 2016-10-14
0.0.9 2016-10-14
0.0.8 2016-06-07
0.0.7 2016-05-31
0.0.6 2016-04-19
0.0.5 2016-04-17
0.0.4 2015-03-04
0.0.3 2015-03-04
0.0.2 2014-03-12
0.0.1 2013-02-12