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)

Author: medmunds

.github/workflows/release.yml

@@ -24,41 +24,43 @@ jobs:
     steps:
       - name: Get code
         uses: actions/checkout@v3
+
       - name: Setup Python
         uses: actions/setup-python@v4
         with:
           python-version: "3.10"
 
+      - name: Install build requirements
+        run: |
+          python -m pip install --upgrade build hatch twine
+
       - name: Get version
         # (This will end the workflow if git and source versions don't match.)
         id: version
         run: |
-          VERSION="$(python setup.py --version)"
+          VERSION="$(python -m hatch version)"
           TAG="v$VERSION"
           GIT_TAG="$(git tag -l --points-at "$GITHUB_REF" 'v*')"
-          if [ "$GIT_TAG" != "$TAG" ]; then
+          if [ "x$GIT_TAG" != "x$TAG" ]; then
             echo "::error ::package version '$TAG' does not match git tag '$GIT_TAG'"
             exit 1
           fi
           echo "version=$VERSION" >> $GITHUB_OUTPUT
           echo "tag=$TAG" >> $GITHUB_OUTPUT
           echo "anchor=${TAG//[^[:alnum:]]/-}" >> $GITHUB_OUTPUT
 
-      - name: Install build requirements
-        run: |
-          pip install twine wheel
       - name: Build
         run: |
           rm -rf build dist django_anymail.egg-info
-          python setup.py sdist bdist_wheel
-          twine check dist/*
+          python -m build
+          python -m twine check dist/*
 
       - name: Publish to PyPI
         env:
           TWINE_USERNAME: __token__
           TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
         run: |
-          twine upload dist/*
+          python -m twine upload dist/*
 
       - name: Release to GitHub
         env:

ADDING_ESPS.md

@@ -38,6 +38,20 @@ tests regularly. That requires the ESP have a free tier (testing is
 extremely low volume), a sandbox API, or that they offer developer
 accounts for open source projects like Anymail.
 
+## Boilerplate
+
+You should add entries for your ESP in:
+
+- pyproject.toml:
+  - in the `[project]` metadata section under `description` and `keywords`
+  - in the `[project.optional-dependencies]` section
+- integration-test.yml in the test matrix
+- tox.ini in the `[testenv]` section under `setenv`
+  - if your ESP requires any extra dependencies, also update the tox.ini
+    `[testenv] extras` and the "partial installation" at the bottom of
+    `[tox] envlist`
+- README.rst in the list of ESPs
+
 ## EmailBackend and payload
 
 Anymail abstracts a lot of common functionality into its base classes;
@@ -99,9 +113,6 @@ Need to parse JSON in the API response? Use `self.deserialize_json_response()`
 
 Good starting points: Test backend; SparkPost
 
-Don't forget add an `'extras_require'` entry for your ESP in setup.py.
-Also update `'tests_require'`.
-
 If the client lib supports the notion of a reusable API "connection"
 (or session), you should override `open()` and `close()` to provide
 API state caching. See the notes in the base implementation.

AUTHORS.txt

@@ -33,9 +33,25 @@ vNext
 Breaking changes
 ~~~~~~~~~~~~~~~~
 
+* **Amazon SES:** The "extra name" for installation must now be spelled with
+  a hyphen rather than an underscore: ``django-anymail[amazon-ses]``.
+  Be sure to update any dependencies specification (pip install, requirements.txt,
+  etc.) that had been using ``[amazon_ses]``.
+
 * Require Python 3.7 or later.
+
 * Require urllib3 1.25 or later (released 2019-04-29).
 
+Other
+~~~~~
+
+* Modernize packaging. (Change from setup.py and setuptools
+  to pyproject.toml and hatchling.) Other than the ``amazon-ses``
+  naming normalization noted above, the new packaging should have
+  no impact. If you have trouble installing django-anymail v10 where
+  v9 worked, please report an issue including the exact install
+  command and pip version you are using.
+
 
 v9.2
 -----

CHANGELOG.rst

@@ -5,9 +5,8 @@ Anymail: Django email integration for transactional ESPs
     * Github: project page, exactly as it appears here
     * Docs: shared-intro section gets included in docs/index.rst
             quickstart section gets included in docs/quickstart.rst
-    * PyPI: project page (via setup.py long_description),
-            with several edits to freeze it to the specific PyPI release
-            (see long_description_from_readme in setup.py)
+    * PyPI: project page (via pyproject.toml readme; see also
+            hatch_build.py which edits in the release version number)
     You can use docutils 1.0 markup, but *not* any Sphinx additions.
     GitHub rst supports code-block, but *no other* block directives.
 

MANIFEST.in

@@ -1,7 +1,17 @@
-# Expose package version at root of package
-from django import VERSION as DJANGO_VERSION
+from ._version import VERSION, __version__
 
-from ._version import VERSION, __version__  # NOQA: F401
+__all__ = [
+    "VERSION",
+    "__version__",
+]
 
-if DJANGO_VERSION < (3, 2, 0):
-    default_app_config = "anymail.apps.AnymailBaseConfig"
+try:
+    import django
+except ImportError:
+    # (don't require django just to get package version)
+    pass
+else:
+    if django.VERSION < (3, 2, 0):
+        # (No longer required -- and causes deprecation warning -- in Django 3.2+)
+        default_app_config = "anymail.apps.AnymailBaseConfig"
+        __all__.append("default_app_config")

README.rst

@@ -1,7 +1,7 @@
-VERSION = (9, 2)
+# Don't import this file directly (unless you are a build system).
+# Instead, load version info from the package root.
 
 #: major.minor.patch or major.minor.devN
-__version__ = ".".join([str(x) for x in VERSION])
+__version__ = "10.0.dev0"
 
-#: Sphinx's X.Y "version"
-__minor_version__ = ".".join([str(x) for x in VERSION[:2]])
+VERSION = __version__.split(",")

anymail/__init__.py

@@ -13,7 +13,7 @@
     from botocore.exceptions import BotoCoreError, ClientError, ConnectionError
 except ImportError as err:
     raise AnymailImproperlyInstalled(
-        missing_package="boto3", backend="amazon_ses"
+        missing_package="boto3", install_extra="amazon-ses"
     ) from err
 
 

anymail/_version.py

@@ -14,7 +14,7 @@
     from botocore.exceptions import BotoCoreError, ClientError, ConnectionError
 except ImportError as err:
     raise AnymailImproperlyInstalled(
-        missing_package="boto3", backend="amazon_sesv2"
+        missing_package="boto3", install_extra="amazon-ses"
     ) from err