mirror of
https://github.com/pacnpal/django-anymail.git
synced 2025-12-20 03:41:05 -05:00
Modernize packaging
Switch to pyproject.toml packaging, using hatchling. - Replace all uses of setup.py with updated equivalent - BREAKING: Change extra name `amazon_ses` to `amazon-ses`, to comply with Python packaging name normalization - Use hatch custom build hook to freeze version number in readme (previously custom setup.py code) - Move separate requirements for dev, docs, tests into their own requirements.txt files - Fix AnymailImproperlyInstalled to correctly refer to package extra name - Update testing documentation - Update docs readme rendering to match PyPI (and avoid setup.py) - In tox tests, use isolated builds and update pip - Remove AUTHORS.txt (it just referred to GitHub)
This commit is contained in:
Mike Edmunds
GitHub
@@ -20,13 +20,13 @@ The `Anymail source code`_ is on GitHub.
|
||||
Contributors
|
||||
------------
|
||||
|
||||
See `AUTHORS.txt`_ for a list of some of the people who have helped
|
||||
See the `contributor chart`_ for a list of some of the people who have helped
|
||||
improve Anymail.
|
||||
|
||||
Anymail evolved from the `Djrill`_ project. Special thanks to the
|
||||
folks from `brack3t`_ who developed the original version of Djrill.
|
||||
|
||||
.. _AUTHORS.txt: https://github.com/anymail/django-anymail/blob/main/AUTHORS.txt
|
||||
.. _contributor chart: https://github.com/anymail/django-anymail/graphs/contributors
|
||||
.. _brack3t: http://brack3t.com/
|
||||
.. _Djrill: https://github.com/brack3t/Djrill
|
||||
|
||||
@@ -72,48 +72,42 @@ Anymail is `tested via GitHub Actions`_ against several combinations of Django
|
||||
and Python versions. Tests are run at least once a week, to check whether ESP APIs
|
||||
and other dependencies have changed out from under Anymail.
|
||||
|
||||
For local development, the recommended test command is
|
||||
:shell:`tox -e django31-py38-all,django20-py35-all,lint`, which tests a representative
|
||||
combination of Python and Django versions. It also runs :pypi:`flake8` and other
|
||||
code-style checkers. Some other test options are covered below, but using this
|
||||
tox command catches most problems, and is a good pre-pull-request check.
|
||||
|
||||
Most of the included tests verify that Anymail constructs the expected ESP API
|
||||
calls, without actually calling the ESP's API or sending any email. So these tests
|
||||
don't require API keys, but they *do* require :pypi:`mock` and all ESP-specific
|
||||
package requirements.
|
||||
|
||||
To run the tests, you can:
|
||||
To run the tests locally, use :pypi:`tox`:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ python setup.py test # (also installs test dependencies if needed)
|
||||
## install tox and other development requirements:
|
||||
$ python -m pip install -r requirements-dev.txt
|
||||
|
||||
Or:
|
||||
## test a representative combination of Python and Django versions:
|
||||
$ tox -e lint,django42-py311-all,django30-py37-all,docs
|
||||
|
||||
## you can also run just some test cases, e.g.:
|
||||
$ tox -e django42-py311-all tests.test_mailgun_backend tests.test_utils
|
||||
|
||||
## to test more Python/Django versions:
|
||||
$ tox --parallel auto # ALL 20+ envs! (in parallel if possible)
|
||||
|
||||
(If your system doesn't come with the necessary Python versions, `pyenv`_ is helpful
|
||||
to install and manage them. Or use the :shell:`--skip-missing-interpreters` tox option.)
|
||||
|
||||
If you don't want to use tox (or have trouble getting it working), you can run
|
||||
the tests in your current Python environment:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ pip install mock boto3 # install test dependencies
|
||||
## install the testing requirements (if any):
|
||||
$ python -m pip install -r tests/requirements.txt
|
||||
|
||||
## run the tests:
|
||||
$ python runtests.py
|
||||
|
||||
## this command can also run just a few test cases, e.g.:
|
||||
$ python runtests.py tests.test_mailgun_backend tests.test_mailgun_webhooks
|
||||
|
||||
Or to test against multiple versions of Python and Django all at once, use :pypi:`tox`.
|
||||
You'll need some version of Python 3 available. (If your system doesn't come
|
||||
with that, `pyenv`_ is a helpful way to install and manage multiple Python versions.)
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ pip install tox # (if you haven't already)
|
||||
$ tox -e django31-py38-all,django20-py35-all,lint # test recommended environments
|
||||
|
||||
## you can also run just some test cases, e.g.:
|
||||
$ tox -e django31-py38-all,django20-py35-all tests.test_mailgun_backend tests.test_utils
|
||||
|
||||
## to test more Python/Django versions:
|
||||
$ tox --parallel auto # ALL 20+ envs! (in parallel if possible)
|
||||
$ tox --skip-missing-interpreters # if some Python versions aren't installed
|
||||
Most of the included tests verify that Anymail constructs the expected ESP API
|
||||
calls, without actually calling the ESP's API or sending any email. (So these
|
||||
tests don't require any API keys.)
|
||||
|
||||
In addition to the mocked tests, Anymail has integration tests which *do* call live ESP APIs.
|
||||
These tests are normally skipped; to run them, set environment variables with the necessary
|
||||
@@ -123,20 +117,19 @@ API keys or other settings. For example:
|
||||
|
||||
$ export ANYMAIL_TEST_MAILGUN_API_KEY='your-Mailgun-API-key'
|
||||
$ export ANYMAIL_TEST_MAILGUN_DOMAIN='mail.example.com' # sending domain for that API key
|
||||
$ tox -e django31-py38-all tests.test_mailgun_integration
|
||||
$ tox -e django42-py311-all tests.test_mailgun_integration
|
||||
|
||||
Check the ``*_integration_tests.py`` files in the `tests source`_ to see which variables
|
||||
are required for each ESP. Depending on the supported features, the integration tests for
|
||||
a particular ESP send around 5-15 individual messages. For ESPs that don't offer a sandbox,
|
||||
these will be real sends charged to your account (again, see the notes in each test case).
|
||||
Be sure to specify a particular testenv with tox's `-e` option, or tox may repeat the tests
|
||||
Be sure to specify a particular testenv with tox's :shell:`-e` option, or tox will repeat the tests
|
||||
for all 20+ supported combinations of Python and Django, sending hundreds of messages.
|
||||
|
||||
|
||||
.. _pyenv: https://github.com/pyenv/pyenv
|
||||
.. _tested via GitHub Actions: https://github.com/anymail/django-anymail/actions?query=workflow:test
|
||||
.. _tests source: https://github.com/anymail/django-anymail/blob/main/tests
|
||||
.. _.travis.yml: https://github.com/anymail/django-anymail/blob/main/.travis.yml
|
||||
|
||||
|
||||
Documentation
|
||||
@@ -155,14 +148,14 @@ It's easiest to build Anymail's docs using tox:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ pip install tox # (if you haven't already)
|
||||
$ python -m pip install -r requirements-dev.txt
|
||||
$ tox -e docs # build the docs using Sphinx
|
||||
|
||||
You can run Python's simple HTTP server to view them:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ (cd .tox/docs/_html; python3 -m http.server 8123 --bind 127.0.0.1)
|
||||
$ (cd .tox/docs/_html; python -m http.server 8123 --bind 127.0.0.1)
|
||||
|
||||
... and then open http://localhost:8123/ in a browser. Leave the server running,
|
||||
and just re-run the tox command and refresh your browser as you make changes.
|
||||
|
||||
Reference in New Issue
Block a user