uzsms 2.0.0__py3-none-any.whl

uzsms/__init__.py

@@ -0,0 +1,66 @@
+"""uzsms: SMS sending API for Django.
+
+This module defines the package's public API surface (``__all__``) and
+must stay free of two things: reading ``SMS_SETTINGS`` at import time, and
+importing Django models at module level. Django imports an app's
+``__init__.py`` while populating the app registry, before it is ready --
+an eager import of anything that reaches ``uzsms.models`` (directly, or
+transitively through ``uzsms.services`` or ``uzsms.repository``) would
+raise ``AppRegistryNotReady``. Names that reach the ORM are therefore
+resolved lazily, on first attribute access, via a module-level
+``__getattr__`` (PEP 562).
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+from uzsms.backends import get_async_backend, get_backend
+from uzsms.dto import SendResult, SmsMessage
+from uzsms.exceptions import (
+    SmsBackendError,
+    SmsConfigurationError,
+    SmsError,
+    SmsProviderError,
+    SmsTransportError,
+    SmsValidationError,
+)
+
+__all__ = [
+    "AsyncSmsClient",
+    "SMS_Sender",
+    "SendResult",
+    "SmsBackendError",
+    "SmsClient",
+    "SmsConfigurationError",
+    "SmsError",
+    "SmsLogRecorder",
+    "SmsMessage",
+    "SmsProviderError",
+    "SmsTransportError",
+    "SmsValidationError",
+    "get_async_backend",
+    "get_backend",
+]
+
+# Names that resolve lazily, via __getattr__ below, because importing their
+# home module reaches Django models (directly or transitively).
+_LAZY_ATTRS: dict[str, tuple[str, str]] = {
+    "SmsClient": ("uzsms.services", "SmsClient"),
+    "AsyncSmsClient": ("uzsms.services", "AsyncSmsClient"),
+    "SmsLogRecorder": ("uzsms.repository", "SmsLogRecorder"),
+    "SMS_Sender": ("uzsms.compat", "SMS_Sender"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    target = _LAZY_ATTRS.get(name)
+    if target is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    module_name, attr_name = target
+    module = importlib.import_module(module_name)
+    value = getattr(module, attr_name)
+    globals()[name] = value
+    return value

uzsms/admin.py

@@ -0,0 +1,30 @@
+"""Admin registration for uzsms models."""
+
+from __future__ import annotations
+
+from django.contrib import admin
+
+from .models import SmsLog
+
+
+@admin.register(SmsLog)
+class SmsLogAdmin(admin.ModelAdmin):
+    list_display = (
+        "id",
+        "phone_number",
+        "text",
+        "status",
+        "created_at",
+        "sent_at",
+    )
+    list_display_links = ("id", "phone_number")
+    list_filter = ("status", "created_at")
+    search_fields = ("phone_number", "message_id")
+    date_hierarchy = "created_at"
+    readonly_fields = (
+        "provider_response",
+        "error",
+        "created_at",
+        "sent_at",
+        "message_id",
+    )

uzsms/api/__init__.py

@@ -0,0 +1,9 @@
+"""The uzsms HTTP API.
+
+Everything under this package depends on Django REST Framework, an
+optional extra (``uzsms[drf]``). ``uzsms/urls.py`` is the guarded
+entry point that host projects include; importing anything under this
+package directly requires DRF to already be installed.
+"""
+
+from __future__ import annotations

uzsms/api/responses.py

@@ -0,0 +1,36 @@
+"""The uzsms API's uniform response envelope.
+
+Owner decision D2 (binding): every response body this API produces —
+success or failure — has exactly the keys ``success``, ``data``, and
+``error``. This module is the ONE place that envelope is constructed; no
+view or exception handler may build that dict inline.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rest_framework.response import Response
+
+
+def success_response(data: dict[str, Any], status_code: int) -> Response:
+    """Build a success envelope carrying ``data``, with ``error`` set to ``None``."""
+    return Response({"success": True, "data": data, "error": None}, status=status_code)
+
+
+def error_response(
+    code: str,
+    message: str,
+    detail: Any = None,
+    *,
+    status_code: int,
+) -> Response:
+    """Build a failure envelope carrying an ``error`` object, with ``data`` set to ``None``."""
+    return Response(
+        {
+            "success": False,
+            "data": None,
+            "error": {"code": code, "message": message, "detail": detail},
+        },
+        status=status_code,
+    )

uzsms/api/serializers.py

@@ -0,0 +1,34 @@
+"""Serializers for the uzsms API.
+
+``SendSmsSerializer`` delegates all validation to :mod:`uzsms.validators` —
+the single source of truth for phone number and message text rules —
+rather than reimplementing it. This replaces 1.0.1's ``ValidatePhoneNumber``
+serializer, which reimplemented a weak ``len(phone_number) != 12`` check of
+its own and assigned directly to the DRF-internal ``self._errors``.
+"""
+
+from __future__ import annotations
+
+from rest_framework import serializers
+
+from uzsms.exceptions import SmsValidationError
+from uzsms.validators import validate_message_text, validate_uz_phone
+
+
+class SendSmsSerializer(serializers.Serializer):
+    """Validates the payload for :class:`uzsms.api.views.SendSmsAPIView`."""
+
+    phone_number = serializers.CharField()
+    message = serializers.CharField()
+
+    def validate_phone_number(self, value: str) -> str:
+        try:
+            return validate_uz_phone(value)
+        except SmsValidationError as exc:
+            raise serializers.ValidationError(str(exc)) from exc
+
+    def validate_message(self, value: str) -> str:
+        try:
+            return validate_message_text(value)
+        except SmsValidationError as exc:
+            raise serializers.ValidationError(str(exc)) from exc

uzsms/api/urls.py

@@ -0,0 +1,18 @@
+"""URLconf for the uzsms API.
+
+Host projects include this (indirectly, via ``uzsms.urls``) under their
+own prefix, e.g. ``path("sms/", include("uzsms.urls"))`` — which, with
+owner decision D7's route path, puts the send endpoint at ``/sms/send/``.
+"""
+
+from __future__ import annotations
+
+from django.urls import path
+
+from uzsms.api.views import send_sms_api_view
+
+app_name = "uzsms"
+
+urlpatterns = [
+    path("send/", send_sms_api_view, name="send_sms"),
+]

uzsms/api/views.py

@@ -0,0 +1,195 @@
+"""Views for the uzsms API.
+
+Fixes the two worst defects in 1.0.1's ``uzsms/views.py``:
+
+1. **Open relay.** The old view hardcoded ``permission_classes =
+   [AllowAny]``, so anyone on the internet could send SMS through the
+   operator's broker credentials. ``SendSmsAPIView.get_permissions``
+   resolves ``sms_settings.PERMISSION_CLASSES`` (default
+   ``IsAuthenticated``) lazily via ``import_string``, so authentication is
+   required by default and a host project can only relax it deliberately,
+   through its own settings.
+2. **Unserializable response.** The old view did ``return
+   Response(result)`` where ``result`` was a raw ``requests.Response``
+   object, which DRF cannot render — every request to it crashed. Every
+   body this view returns is built by :mod:`uzsms.api.responses`, whose
+   envelope contains only JSON-primitive values.
+
+``handle_exception`` re-shapes DRF's own error responses (authentication,
+permission, throttling, parsing, and validation failures) into the same
+envelope, by delegating to DRF's default exception handling for status
+codes and headers and then rewriting only the body.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.utils.module_loading import import_string
+from rest_framework.exceptions import APIException
+from rest_framework.exceptions import AuthenticationFailed as DRFAuthenticationFailed
+from rest_framework.exceptions import NotAuthenticated as DRFNotAuthenticated
+from rest_framework.exceptions import PermissionDenied as DRFPermissionDenied
+from rest_framework.exceptions import Throttled as DRFThrottled
+from rest_framework.exceptions import ValidationError as DRFValidationError
+from rest_framework.permissions import BasePermission
+from rest_framework.response import Response
+from rest_framework.throttling import ScopedRateThrottle
+from rest_framework.views import APIView
+
+from uzsms.api.responses import error_response, success_response
+from uzsms.api.serializers import SendSmsSerializer
+from uzsms.conf import sms_settings
+from uzsms.exceptions import SmsProviderError, SmsTransportError, SmsValidationError
+from uzsms.models import SmsLog
+from uzsms.services import SmsClient
+
+# Maps a DRF exception type to the error code this API reports for it.
+# Checked in order, most specific first; anything else that reaches
+# ``handle_exception`` falls back to the exception's own ``default_code``.
+_DRF_ERROR_CODES: tuple[tuple[type[APIException], str], ...] = (
+    (DRFThrottled, "throttled"),
+    (DRFNotAuthenticated, "authentication_failed"),
+    (DRFAuthenticationFailed, "authentication_failed"),
+    (DRFPermissionDenied, "permission_denied"),
+    (DRFValidationError, "validation_error"),
+)
+
+
+def _error_code_for(exc: Exception) -> str:
+    for exc_type, code in _DRF_ERROR_CODES:
+        if isinstance(exc, exc_type):
+            return code
+    if isinstance(exc, APIException):
+        return str(exc.default_code)
+    return "error"
+
+
+class _SendSmsThrottle(ScopedRateThrottle):
+    """A :class:`ScopedRateThrottle` whose rate comes from ``SMS_SETTINGS``.
+
+    DRF's own ``ScopedRateThrottle`` reads its rate from
+    ``DEFAULT_THROTTLE_RATES`` in the ``REST_FRAMEWORK`` setting, keyed by
+    scope. This overrides that lookup so ``sms_settings.THROTTLE_RATE``
+    stays the single place the send endpoint's throttle is configured,
+    consistent with every other tunable this package exposes.
+    """
+
+    def get_rate(self) -> str:
+        return sms_settings.THROTTLE_RATE
+
+
+class SendSmsAPIView(APIView):
+    """Sends a single SMS message.
+
+    Requires authentication by default; see the module docstring and
+    ``sms_settings.PERMISSION_CLASSES``.
+    """
+
+    serializer_class = SendSmsSerializer
+    throttle_classes = (_SendSmsThrottle,)
+    throttle_scope = "uzsms.send"
+
+    def get_permissions(self) -> list[BasePermission]:
+        """Resolve permission classes lazily, so tests can override the setting."""
+        permission_paths = sms_settings.PERMISSION_CLASSES
+        return [import_string(path)() for path in permission_paths]
+
+    def post(self, request: Any, *args: Any, **kwargs: Any) -> Response:
+        serializer = self.serializer_class(data=request.data)
+        serializer.is_valid(raise_exception=True)
+
+        phone_number = serializer.validated_data["phone_number"]
+        text = serializer.validated_data["message"]
+
+        client = SmsClient()
+        try:
+            result = client.send(phone_number, text)
+        except SmsValidationError as exc:
+            return error_response("validation_error", str(exc), status_code=400)
+        except SmsProviderError as exc:
+            # ``exc.body`` is the broker's raw, unfiltered response body —
+            # it can carry broker-internal error text, account, or routing
+            # details, and this endpoint's caller (potentially anonymous,
+            # if PERMISSION_CLASSES has been relaxed) is not entitled to
+            # any of that. Only the upstream HTTP status code — not
+            # sensitive — is forwarded; the message stays a fixed, generic
+            # string rather than anything derived from the broker's own
+            # wording.
+            return error_response(
+                "provider_error",
+                "The SMS provider rejected the request.",
+                detail={"status_code": exc.status_code},
+                status_code=502,
+            )
+        except SmsTransportError:
+            # ``str(exc)`` here is whatever the underlying HTTP client
+            # raised (e.g. ``requests``'s ``ConnectionError``/``Timeout``
+            # repr), which routinely embeds the broker's hostname, port,
+            # and URL path — operator infrastructure details this
+            # endpoint's caller (potentially anonymous, if
+            # PERMISSION_CLASSES has been relaxed) is not entitled to.
+            # Mirrors the ``SmsProviderError`` branch above: a fixed,
+            # generic message only. The real detail is still persisted to
+            # ``SmsLog.error`` for operators.
+            return error_response(
+                "transport_error",
+                "The SMS provider could not be reached.",
+                status_code=502,
+            )
+
+        if not result.ok:
+            # ``FAIL_SILENTLY=True`` makes the backend RETURN an ``ok=False``
+            # ``SendResult`` instead of raising one of the exceptions caught
+            # above -- so this branch is the only place that catches that
+            # case. Without it, a failed send under FAIL_SILENTLY fell
+            # through to the 201 success response below. As with the
+            # ``SmsProviderError`` branch above, the broker's raw response
+            # body is never forwarded to the caller; only the log id, so an
+            # operator can look up ``SmsLog.error``/``.provider_response``.
+            return error_response(
+                "provider_error",
+                "The SMS provider rejected the request.",
+                detail={"log_id": result.log_id},
+                status_code=502,
+            )
+
+        # ``result.log_id`` is carried straight out of ``SmsClient.send()``
+        # (see ``uzsms.services._with_log_ids``) — it is the pk of exactly
+        # the log row this result belongs to, no re-query needed. It is
+        # ``None`` when ``sms_settings.LOG_MESSAGES`` is disabled, since no
+        # log row was ever created. ``result.ok`` is always True here — a
+        # ``False`` result returns 502 above, before this point.
+        data = {
+            "message_id": result.message.message_id,
+            "log_id": result.log_id,
+            "phone_number": result.message.phone_number,
+            "status": SmsLog.Status.SENT.value,
+        }
+        return success_response(data, status_code=201)
+
+    def handle_exception(self, exc: Exception) -> Response:
+        """Re-shape DRF's own error responses into this API's envelope.
+
+        Delegates to DRF's default handling for the status code and any
+        headers it attaches (``WWW-Authenticate``, ``Retry-After``), and
+        rewrites only the body — so auth, permission, throttling, and
+        parsing failures never leak DRF's bare ``{"detail": ...}`` shape.
+        """
+        response = super().handle_exception(exc)
+        code = _error_code_for(exc)
+
+        if isinstance(response.data, dict) and set(response.data) == {"detail"}:
+            message = str(response.data["detail"])
+            detail = None
+        else:
+            message = "Invalid request." if code == "validation_error" else str(exc)
+            detail = response.data
+
+        enveloped = error_response(code, message, detail, status_code=response.status_code)
+        for header, value in response.items():
+            enveloped[header] = value
+        return enveloped
+
+
+send_sms_api_view = SendSmsAPIView.as_view()

uzsms/apps.py

@@ -0,0 +1,8 @@
+from django.apps import AppConfig
+
+
+class UzSmsConfig(AppConfig):
+    default_auto_field = 'django.db.models.BigAutoField'
+    name = 'uzsms'
+    label = 'SMS'
+    verbose_name = 'SMS'

uzsms/backends/__init__.py

@@ -0,0 +1,64 @@
+"""Backend loader for uzsms.
+
+Resolves a dotted backend path (``sms_settings.BACKEND`` for
+:func:`get_backend`, ``sms_settings.ASYNC_BACKEND`` for
+:func:`get_async_backend`, when no explicit ``path`` is given) to a backend
+class via :func:`django.utils.module_loading.import_string`, and
+instantiates it. The resolved class is cached per ``(path, base)`` pair so
+repeated calls avoid re-importing; each call still returns a fresh
+*instance*, since backends may hold open connections.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django.utils.module_loading import import_string
+
+from uzsms.backends.base import BaseAsyncSmsBackend, BaseSmsBackend
+from uzsms.conf import sms_settings
+from uzsms.exceptions import SmsConfigurationError
+
+_backend_class_cache: dict[tuple[str, type], type] = {}
+
+
+def _resolve_backend_class(path: str, base: type) -> type:
+    cache_key = (path, base)
+    if cache_key in _backend_class_cache:
+        return _backend_class_cache[cache_key]
+
+    try:
+        backend_class = import_string(path)
+    except ImportError as exc:
+        raise SmsConfigurationError(f"Could not import SMS backend {path!r}: {exc}") from exc
+
+    if not (isinstance(backend_class, type) and issubclass(backend_class, base)):
+        raise SmsConfigurationError(
+            f"SMS backend {path!r} does not resolve to a subclass of {base.__name__}."
+        )
+
+    _backend_class_cache[cache_key] = backend_class
+    return backend_class
+
+
+def get_backend(path: str | None = None, **kwargs: Any) -> BaseSmsBackend:
+    """Resolve and instantiate a synchronous SMS backend.
+
+    Defaults to ``sms_settings.BACKEND`` when ``path`` is ``None``.
+    """
+    resolved_path = sms_settings.BACKEND if path is None else path
+    backend_class = _resolve_backend_class(resolved_path, BaseSmsBackend)
+    return backend_class(**kwargs)
+
+
+def get_async_backend(path: str | None = None, **kwargs: Any) -> BaseAsyncSmsBackend:
+    """Resolve and instantiate an asynchronous SMS backend.
+
+    Defaults to ``sms_settings.ASYNC_BACKEND`` when ``path`` is ``None`` --
+    a separate setting from ``sms_settings.BACKEND`` (which defaults to the
+    *sync* Playmobile backend), so ``SmsClient`` and ``AsyncSmsClient`` can
+    both be constructed from one unmodified ``SMS_SETTINGS`` dict.
+    """
+    resolved_path = sms_settings.ASYNC_BACKEND if path is None else path
+    backend_class = _resolve_backend_class(resolved_path, BaseAsyncSmsBackend)
+    return backend_class(**kwargs)

uzsms/backends/base.py

@@ -0,0 +1,79 @@
+"""Abstract backend interface for uzsms.
+
+This module must not import ``django.conf.settings`` at module import
+time, so that importing ``uzsms.backends.base`` never requires
+``SMS_SETTINGS`` to be configured.
+"""
+
+from __future__ import annotations
+
+import abc
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from uzsms.conf import sms_settings
+from uzsms.dto import SendResult, SmsMessage
+
+if TYPE_CHECKING:
+    from typing_extensions import Self
+
+
+class BaseSmsBackend(abc.ABC):
+    """Abstract base class for synchronous SMS backends.
+
+    Subclasses implement :meth:`send_messages`. ``open``/``close`` are
+    no-ops by default; override them to acquire/release resources such
+    as a pooled HTTP connection.
+    """
+
+    def __init__(self, *, fail_silently: bool | None = None) -> None:
+        self.fail_silently = (
+            sms_settings.FAIL_SILENTLY if fail_silently is None else fail_silently
+        )
+
+    def open(self) -> None:
+        """Open any resources needed to send messages."""
+
+    def close(self) -> None:
+        """Close resources opened by :meth:`open`."""
+
+    def __enter__(self) -> Self:
+        self.open()
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
+        self.close()
+
+    @abc.abstractmethod
+    def send_messages(self, messages: Sequence[SmsMessage]) -> list[SendResult]:
+        """Send ``messages`` and return one :class:`SendResult` per message, in order."""
+
+
+class BaseAsyncSmsBackend(abc.ABC):
+    """Abstract base class for asynchronous SMS backends.
+
+    Mirrors :class:`BaseSmsBackend`, but with an ``async`` ``open``/``close``
+    and ``send_messages``.
+    """
+
+    def __init__(self, *, fail_silently: bool | None = None) -> None:
+        self.fail_silently = (
+            sms_settings.FAIL_SILENTLY if fail_silently is None else fail_silently
+        )
+
+    async def open(self) -> None:
+        """Open any resources needed to send messages."""
+
+    async def close(self) -> None:
+        """Close resources opened by :meth:`open`."""
+
+    async def __aenter__(self) -> Self:
+        await self.open()
+        return self
+
+    async def __aexit__(self, exc_type, exc_value, traceback) -> None:
+        await self.close()
+
+    @abc.abstractmethod
+    async def send_messages(self, messages: Sequence[SmsMessage]) -> list[SendResult]:
+        """Send ``messages`` and return one :class:`SendResult` per message, in order."""

uzsms/backends/console.py

@@ -0,0 +1,33 @@
+"""Console SMS backend.
+
+Writes a readable rendering of each outgoing message to stdout instead of
+sending it. Performs zero network I/O; useful for local development.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from uzsms.backends.base import BaseSmsBackend
+from uzsms.dto import SendResult, SmsMessage
+
+
+class ConsoleBackend(BaseSmsBackend):
+    """Prints each message to stdout and reports it as successfully sent."""
+
+    def send_messages(self, messages: Sequence[SmsMessage]) -> list[SendResult]:
+        results = []
+        for message in messages:
+            print(
+                "\n".join(
+                    (
+                        "-" * 40,
+                        f"To: {message.phone_number}",
+                        f"Message-ID: {message.message_id}",
+                        message.text,
+                        "-" * 40,
+                    )
+                )
+            )
+            results.append(SendResult(message=message, ok=True))
+        return results

uzsms/backends/dummy.py

@@ -0,0 +1,19 @@
+"""Dummy SMS backend.
+
+Discards every message without sending it. Performs zero network I/O;
+useful for tests or environments where SMS sending should be a no-op.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from uzsms.backends.base import BaseSmsBackend
+from uzsms.dto import SendResult, SmsMessage
+
+
+class DummyBackend(BaseSmsBackend):
+    """Discards all messages and reports each as successfully sent."""
+
+    def send_messages(self, messages: Sequence[SmsMessage]) -> list[SendResult]:
+        return [SendResult(message=message, ok=True) for message in messages]

uzsms/backends/locmem.py

@@ -0,0 +1,39 @@
+"""In-memory SMS backend for tests.
+
+Mirrors the idiom of Django's ``django.core.mail.outbox``: every message
+sent through :class:`LocMemBackend` is appended to the module-level
+``outbox`` list, so tests can import this module and inspect it directly
+without holding a reference to the backend instance. Performs zero
+network I/O.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from uzsms.backends.base import BaseAsyncSmsBackend, BaseSmsBackend
+from uzsms.dto import SendResult, SmsMessage
+
+outbox: list[SmsMessage] = []
+
+
+class LocMemBackend(BaseSmsBackend):
+    """Appends each sent message to the module-level :data:`outbox`."""
+
+    def send_messages(self, messages: Sequence[SmsMessage]) -> list[SendResult]:
+        results = []
+        for message in messages:
+            outbox.append(message)
+            results.append(SendResult(message=message, ok=True))
+        return results
+
+
+class AsyncLocMemBackend(BaseAsyncSmsBackend):
+    """Appends each sent message to the same module-level :data:`outbox`."""
+
+    async def send_messages(self, messages: Sequence[SmsMessage]) -> list[SendResult]:
+        results = []
+        for message in messages:
+            outbox.append(message)
+            results.append(SendResult(message=message, ok=True))
+        return results