pintos-utils 1.0.0__py3-none-any.whl

pintos_utils/__init__.py

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

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/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/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

pintos_utils/email/models.py

@@ -0,0 +1,119 @@
+"""Immutable provider-neutral email models."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import TypeVar
+
+from pintos_utils.email.exceptions import EmailValidationError
+
+_T = TypeVar("_T")
+_MEDIA_TYPE_PATTERN = re.compile(
+    r"^[!#$%&'*+\-.^_`|~0-9A-Za-z]+/[!#$%&'*+\-.^_`|~0-9A-Za-z]+$"
+)
+
+
+def _reject_line_breaks(value: str, field_name: str) -> None:
+    if "\r" in value or "\n" in value:
+        raise EmailValidationError(f"{field_name} must not contain line breaks")
+
+
+def _immutable_tuple(values: tuple[_T, ...], field_name: str) -> tuple[_T, ...]:
+    try:
+        return tuple(values)
+    except TypeError as error:
+        raise EmailValidationError(f"{field_name} must be an iterable") from error
+
+
+@dataclass(frozen=True, slots=True)
+class EmailAddress:
+    """One email address with an optional display name."""
+
+    address: str
+    display_name: str | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.address, str) or not self.address.strip():
+            raise EmailValidationError("address must be a non-empty string")
+        _reject_line_breaks(self.address, "address")
+        if self.display_name is not None:
+            if not isinstance(self.display_name, str):
+                raise EmailValidationError("display_name must be a string or None")
+            _reject_line_breaks(self.display_name, "display_name")
+
+
+@dataclass(frozen=True, slots=True)
+class EmailAttachment:
+    """An attachment whose bytes have already been read by the caller."""
+
+    filename: str
+    content: bytes
+    content_type: str | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.filename, str) or not self.filename.strip():
+            raise EmailValidationError("filename must be a non-empty string")
+        _reject_line_breaks(self.filename, "filename")
+        if not isinstance(self.content, bytes):
+            raise EmailValidationError("content must be bytes")
+        if self.content_type is not None:
+            if not isinstance(
+                self.content_type, str
+            ) or not _MEDIA_TYPE_PATTERN.fullmatch(self.content_type):
+                raise EmailValidationError("content_type must be a valid MIME type")
+
+
+@dataclass(frozen=True, slots=True)
+class EmailMessage:
+    """Immutable message input shared by all provider implementations."""
+
+    sender: EmailAddress
+    subject: str
+    to: tuple[EmailAddress, ...] = ()
+    cc: tuple[EmailAddress, ...] = ()
+    bcc: tuple[EmailAddress, ...] = ()
+    text_body: str | None = None
+    html_body: str | None = None
+    attachments: tuple[EmailAttachment, ...] = ()
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.sender, EmailAddress):
+            raise EmailValidationError("sender must be an EmailAddress")
+        if not isinstance(self.subject, str):
+            raise EmailValidationError("subject must be a string")
+        _reject_line_breaks(self.subject, "subject")
+
+        for field_name in ("to", "cc", "bcc", "attachments"):
+            values = _immutable_tuple(getattr(self, field_name), field_name)
+            object.__setattr__(self, field_name, values)
+
+        recipients = (*self.to, *self.cc, *self.bcc)
+        if not recipients:
+            raise EmailValidationError("message must have at least one recipient")
+        if any(not isinstance(recipient, EmailAddress) for recipient in recipients):
+            raise EmailValidationError("recipients must be EmailAddress instances")
+        if any(not isinstance(item, EmailAttachment) for item in self.attachments):
+            raise EmailValidationError("attachments must be EmailAttachment instances")
+        if self.text_body is None and self.html_body is None:
+            raise EmailValidationError("message must have a text_body or html_body")
+        if self.text_body is not None and not isinstance(self.text_body, str):
+            raise EmailValidationError("text_body must be a string or None")
+        if self.html_body is not None and not isinstance(self.html_body, str):
+            raise EmailValidationError("html_body must be a string or None")
+
+
+@dataclass(frozen=True, slots=True)
+class SendResult:
+    """Provider acceptance result; it does not imply recipient delivery."""
+
+    provider: str
+    provider_message_id: str | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.provider, str) or not self.provider.strip():
+            raise EmailValidationError("provider must be a non-empty string")
+        if self.provider_message_id is not None and not isinstance(
+            self.provider_message_id, str
+        ):
+            raise EmailValidationError("provider_message_id must be a string or None")

pintos_utils/email/providers/__init__.py

@@ -0,0 +1 @@
+"""Optional email provider implementations."""

pintos_utils/email/providers/gmail/__init__.py

@@ -0,0 +1,16 @@
+"""Optional Gmail email provider adapter."""
+
+try:
+    from pintos_utils.email.providers.gmail.sender import (
+        GMAIL_SEND_SCOPE,
+        GmailEmailSender,
+    )
+except ModuleNotFoundError as error:
+    if error.name is None or not error.name.startswith("google"):
+        raise
+    raise ImportError(
+        "Gmail support requires the optional dependencies; "
+        'install pintos-utils with the "gmail" extra.'
+    ) from error
+
+__all__ = ["GMAIL_SEND_SCOPE", "GmailEmailSender"]

pintos_utils/email/providers/gmail/_mime.py

@@ -0,0 +1,46 @@
+"""Private MIME serialization for the Gmail adapter."""
+
+from __future__ import annotations
+
+import base64
+from email import policy
+from email.message import EmailMessage as MimeMessage
+from email.utils import formataddr
+
+from pintos_utils.email.models import EmailAddress, EmailMessage
+
+
+def _format_address(value: EmailAddress) -> str:
+    return formataddr((value.display_name or "", value.address))
+
+
+def serialize_message(message: EmailMessage) -> str:
+    """Return an RFC-compliant message encoded for Gmail's ``raw`` field."""
+    mime = MimeMessage(policy=policy.SMTP)
+    mime["From"] = _format_address(message.sender)
+    if message.to:
+        mime["To"] = ", ".join(_format_address(item) for item in message.to)
+    if message.cc:
+        mime["Cc"] = ", ".join(_format_address(item) for item in message.cc)
+    if message.bcc:
+        mime["Bcc"] = ", ".join(_format_address(item) for item in message.bcc)
+    mime["Subject"] = message.subject
+
+    if message.text_body is not None:
+        mime.set_content(message.text_body)
+        if message.html_body is not None:
+            mime.add_alternative(message.html_body, subtype="html")
+    else:
+        mime.set_content(message.html_body or "", subtype="html")
+
+    for attachment in message.attachments:
+        content_type = attachment.content_type or "application/octet-stream"
+        maintype, subtype = content_type.split("/", maxsplit=1)
+        mime.add_attachment(
+            attachment.content,
+            maintype=maintype,
+            subtype=subtype,
+            filename=attachment.filename,
+        )
+
+    return base64.urlsafe_b64encode(mime.as_bytes()).decode("ascii")

pintos_utils/email/providers/gmail/sender.py

@@ -0,0 +1,153 @@
+"""Optional Gmail API implementation of the provider-neutral email contract."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Protocol, cast
+
+from google.auth.credentials import Credentials
+from google.auth.transport.requests import Request
+from googleapiclient.discovery import build  # type: ignore[import-untyped]
+from googleapiclient.errors import HttpError  # type: ignore[import-untyped]
+
+from pintos_utils.email.contracts import EmailSender
+from pintos_utils.email.exceptions import (
+    EmailAuthenticationError,
+    EmailConfigurationError,
+    EmailProviderError,
+)
+from pintos_utils.email.models import EmailMessage, SendResult
+from pintos_utils.email.providers.gmail._mime import serialize_message
+
+GMAIL_SEND_SCOPE = "https://www.googleapis.com/auth/gmail.send"
+_PROVIDER = "gmail"
+_TRANSIENT_STATUSES = {429, 500, 502, 503, 504}
+_AUTH_REASONS = {"authError", "invalidCredentials", "insufficientPermissions"}
+_PERMANENT_REASONS = {
+    "badRequest",
+    "invalidArgument",
+    "invalidParameter",
+    "notFound",
+    "required",
+    "requestTooLarge",
+}
+
+
+class _RefreshableCredentials(Protocol):
+    @property
+    def valid(self) -> bool: ...
+
+    @property
+    def refresh_token(self) -> str | None: ...
+
+    def refresh(self, request: Request) -> None: ...
+
+
+def _build_service(credentials: Credentials) -> Any:
+    """Create the discovery client at the optional dependency boundary."""
+    return build(
+        "gmail",
+        "v1",
+        credentials=credentials,
+        cache_discovery=False,
+    )
+
+
+def _refresh_request() -> Request:
+    return Request()
+
+
+def _error_reason(error: HttpError) -> str | None:
+    try:
+        payload = json.loads(error.content.decode("utf-8"))
+        entries = payload.get("error", {}).get("errors", [])
+        if entries and isinstance(entries[0], dict):
+            reason = entries[0].get("reason")
+            return reason if isinstance(reason, str) else None
+    except (AttributeError, UnicodeDecodeError, json.JSONDecodeError, TypeError):
+        return None
+    return None
+
+
+def _http_status(error: HttpError) -> int | None:
+    try:
+        return int(error.resp.status)
+    except (AttributeError, TypeError, ValueError):
+        return None
+
+
+def _retryability(status: int | None, reason: str | None) -> bool | None:
+    if status in _TRANSIENT_STATUSES:
+        return True
+    if status == 403:
+        if reason in {"rateLimitExceeded", "userRateLimitExceeded"}:
+            return True
+        if reason in {"dailyLimitExceeded", "domainPolicy"}:
+            return False
+        return None
+    if reason in _PERMANENT_REASONS:
+        return False
+    return None
+
+
+class GmailEmailSender(EmailSender):
+    """Send provider-neutral messages through Gmail using consumer credentials."""
+
+    def __init__(self, credentials: Credentials) -> None:
+        if credentials is None:
+            raise EmailConfigurationError("Gmail credentials are required")
+        self._credentials = credentials
+
+    def _refresh_credentials(self) -> None:
+        credentials = cast(_RefreshableCredentials, self._credentials)
+        if credentials.valid:
+            return
+        if not credentials.refresh_token:
+            raise EmailAuthenticationError(
+                "Gmail credentials are invalid and cannot be refreshed"
+            )
+        try:
+            credentials.refresh(_refresh_request())
+        except Exception as error:
+            raise EmailAuthenticationError("Gmail credential refresh failed") from error
+        if not credentials.valid:
+            raise EmailAuthenticationError(
+                "Gmail credentials remain invalid after refresh"
+            )
+
+    def send(self, message: EmailMessage, /) -> SendResult:
+        """Submit one message and return Gmail's acceptance identifier."""
+        self._refresh_credentials()
+        try:
+            service = _build_service(self._credentials)
+            response = (
+                service.users()
+                .messages()
+                .send(userId="me", body={"raw": serialize_message(message)})
+                .execute()
+            )
+        except HttpError as error:
+            status = _http_status(error)
+            reason = _error_reason(error)
+            if status == 401 or reason in _AUTH_REASONS:
+                raise EmailAuthenticationError("Gmail authentication failed") from error
+            raise EmailProviderError(
+                "Gmail provider request failed",
+                provider=_PROVIDER,
+                retryable=_retryability(status, reason),
+            ) from error
+        except Exception as error:
+            raise EmailProviderError(
+                "Gmail provider request failed",
+                provider=_PROVIDER,
+                retryable=None,
+            ) from error
+
+        message_id = response.get("id") if isinstance(response, dict) else None
+        return SendResult(
+            provider=_PROVIDER,
+            provider_message_id=message_id if isinstance(message_id, str) else None,
+        )
+
+
+__all__ = ["GMAIL_SEND_SCOPE", "GmailEmailSender"]

pintos_utils-1.0.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,14 @@
+pintos_utils/__init__.py,sha256=vQ0eUARsX_kkD0RNaRTniIJ3ayrWIhrU1xCotAHvRaI,50
+pintos_utils/email/__init__.py,sha256=aCeS8MVLavuHHNpZihTUDRFj6lYgkoNe3TYfN4MpWDc,654
+pintos_utils/email/contracts.py,sha256=sI9SimyQ5Q1Z1etXAcrzUjfxlwla2Je9B94BEoiKlq8,411
+pintos_utils/email/exceptions.py,sha256=nT9yGWJCG0uOk2t47_yetQNhOBtChOQirTrt6qp9hrQ,869
+pintos_utils/email/models.py,sha256=j4BTSLaRLB0ANmW4ZxZbSDYCxq2czqtpyEtkHabog5E,4750
+pintos_utils/email/providers/__init__.py,sha256=iS3OuQ3fpi2Rnwivbu24224VY4gG45qtZdkhkRurctw,47
+pintos_utils/email/providers/gmail/__init__.py,sha256=h9Mcsk8qAPCXggFqE-s-AL-K5VjA4yf2bimnibrE4q0,494
+pintos_utils/email/providers/gmail/_mime.py,sha256=4vrK7n_RIQ7I9eZK_p-Vr0cwF9q63orR8hveVVpbwrc,1655
+pintos_utils/email/providers/gmail/sender.py,sha256=ovL-_se7nBe7Z7tvjBxzTKSFxr7vXOyA0qJBZICY7cU,5099
+pintos_utils/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pintos_utils-1.0.0.dist-info/METADATA,sha256=zD3X5duVhd5dTsu7kFx1yjgBmH79H2l4HABGXhVyGWw,1917
+pintos_utils-1.0.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pintos_utils-1.0.0.dist-info/licenses/LICENSE,sha256=rFZDgtLF5UO5xW0DOTxt3udLxNjbUYrbc9okVWo5eMs,1079
+pintos_utils-1.0.0.dist-info/RECORD,,

pintos_utils-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

pintos_utils-1.0.0.dist-info/licenses/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.