Modernize project tooling and packaging

.editorconfig

@@ -9,6 +9,6 @@ trim_trailing_whitespace = true
 indent_style = space
 indent_size = 4
 
-[.travis.yml]
+[*.{yaml,yml}]
 indent_style = space
 indent_size = 2

.github/workflows/deploy.yaml

@@ -7,14 +7,19 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags') && github.repository == 'gmr/email-normalize'
-    container: python:3.8-alpine
+    environment: release
+    permissions:
+      contents: read
+      id-token: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v1
+        uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
       - name: Build package
-        run: python3 setup.py sdist
+        run: uv build
+
       - name: Publish package
-        uses: pypa/gh-action-pypi-publish@master
-        with:
-          user: __token__
-          password: ${{ secrets.PYPI_PASSWORD }}
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/docs.yaml

@@ -0,0 +1,53 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'email_normalize/**'
+      - '.github/workflows/docs.yaml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Install dependencies
+        run: uv sync --extra docs
+
+      - name: Build documentation
+        run: uv run mkdocs build --strict
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/testing.yaml

@@ -3,14 +3,12 @@ on:
   pull_request:
     paths-ignore:
       - 'docs/**'
-      - 'setup.*'
       - '*.md'
       - '*.rst'
   push:
     branches: ["*"]
     paths-ignore:
       - 'docs/**'
-      - 'setup.*'
       - '*.md'
       - '*.rst'
     tags-ignore: ["*"]
@@ -19,37 +17,37 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 3
     strategy:
+      fail-fast: false
       matrix:
-        python: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13', '3.14']
-    container:
-      image: python:${{ matrix.python }}-alpine
+        python: ["3.11", "3.12", "3.13", "3.14"]
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v1
+        uses: actions/checkout@v5
 
-      - name: Install OS dependencies
-        run: apk --update add gcc libffi-dev linux-headers make musl-dev
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
 
-      - name: Install testing dependencies
-        run: pip3 --no-cache-dir install -e '.[testing]'
+      - name: Set up Python
+        run: uv python install ${{ matrix.python }}
+
+      - name: Install dependencies
+        run: uv sync --all-extras
 
       - name: Create build directory
-        run: mkdir build
+        run: mkdir -p build
 
-      - name: Run flake8 tests
-        run: flake8
+      - name: Lint Check
+        run: uv run pre-commit run --all-files
 
       - name: Run tests
-        run: coverage run
-
-      - name: Output coverage
-        run: coverage report && coverage xml
+        run: |
+          uv run coverage run
+          uv run coverage report
+          uv run coverage xml
 
       - name: Upload Coverage
-        uses: codecov/codecov-action@v1.0.2
+        uses: codecov/codecov-action@v5
         if: github.event_name == 'push' && github.repository == 'gmr/email-normalize'
         with:
-          token: ${{secrets.CODECOV_TOKEN}}
-          file: build/coverage.xml
+          files: ./build/coverage.xml
           flags: unittests
-          fail_ci_if_error: true

.gitignore

@@ -51,9 +51,8 @@ coverage.xml
 *.log
 *.pot
 
-# Sphinx documentation
-docs/_build/
+# Documentation
+site/
 
 .idea
 .vagrant
-

.pre-commit-config.yaml

@@ -0,0 +1,19 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-ast
+      - id: check-toml
+      - id: check-yaml
+        args: [--allow-multiple-documents]
+      - id: debug-statements
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+      - id: trailing-whitespace
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.5
+    hooks:
+      - id: ruff-format
+      - id: ruff
+        args: [--fix]

CONTRIBUTING.md

@@ -3,12 +3,11 @@
 To get setup in the environment and run the tests, take the following steps:
 
 ```bash
-python3 -m venv env
-source env/bin/activate
-pip install -e '.[test]'
+uv sync --all-extras
+uv run pre-commit install
 
-flake8
-coverage run && coverage report
+uv run pre-commit run --all-files
+uv run coverage run && uv run coverage report
 ```
 
 ## Adding a Mailbox Provider
@@ -22,6 +21,6 @@ Set the flags in the new class appropriately and add tests.
 Pull requests that make changes or additions that are not covered by tests
 will likely be closed without review.
 
-In addition, all tests must pass the tests **AND** flake8 linter. If flake8
+In addition, all tests must pass the tests **AND** ruff linter. If ruff
 exceptions are included, the reasoning for adding the exception must be included
 in the pull request.

MANIFEST.in

@@ -1,4 +1 @@
-include CONTRIBUTING.md
-include LICENSE
-include README.rst
-include VERSION
+include README.md LICENSE

README.md

@@ -0,0 +1,35 @@
+# email-normalize
+
+`email-normalize` is a Python 3.11+ library for returning a normalized email-address
+stripping mailbox-provider-specific behaviors such as "Plus addressing"
+(foo+bar@gmail.com).
+
+![Version](https://img.shields.io/pypi/v/email-normalize.svg?)
+![Status](https://github.com/gmr/email-normalize/workflows/Testing/badge.svg?)
+![Coverage](https://img.shields.io/codecov/c/github/gmr/email-normalize.svg?)
+![License](https://img.shields.io/pypi/l/email-normalize.svg?)
+
+## Example
+
+```python
+import email_normalize
+
+# Returns ``foo@gmail.com``
+normalized = email_normalize.normalize('f.o.o+bar@gmail.com')
+```
+
+## Currently Supported Mailbox Providers
+
+- Apple
+- Fastmail
+- Google
+- Microsoft
+- ProtonMail
+- Rackspace
+- Yahoo
+- Yandex
+- Zoho
+
+## Python Versions Supported
+
+3.11+

docs/api.md

@@ -0,0 +1,36 @@
+# API Reference
+
+## normalize Function
+
+::: email_normalize.normalize
+
+## Normalizer Class
+
+::: email_normalize.Normalizer
+
+## Result Class
+
+::: email_normalize.Result
+
+## MXRecords Type
+
+::: email_normalize.MXRecords
+
+A type alias for a list of tuples containing the priority and host name for
+each record returned during the MX lookup.
+
+```python
+list[tuple[int, str]]
+```
+
+**Example:**
+
+```python
+[
+    (5, 'gmail-smtp-in.l.google.com'),
+    (10, 'alt1.gmail-smtp-in.l.google.com'),
+    (20, 'alt2.gmail-smtp-in.l.google.com'),
+    (30, 'alt3.gmail-smtp-in.l.google.com'),
+    (40, 'alt4.gmail-smtp-in.l.google.com'),
+]
+```