pintos-utils 1.0.0__tar.gz

pintos_utils-1.0.0/.gitignore

@@ -0,0 +1,17 @@
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.env
+.env.*
+!.env.example
+.DS_Store

pintos_utils-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivaney Vieira de Sales
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pintos_utils-1.0.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.5
+Name: pintos-utils
+Version: 1.0.0
+Summary: Reusable, provider-neutral utilities for Python applications.
+Project-URL: Source, https://github.com/PINTOS-LTDA/python-utils
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Provides-Extra: gmail
+Requires-Dist: google-api-python-client<3,>=2.150; extra == 'gmail'
+Requires-Dist: google-auth-httplib2<1,>=0.2; extra == 'gmail'
+Requires-Dist: google-auth<3,>=2.35; extra == 'gmail'
+Description-Content-Type: text/markdown
+
+# pintos-utils
+
+Reusable Python utilities for application projects. The package is framework
+independent and keeps provider-specific integrations optional.
+
+## Installation
+
+Install the published base package from PyPI:
+
+```bash
+python -m pip install pintos-utils
+uv add pintos-utils
+```
+
+For Gmail support and its optional Google dependencies:
+
+```bash
+python -m pip install "pintos-utils[gmail]"
+uv add "pintos-utils[gmail]"
+```
+
+Install the base package from a local checkout:
+
+```bash
+uv pip install .
+```
+
+For editable development:
+
+```bash
+uv pip install -e .
+```
+
+Install the Gmail integration and its optional dependencies when needed:
+
+```bash
+uv pip install "pintos-utils[gmail] @ git+ssh://git@<git-host>/<org>/pintos-utils.git@<tag-or-commit>"
+```
+
+The base package has no third-party runtime dependencies. Configure SSH access
+using the consuming environment; do not put credentials in the Git URL.
+
+## Email module
+
+See [docs/email.md](docs/email.md) for the provider-neutral API, Gmail OAuth
+ownership, error behavior, and installation examples.
+
+## Development
+
+Use Python 3.11 and uv to create the environment and install development tools:
+
+```bash
+uv sync --group dev
+```
+
+Run the tests, lint, formatting check, type check, and package build:
+
+```bash
+uv run pytest --cov=pintos_utils --cov-report=term-missing
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src
+uv build
+```

pintos_utils-1.0.0/README.md

@@ -0,0 +1,64 @@
+# pintos-utils
+
+Reusable Python utilities for application projects. The package is framework
+independent and keeps provider-specific integrations optional.
+
+## Installation
+
+Install the published base package from PyPI:
+
+```bash
+python -m pip install pintos-utils
+uv add pintos-utils
+```
+
+For Gmail support and its optional Google dependencies:
+
+```bash
+python -m pip install "pintos-utils[gmail]"
+uv add "pintos-utils[gmail]"
+```
+
+Install the base package from a local checkout:
+
+```bash
+uv pip install .
+```
+
+For editable development:
+
+```bash
+uv pip install -e .
+```
+
+Install the Gmail integration and its optional dependencies when needed:
+
+```bash
+uv pip install "pintos-utils[gmail] @ git+ssh://git@<git-host>/<org>/pintos-utils.git@<tag-or-commit>"
+```
+
+The base package has no third-party runtime dependencies. Configure SSH access
+using the consuming environment; do not put credentials in the Git URL.
+
+## Email module
+
+See [docs/email.md](docs/email.md) for the provider-neutral API, Gmail OAuth
+ownership, error behavior, and installation examples.
+
+## Development
+
+Use Python 3.11 and uv to create the environment and install development tools:
+
+```bash
+uv sync --group dev
+```
+
+Run the tests, lint, formatting check, type check, and package build:
+
+```bash
+uv run pytest --cov=pintos_utils --cov-report=term-missing
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src
+uv build
+```

pintos_utils-1.0.0/docs/email.md

@@ -0,0 +1,171 @@
+# Email API
+
+`pintos-utils` exposes provider-neutral message models and the `EmailSender`
+contract from `pintos_utils.email`. Gmail is an optional adapter. Applications
+can inject another implementation of the same contract without changing the
+code that builds messages.
+
+## Installation
+
+Install the published base package from PyPI:
+
+```bash
+python -m pip install pintos-utils
+uv add pintos-utils
+```
+
+For Gmail support, request the optional extra:
+
+```bash
+python -m pip install "pintos-utils[gmail]"
+uv add "pintos-utils[gmail]"
+```
+
+Install the base package from a checkout with pip or uv:
+
+```bash
+python -m pip install .
+uv pip install .
+```
+
+For editable development with Gmail support:
+
+```bash
+python -m pip install -e ".[gmail]"
+uv pip install -e ".[gmail]"
+```
+
+The base package has no third-party runtime dependencies. The `gmail` extra
+installs the Google API and authentication libraries. Importing
+`pintos_utils.email` does not load them. Import the adapter explicitly when the
+extra is installed:
+
+```python
+from pintos_utils.email.providers.gmail import GmailEmailSender
+```
+
+For an authorized private SSH Git repository, use a reviewed tag or, for a
+reproducible production pin, a full commit hash:
+
+```bash
+python -m pip install "pintos-utils[gmail] @ git+ssh://git@<git-host>/<org>/pintos-utils.git@<full-commit-sha>"
+uv add "pintos-utils[gmail] @ git+ssh://git@<git-host>/<org>/pintos-utils.git@<full-commit-sha>"
+```
+
+Replace the placeholders with the repository location and revision. SSH agent,
+deploy key, or the environment's Git credential helper must already grant
+access. Do not put passwords or tokens in the URL or committed dependency
+configuration.
+
+## Public contract
+
+The provider-neutral API exports:
+
+- `EmailAddress(address, display_name=None)`
+- `EmailAttachment(filename, content, content_type=None)`
+- `EmailMessage(sender, subject, to=(), cc=(), bcc=(), text_body=None, html_body=None, attachments=())`
+- `EmailSender`, a structural protocol with `send(message, /) -> SendResult`
+- `SendResult(provider, provider_message_id=None)`
+- `EmailError`, `EmailValidationError`, `EmailConfigurationError`,
+  `EmailAuthenticationError`, and `EmailProviderError`
+
+Models are frozen dataclasses. Recipient and attachment collections are stored
+as tuples. At least one recipient across To, CC, and BCC and at least one body
+format are required. Supplying both text and HTML sends them as alternatives.
+Header line breaks are rejected. Attachments are passed as in-memory bytes; the
+library does not read paths.
+
+```python
+from pintos_utils.email import EmailAddress, EmailAttachment, EmailMessage
+
+message = EmailMessage(
+    sender=EmailAddress("reports@example.com", "Reports"),
+    to=(EmailAddress("person@example.net"),),
+    cc=(EmailAddress("team@example.net"),),
+    bcc=(EmailAddress("archive@example.net"),),
+    subject="Monthly report",
+    text_body="The report is attached.",
+    html_body="<p>The report is attached.</p>",
+    attachments=(
+        EmailAttachment("report.csv", csv_bytes, "text/csv"),
+        EmailAttachment("chart.png", image_bytes, "image/png"),
+    ),
+)
+```
+
+## Gmail OAuth and sending
+
+The application owns OAuth client configuration, the initial consent flow,
+refresh-token persistence, and secret storage. It passes configured Google
+credentials to the adapter. Request the narrow
+`https://www.googleapis.com/auth/gmail.send` scope, available as
+`GMAIL_SEND_SCOPE`. Google Auth refreshes an invalid access token when a refresh
+token is available; this library does not start an interactive OAuth flow or
+persist tokens.
+
+```python
+from google.oauth2.credentials import Credentials
+
+from pintos_utils.email.providers.gmail import (
+    GMAIL_SEND_SCOPE,
+    GmailEmailSender,
+)
+
+credentials = Credentials(
+    token=access_token,
+    refresh_token=refresh_token,
+    token_uri=token_uri,
+    client_id=client_id,
+    client_secret=client_secret,
+    scopes=[GMAIL_SEND_SCOPE],
+)
+sender = GmailEmailSender(credentials)
+result = sender.send(message)
+```
+
+`SendResult` means Gmail accepted the request. It does not confirm final delivery
+to every recipient. The result includes `provider == "gmail"` and may include an
+opaque `provider_message_id`.
+
+## Errors and retry policy
+
+Invalid local message data raises `EmailValidationError`. Missing or unusable
+credentials raise `EmailConfigurationError` or `EmailAuthenticationError`.
+Provider or transport failures raise `EmailProviderError`, with a stable
+`provider` value and `retryable: bool | None` advisory. The original SDK or
+transport error is chained as `__cause__`; its text and raw response are not
+copied into the library exception message.
+
+For Gmail, known temporary quota/backend responses are classified as retryable,
+known permanent rejections as non-retryable, and unclassified or transport
+failures as unknown. The adapter never retries automatically. A timeout can
+occur after Gmail accepted the message, so the consuming application must
+consider duplicate-send risk before retrying.
+
+All providers implement the same small contract:
+
+```python
+from pintos_utils.email import EmailMessage, EmailSender, SendResult
+
+
+def send_report(sender: EmailSender, message: EmailMessage) -> SendResult:
+    return sender.send(message)
+```
+
+The Gmail SDK, request objects, MIME payload, HTTP status codes, and provider
+message identifier details remain inside the adapter boundary.
+
+## Versioning
+
+The package uses Semantic Versioning. Version `1.0.0` is the first stable public
+API release, after implementation, validation, and API compatibility review.
+Compatible fixes increment patch, compatible additions increment minor, and
+breaking public API changes increment major.
+
+The compatibility boundary includes the names and signatures exported by
+`pintos_utils.email`, the `GmailEmailSender` and `GMAIL_SEND_SCOPE` adapter
+exports, validation behavior, exception categories, retryability semantics, and
+the meaning of `SendResult`. Gmail request objects, HTTP parsing, MIME assembly,
+and Google SDK types remain implementation details. Future provider adapters
+can be added without changing the shared contract; a change to that contract's
+existing behavior requires a major version.

pintos_utils-1.0.0/docs/releases.md

@@ -0,0 +1,112 @@
+# Release Runbook
+
+This runbook defines the checks and external settings for publishing `pintos-utils` to PyPI through GitHub Actions Trusted Publishing. The workflow does not use a stored PyPI API token.
+
+## Verified Release Identity
+
+| Setting | Required value |
+| --- | --- |
+| GitHub repository | `PINTOS-LTDA/python-utils` |
+| Repository visibility checked | Public (checked 2026-10-21) |
+| PyPI distribution | `pintos-utils` |
+| Source URL | `https://github.com/PINTOS-LTDA/python-utils` |
+| Release workflow file | `.github/workflows/release.yml` (PyPI field: `release.yml`) |
+| GitHub environment and PyPI environment claim | `pypi` |
+| Stable release tag | `vMAJOR.MINOR.PATCH`, without prerelease suffixes |
+| License | MIT; `Ivaney Vieira de Sales`, 2026 |
+
+## Readiness Checks
+
+### GitHub environment approval
+
+The repository was confirmed public on 2026-10-21. GitHub's required-reviewer availability depends on repository visibility and the plan. Confirm in repository settings that the `pypi` environment offers required reviewers before enabling release publication. GitHub documents required reviewers for public repositories on Free, Pro, and Team plans; if the setting is unavailable, stop and resolve account-plan support rather than removing the approval gate. Select the required reviewer(s) from authorized project maintainers; this runbook does not invent reviewer identities.
+
+Configure the `pypi` environment to require approval from `ivaneyvieira`, restrict deployment to the intended stable release tags when supported, and reject a controlled deployment during the no-upload check. This is the sole reviewer identity supplied so far; leave GitHub's optional self-review prevention disabled unless another reviewer is added, or the only reviewer could be unable to approve a release they initiate.
+
+Create and protect the `pypi` environment before configuring PyPI's pending publisher. GitHub automatically creates a missing environment when a workflow references it, but that environment has no protection rules by default. Do not enable the PyPI publisher until the named environment is visible in repository settings with required reviewers and the intended stable-tag restriction. See [GitHub's environment management behavior](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments).
+
+### PyPI name and pending publisher
+
+Review `pintos-utils` against [PyPI's project-name guidance](https://docs.pypi.org/project-management/choosing-a-name/) before configuring it. A `404` from the project JSON endpoint does **not** prove that the name is available. A pending publisher does not reserve a project name; another party may register it before the first authorized upload. PyPI's first-use project creation and publisher authentication are authoritative. If PyPI rejects project creation or publisher authentication, stop before upload and ask the project owner to review the name and publisher settings. Do not rename the distribution automatically.
+
+For a package that does not yet exist on PyPI, configure the pending Trusted Publisher values below and let PyPI attempt project creation only during the first explicitly authorized publication. After PyPI creates the project, confirm that the same publisher is listed as the project's normal Trusted Publisher. Do not treat pending configuration as a reservation or proof of ownership.
+
+### Trusted Publisher fields
+
+Configure the publisher for the project `pintos-utils` with these exact claims:
+
+| PyPI field | Value |
+| --- | --- |
+| Owner | `PINTOS-LTDA` |
+| Repository | `python-utils` |
+| Workflow filename | `release.yml` |
+| Environment | `pypi` |
+
+The effective PyPI publisher record must match the isolated `publish` job in `.github/workflows/release.yml`. Confirm that no additional publisher is configured. Only that job may have `id-token: write`, and no workflow may contain a static PyPI token.
+
+## Workflow and Tag Rules
+
+- Create a GitHub Release only for a reviewed stable tag in the exact form `vMAJOR.MINOR.PATCH`; its version must equal `[project].version` after removing `v`.
+- The release workflow accepts a published, non-prerelease GitHub Release. Branch and pull request validation must not request OIDC or invoke the publisher.
+- Protect creation and update of `v*` tags with a repository ruleset for authorized maintainers. The supplied maintainer identity is `ivaneyvieira`.
+- Pin every third-party action to a reviewed full commit SHA. Keep a version comment beside each pin and review pins when changing an action.
+- The first real PyPI upload requires an explicit release instruction and maintainer approval of the protected environment deployment.
+
+Configure the repository in this order: review the PyPI name guidance; create and verify the protected `pypi` environment and stable-tag restrictions; add the `v*` tag ruleset; then configure PyPI's pending publisher with the exact fields above. This prevents a release from targeting a newly auto-created but unprotected environment.
+
+## Local Checks Before a Release
+
+Run the offline validation from the repository root:
+
+```bash
+uv sync --locked --group dev
+uv run pytest --cov=pintos_utils --cov-report=term-missing
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src scripts/release_preflight.py
+uv run pytest tests/unit/test_release_preflight.py
+uv build --no-sources
+```
+
+Inspect the wheel and sdist. Both must report package `pintos-utils`, the same version, Python `>=3.11`, the `gmail` extra, the source URL, MIT license metadata, and the `LICENSE` file. Confirm there is exactly one expected wheel and one sdist. Do not treat a successful local build as authorization to publish.
+
+## Publisher Approval and Rejection Check
+
+Before any production release, compare the actual PyPI Trusted Publisher settings with the `publish` job's OIDC claims: owner `PINTOS-LTDA`, repository `python-utils`, workflow `release.yml`, and environment `pypi`. Inspect the CI, quality, and release workflows to verify the OIDC permission boundary and absence of static credentials. Any mismatch or additional publisher blocks release readiness.
+
+For a no-upload check, reject a controlled deployment at the protected `pypi` environment and confirm that PyPI received no distribution files. Record the date, workflow run, reviewer outcome, and no-upload observation in the release review record. Do not use an alternate project or distribution as an identity probe.
+
+For an authorized release, the designated reviewer inspects the GitHub Release tag, successful preflight and quality jobs, and the two uploaded workflow artifacts before approving the `pypi` environment. Reject or cancel if any check is missing or unexpected. Rejection must prevent the publisher job from starting; confirm no files were uploaded before considering another attempt. Approval permits the isolated job to publish the already-built files; after completion, verify each file and its provenance as described below.
+
+## Reviewed Action Pins
+
+All third-party actions used by the release and quality workflows must use immutable full commit SHAs. These are the pins currently in the repository; review the upstream release and security notes when changing one.
+
+| Action | Full commit SHA | Reviewed release |
+| --- | --- | --- |
+| `actions/checkout` | `3d3c42e5aac5ba805825da76410c181273ba90b1` | [v7.0.1](https://github.com/actions/checkout/releases/tag/v7.0.1) |
+| `actions/setup-python` | `5fda3b95a4ea91299a34e894583c3862153e4b97` | [v7.0.0](https://github.com/actions/setup-python/releases/tag/v7.0.0) |
+| `astral-sh/setup-uv` | `1c37ad07a6a961277cf70c0d37d6f313000f5884` | [v10.3.0](https://github.com/astral-sh/setup-uv/releases/tag/v10.3.0) |
+| `actions/upload-artifact` | `cf430e030ddbb5b0abf93d22962f4752f3646cd9` | [v7.0.2](https://github.com/actions/upload-artifact/releases/tag/v7.0.2) |
+| `actions/download-artifact` | `9000827ccba6bdab643e8b6fd33ac0654aef8333` | [v8.0.2](https://github.com/actions/download-artifact/releases/tag/v8.0.2) |
+| `pypa/gh-action-pypi-publish` | `7245906fb61fa33a13554f9d5fb856fe61758086` | [v1.14.3](https://github.com/pypa/gh-action-pypi-publish/releases/tag/v1.14.3) |
+
+## Failure Recovery
+
+- **Tag/version mismatch, existing version, inconclusive version check, quality failure, or build failure**: stop before publication, fix the source of failure, then create a new reviewed release tag.
+- **Rejected environment deployment**: no publisher job should run; confirm that no files were uploaded. A later attempt requires a fresh maintainer decision.
+- **PyPI project creation or publisher authentication rejection**: stop before upload, confirm the PyPI name and exact publisher claims with the project owner, and do not switch to a static token or alternate name.
+- **Upload or provenance failure**: inspect PyPI's release files and provenance for each file before any retry. PyPI can accept one distribution before a later upload fails, and published files cannot be replaced in place. Never retry an ambiguous upload blindly.
+- **Missing or mismatched provenance**: do not record the release as complete. Compare each file's digest and attestation with the intended repository, tagged revision, workflow, and environment, then resolve the discrepancy before another release attempt.
+
+## First Authorized Release Follow-up
+
+After an explicitly authorized production upload, verify the PyPI project metadata, install the base package and Gmail extra in clean environments, and check the attestation for the wheel and sdist independently. Record evidence and any blockers in `specs/002-pypi-trusted-publishing/quickstart.md`. Do not mark these checks complete before a successful authorized release.
+
+## References
+
+- [PyPI Trusted Publisher setup](https://docs.pypi.org/trusted-publishers/adding-a-publisher/)
+- [Create a project with a pending publisher](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)
+- [PyPI project-name guidance](https://docs.pypi.org/project-management/choosing-a-name/)
+- [GitHub deployment environments and required reviewers](https://docs.github.com/en/actions/reference/workflows-and-actions/deployments-and-environments)
+- [PyPA publishing action](https://github.com/marketplace/actions/pypi-publish)

pintos_utils-1.0.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pintos-utils"
+version = "1.0.0"
+description = "Reusable, provider-neutral utilities for Python applications."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = []
+
+[project.urls]
+Source = "https://github.com/PINTOS-LTDA/python-utils"
+
+[project.optional-dependencies]
+gmail = [
+    "google-api-python-client>=2.150,<3",
+    "google-auth>=2.35,<3",
+    "google-auth-httplib2>=0.2,<1",
+]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.13,<2",
+    "pytest>=8.3,<10",
+    "pytest-cov>=6,<8",
+    "ruff>=0.9,<1",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pintos_utils"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/pintos_utils/py.typed" = "pintos_utils/py.typed"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/LICENSE",
+    "/README.md",
+    "/docs",
+    "/pyproject.toml",
+    "/src",
+    "/tests",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests/unit"]
+pythonpath = ["src", "tests/unit/email", "scripts"]
+addopts = ["-ra"]
+
+[tool.coverage.run]
+branch = true
+source = ["pintos_utils"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+exclude = ["specs"]
+
+[tool.ruff.lint]
+select = ["B", "E", "F", "I", "UP"]
+
+[tool.mypy]
+python_version = "3.11"
+mypy_path = "src"
+strict = true
+warn_unreachable = true
+show_error_codes = true

pintos_utils-1.0.0/src/pintos_utils/__init__.py

@@ -0,0 +1 @@
+"""Reusable utilities for Python applications."""

pintos_utils-1.0.0/src/pintos_utils/email/__init__.py

@@ -0,0 +1,29 @@
+"""Provider-neutral email models, contracts, and exceptions."""
+
+from pintos_utils.email.contracts import EmailSender
+from pintos_utils.email.exceptions import (
+    EmailAuthenticationError,
+    EmailConfigurationError,
+    EmailError,
+    EmailProviderError,
+    EmailValidationError,
+)
+from pintos_utils.email.models import (
+    EmailAddress,
+    EmailAttachment,
+    EmailMessage,
+    SendResult,
+)
+
+__all__ = [
+    "EmailAddress",
+    "EmailAttachment",
+    "EmailAuthenticationError",
+    "EmailConfigurationError",
+    "EmailError",
+    "EmailMessage",
+    "EmailProviderError",
+    "EmailSender",
+    "EmailValidationError",
+    "SendResult",
+]

pintos_utils-1.0.0/src/pintos_utils/email/contracts.py

@@ -0,0 +1,15 @@
+"""Provider-neutral email service contracts."""
+
+from typing import Protocol
+
+from pintos_utils.email.models import EmailMessage, SendResult
+
+
+class EmailSender(Protocol):
+    """Structural contract implemented by each email provider adapter."""
+
+    def send(self, message: EmailMessage, /) -> SendResult:
+        """Submit one message and return the provider acceptance result."""
+
+
+__all__ = ["EmailSender"]

pintos_utils-1.0.0/src/pintos_utils/email/exceptions.py

@@ -0,0 +1,32 @@
+"""Public exceptions raised by the email module."""
+
+
+class EmailError(Exception):
+    """Base class for errors exposed by ``pintos_utils.email``."""
+
+
+class EmailValidationError(EmailError):
+    """Raised when an email model contains invalid or unsafe values."""
+
+
+class EmailConfigurationError(EmailError):
+    """Raised when provider configuration is missing or unusable."""
+
+
+class EmailAuthenticationError(EmailError):
+    """Raised when provider credentials are rejected or cannot be refreshed."""
+
+
+class EmailProviderError(EmailError):
+    """Raised when a provider request fails or has an indeterminate outcome."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        provider: str,
+        retryable: bool | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.provider = provider
+        self.retryable = retryable