callish 0.1.0__py3-none-any.whl

callish/__init__.py

@@ -0,0 +1,36 @@
+"""callish — Django QuerySet façade for user-written API adapters."""
+
+from __future__ import annotations
+
+from .adapter import AdapterProtocol, BaseAdapter
+from .exceptions import (
+    AdapterError,
+    AdapterValidationError,
+    NotFound,
+    RateLimited,
+    Unauthorized,
+    Upstream5xx,
+)
+from .forms import APIModelForm
+from .manager import APIManager
+from .models import APIModel
+from .queryset import APIQuerySet
+
+__version__ = "0.1.0"
+default_app_config = "callish.apps.CallishConfig"
+
+__all__ = [
+    "AdapterError",
+    "AdapterProtocol",
+    "AdapterValidationError",
+    "APIManager",
+    "APIModel",
+    "APIModelForm",
+    "APIQuerySet",
+    "BaseAdapter",
+    "NotFound",
+    "RateLimited",
+    "Unauthorized",
+    "Upstream5xx",
+    "__version__",
+]

callish/_meta.py

@@ -0,0 +1,117 @@
+"""``_meta`` shim — exposes the surface Django introspects on real models.
+
+Django's ``fields_for_model``, ``ModelForm``, generic class-based views and
+URL reverse helpers all reach into ``model._meta`` for things like
+``concrete_fields``, ``get_field``, ``app_label``, ``model_name``,
+``verbose_name`` etc. This shim provides exactly those — and no more.
+
+Anything Django reaches for that isn't here either lives outside callish's
+v1 scope (relations, indexes, constraints, db_table) or signals a bug.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from typing import TYPE_CHECKING, Any
+
+from django.core.exceptions import FieldDoesNotExist
+from django.db.models import Field
+
+if TYPE_CHECKING:
+    from .models import APIModel
+
+
+_CAMEL_RE = re.compile(r"(?<!^)(?=[A-Z])")
+
+
+def _humanize(name: str) -> str:
+    return _CAMEL_RE.sub(" ", name).strip().lower()
+
+
+class Options:
+    """Drop-in for ``django.db.models.options.Options`` — minimum viable surface."""
+
+    # Marker so external code can tell us apart from a real Options.
+    callish_shim = True
+
+    # Real Django Options uses these to opt out of DB/admin behaviour we never want.
+    proxy = False
+    abstract = False
+    swapped = False
+    auto_created = False
+    managed = False  # we have no DB table
+    is_composite_pk = False  # Django 5.2+ admin compatibility
+
+    # Empty collections that Django iterates blindly.
+    many_to_many: list[Field] = []
+    private_fields: list[Field] = []
+    parents: dict[Any, Any] = {}
+    local_many_to_many: list[Field] = []
+
+    # Admin / changelist hint — not supported for v1.
+    default_permissions: tuple[str, ...] = ()
+    permissions: tuple[Any, ...] = ()
+
+    def __init__(
+        self,
+        *,
+        model: type[APIModel],
+        fields: Iterable[Field],
+        pk_field: Field,
+        app_label: str,
+        object_name: str,
+        verbose_name: str | None = None,
+        verbose_name_plural: str | None = None,
+    ) -> None:
+        self.model = model
+        self.concrete_fields: list[Field] = list(fields)
+        self.local_fields: list[Field] = list(self.concrete_fields)
+        self.local_concrete_fields: list[Field] = list(self.concrete_fields)
+        self.pk: Field = pk_field
+
+        self.app_label = app_label
+        self.object_name = object_name
+        self.model_name = object_name.lower()
+        self.verbose_name = verbose_name or _humanize(object_name)
+        self.verbose_name_plural = verbose_name_plural or f"{self.verbose_name}s"
+
+        # Build a name -> field map for fast lookup.
+        self._field_map: dict[str, Field] = {f.name: f for f in self.concrete_fields}
+
+    # ----- Django Options surface -----------------------------------------
+
+    @property
+    def fields(self) -> tuple[Field, ...]:
+        return tuple(self.concrete_fields)
+
+    @property
+    def label(self) -> str:
+        return f"{self.app_label}.{self.object_name}"
+
+    @property
+    def label_lower(self) -> str:
+        return f"{self.app_label}.{self.model_name}"
+
+    def get_field(self, field_name: str) -> Field:
+        if field_name == "pk":
+            return self.pk
+        try:
+            return self._field_map[field_name]
+        except KeyError as exc:
+            raise FieldDoesNotExist(
+                f"{self.object_name} has no field named {field_name!r}"
+            ) from exc
+
+    def get_fields(
+        self, include_parents: bool = True, include_hidden: bool = False
+    ) -> tuple[Field, ...]:
+        return self.fields
+
+    # Django sometimes calls this to canonicalise the verbose name with case.
+    @property
+    def verbose_name_raw(self) -> str:
+        return str(self.verbose_name)
+
+    def __repr__(self) -> str:
+        return f"<callish Options for {self.label}>"

callish/adapter.py

@@ -0,0 +1,102 @@
+"""Adapter contract — the user-written layer between callish and an HTTP API."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class AdapterProtocol(Protocol):
+    """The structural contract every adapter must satisfy.
+
+    Adapters are plain Python objects. They MAY also subclass :class:`BaseAdapter`
+    for convenience, but it is not required — duck typing is sufficient.
+    """
+
+    def list(
+        self,
+        *,
+        filters: Mapping[str, Any],
+        ordering: Sequence[str],
+        offset: int,
+        limit: int | None,
+    ) -> Sequence[Mapping[str, Any]]: ...
+
+    def retrieve(self, pk: Any) -> Mapping[str, Any]: ...
+
+    def create(self, data: Mapping[str, Any]) -> Mapping[str, Any]: ...
+
+    def update(self, pk: Any, data: Mapping[str, Any]) -> Mapping[str, Any]: ...
+
+    def delete(self, pk: Any) -> None: ...
+
+
+class BaseAdapter:
+    """Optional convenience base for adapters.
+
+    Provides NotImplementedError stubs and a ``supported_lookups`` class attribute
+    that the conformance suite uses to skip lookups the adapter doesn't claim.
+    """
+
+    #: Field-lookup suffixes (e.g. ``"in"``, ``"gte"``) the adapter promises to honour
+    #: when passed in ``filters``. Equality (no suffix) is assumed always supported.
+    supported_lookups: tuple[str, ...] = ("in", "gte", "lte", "contains", "icontains")
+
+    def list(
+        self,
+        *,
+        filters: Mapping[str, Any],
+        ordering: Sequence[str],
+        offset: int,
+        limit: int | None,
+    ) -> Sequence[Mapping[str, Any]]:
+        raise NotImplementedError
+
+    def retrieve(self, pk: Any) -> Mapping[str, Any]:
+        raise NotImplementedError
+
+    def create(self, data: Mapping[str, Any]) -> Mapping[str, Any]:
+        raise NotImplementedError
+
+    def update(self, pk: Any, data: Mapping[str, Any]) -> Mapping[str, Any]:
+        raise NotImplementedError
+
+    def delete(self, pk: Any) -> None:
+        raise NotImplementedError
+
+    def count(self, *, filters: Mapping[str, Any]) -> int | None:
+        """Optional. Return ``None`` to fall back to ``len(list(...))``."""
+        return None
+
+
+def resolve_adapter(spec: Any) -> Any:
+    """Resolve an ``Meta.adapter`` declaration into an instance.
+
+    Accepts:
+      * An adapter instance — returned as-is.
+      * An adapter class — instantiated with no args.
+      * A dotted string ``"pkg.mod:ClassName"`` or ``"pkg.mod.ClassName"`` —
+        imported then instantiated with no args.
+    """
+    if spec is None:
+        raise ValueError("Meta.adapter is required on APIModel subclasses")
+
+    if isinstance(spec, str):
+        from importlib import import_module
+
+        if ":" in spec:
+            module_path, attr = spec.split(":", 1)
+        elif "." in spec:
+            module_path, attr = spec.rsplit(".", 1)
+        else:
+            raise ValueError(
+                f"Adapter spec {spec!r} must be 'pkg.mod:Class' or 'pkg.mod.Class'"
+            )
+        module = import_module(module_path)
+        spec = getattr(module, attr)
+
+    if isinstance(spec, type):
+        return spec()
+
+    return spec

callish/apps.py

@@ -0,0 +1,18 @@
+"""Django app config for callish.
+
+Intentionally inert: no signals, no monkey-patching, no admin-site mutations.
+This keeps callish coexistence-safe with Wagtail and any other framework that
+expects to own its corners of Django.
+"""
+
+from __future__ import annotations
+
+from django.apps import AppConfig
+
+
+class CallishConfig(AppConfig):
+    name = "callish"
+    label = "callish"
+    verbose_name = "callish"
+    # Required for Django to instantiate AppConfig — we have no real models.
+    default_auto_field = "django.db.models.BigAutoField"

callish/exceptions.py

@@ -0,0 +1,51 @@
+"""Exceptions raised by adapters and propagated through the callish façade."""
+
+from __future__ import annotations
+
+
+class AdapterError(Exception):
+    """Base class for all adapter-raised errors."""
+
+
+class NotFound(AdapterError):
+    """The requested record does not exist upstream.
+
+    The façade maps this to the model's ``DoesNotExist`` for Django parity.
+    """
+
+
+class Unauthorized(AdapterError):
+    """Authentication or authorization failed upstream."""
+
+
+class RateLimited(AdapterError):
+    """The upstream API is rate-limiting the caller."""
+
+    def __init__(self, *args: object, retry_after: float | None = None) -> None:
+        super().__init__(*args)
+        self.retry_after = retry_after
+
+
+class Upstream5xx(AdapterError):
+    """The upstream API returned a server error."""
+
+    def __init__(self, *args: object, status: int | None = None) -> None:
+        super().__init__(*args)
+        self.status = status
+
+
+class AdapterValidationError(AdapterError):
+    """The upstream rejected the payload with field-level validation errors.
+
+    ``errors`` is a mapping of field name to a list of error strings,
+    matching Django's ``ValidationError.message_dict`` shape.
+    """
+
+    def __init__(
+        self,
+        message: str = "Adapter validation failed",
+        *,
+        errors: dict[str, list[str]] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.errors: dict[str, list[str]] = errors or {}

callish/fields.py

@@ -0,0 +1,54 @@
+"""Field wrappers — thin shims around ``django.db.models.fields.*`` instances.
+
+These are declared on :class:`callish.APIModel` subclasses but never attached
+to a real DB table. The metaclass calls :meth:`set_attributes_from_name` on
+each so ``field.name`` / ``field.attname`` are populated, which is enough for
+Django's ``fields_for_model`` to introspect them and produce form fields.
+"""
+
+from __future__ import annotations
+
+from django.db import models as dj_models
+
+# Re-export Django field classes verbatim. We intentionally do not subclass:
+# subclasses would inherit ``contribute_to_class`` behaviour that assumes a real
+# Model, and the metaclass already handles attachment.
+CharField = dj_models.CharField
+TextField = dj_models.TextField
+IntegerField = dj_models.IntegerField
+BigIntegerField = dj_models.BigIntegerField
+SmallIntegerField = dj_models.SmallIntegerField
+PositiveIntegerField = dj_models.PositiveIntegerField
+FloatField = dj_models.FloatField
+DecimalField = dj_models.DecimalField
+BooleanField = dj_models.BooleanField
+DateField = dj_models.DateField
+DateTimeField = dj_models.DateTimeField
+TimeField = dj_models.TimeField
+EmailField = dj_models.EmailField
+URLField = dj_models.URLField
+SlugField = dj_models.SlugField
+UUIDField = dj_models.UUIDField
+JSONField = dj_models.JSONField
+BinaryField = dj_models.BinaryField
+
+__all__ = [
+    "BigIntegerField",
+    "BinaryField",
+    "BooleanField",
+    "CharField",
+    "DateField",
+    "DateTimeField",
+    "DecimalField",
+    "EmailField",
+    "FloatField",
+    "IntegerField",
+    "JSONField",
+    "PositiveIntegerField",
+    "SlugField",
+    "SmallIntegerField",
+    "TextField",
+    "TimeField",
+    "URLField",
+    "UUIDField",
+]

callish/forms.py

@@ -0,0 +1,58 @@
+"""``APIModelForm`` — a ``ModelForm`` that talks to adapters instead of the DB.
+
+This subclasses Django's ``ModelForm`` directly: ``ModelFormMetaclass`` only
+needs ``model._meta`` to expose the surface ``fields_for_model`` walks. Our
+``_meta`` shim does. ``_post_clean`` is overridden to skip DB-level validation,
+and ``save`` is overridden to dispatch to ``adapter.create/update``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from django import forms
+from django.core.exceptions import ValidationError
+from django.forms.models import construct_instance
+
+from .exceptions import AdapterValidationError
+
+
+class APIModelForm(forms.ModelForm):
+    """ModelForm replacement that round-trips through an adapter."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+
+    def _post_clean(self) -> None:
+        """Skip the DB-constraint pass; keep the field-level construct_instance."""
+        opts = self._meta
+        try:
+            self.instance = construct_instance(
+                self,
+                self.instance,  # type: ignore[has-type]
+                opts.fields,
+                opts.exclude,
+            )
+        except ValidationError as e:
+            self._update_errors(e)
+        # Intentionally NOT calling self.instance.full_clean() — the adapter is
+        # the source of truth for upstream validation (and would raise
+        # AdapterValidationError on failure during save()).
+
+    def save(self, commit: bool = True) -> Any:
+        """Send the instance through the adapter.
+
+        Adapter errors propagate. :class:`AdapterValidationError` is translated
+        into a form-level :class:`~django.core.exceptions.ValidationError` so
+        downstream code can display per-field messages.
+        """
+        if not commit:
+            # Caller wants to inspect/mutate the instance before persisting.
+            return self.instance
+
+        try:
+            self.instance.save()
+        except AdapterValidationError as exc:
+            self._update_errors(ValidationError(exc.errors or {"__all__": [str(exc)]}))
+            raise
+        return self.instance

callish/manager.py

@@ -0,0 +1,74 @@
+"""Manager for API-backed models — Django ``.objects`` analogue."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .queryset import APIQuerySet
+
+if TYPE_CHECKING:
+    from .models import APIModel
+
+
+class APIManager:
+    """Minimal manager: spawns querysets and proxies the common terminal methods."""
+
+    # Django generic views look at this attribute (``model._default_manager``).
+    use_in_migrations = False
+
+    def __init__(self) -> None:
+        self.model: type[APIModel] | None = None
+        self.name: str = "objects"
+
+    def contribute_to_class(self, model: type[APIModel], name: str) -> None:
+        self.model = model
+        self.name = name
+        setattr(model, name, self)
+        # Django generic views look for ``_default_manager`` and ``_meta.base_manager``.
+        if getattr(model, "_default_manager", None) is None:
+            model._default_manager = self
+
+    # ----- queryset spawners ----------------------------------------------
+
+    def get_queryset(self) -> APIQuerySet:
+        if self.model is None:
+            raise RuntimeError("APIManager is not attached to a model.")
+        return APIQuerySet(self.model)
+
+    def all(self) -> APIQuerySet:
+        return self.get_queryset()
+
+    def none(self) -> APIQuerySet:
+        return self.get_queryset().none()
+
+    def filter(self, **kwargs: Any) -> APIQuerySet:
+        return self.get_queryset().filter(**kwargs)
+
+    def exclude(self, **kwargs: Any) -> APIQuerySet:
+        return self.get_queryset().exclude(**kwargs)
+
+    def order_by(self, *fields: str) -> APIQuerySet:
+        return self.get_queryset().order_by(*fields)
+
+    def get(self, **kwargs: Any) -> APIModel:
+        return self.get_queryset().get(**kwargs)
+
+    def first(self) -> APIModel | None:
+        return self.get_queryset().first()
+
+    def last(self) -> APIModel | None:
+        return self.get_queryset().last()
+
+    def exists(self) -> bool:
+        return self.get_queryset().exists()
+
+    def count(self) -> int:
+        return self.get_queryset().count()
+
+    # ----- write helpers ---------------------------------------------------
+
+    def create(self, **kwargs: Any) -> APIModel:
+        assert self.model is not None
+        instance = self.model(**kwargs)
+        instance.save()
+        return instance