callish 0.1.0__tar.gz

callish-0.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.3
+Name: callish
+Version: 0.1.0
+Summary: Django QuerySet façade for user-written API adapters.
+License: BSD-3-Clause
+Keywords: django,api,queryset,modelform,adapter
+Author: callish contributors
+Requires-Python: >=3.10
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: django (>=5.0,<7.0)
+Project-URL: Homepage, https://github.com/Technology-Company/callish
+Project-URL: Issues, https://github.com/Technology-Company/callish/issues
+Description-Content-Type: text/markdown
+
+# callish
+
+**Django QuerySet façade for user-written API adapters.**
+
+`callish` lets a Django app expose data living behind an arbitrary API as if
+it were a Django model — so `ModelForm`, generic class-based views, templates,
+and admin register/instantiation keep working — **without** trying to
+standardise the HTTP shape. You write the adapter (`list / retrieve / create /
+update / delete`); `callish` wires it into Django.
+
+## Why
+
+Existing libraries either lock you into a specific HTTP shape
+(`wagtail/queryish` — REST-only, read-only) or rebuild Django machinery
+from scratch. APIs vary too much for one base class to fit all of them.
+callish takes the opposite stance: you write the five-method adapter, and
+callish handles the Django integration around it.
+
+The conformance suite is the spec — when the test battery is green, Django
+integration works.
+
+## Install
+
+```bash
+pip install callish      # core
+# or, with Poetry:
+poetry add callish
+```
+
+**Requires** Python ≥3.10, Django ≥5.0 (5.x or 6.x). No HTTP client
+dependency — that's the adapter's job.
+
+## Quick start
+
+```python
+from callish import APIModel, APIModelForm
+from callish.fields import CharField, IntegerField, BooleanField
+
+
+class Invoice(APIModel):
+    id = IntegerField(primary_key=True)
+    number = CharField(max_length=64)
+    amount_cents = IntegerField()
+    paid = BooleanField(default=False)
+
+    class Meta:
+        adapter = "myproject.adapters:InvoiceAdapter"
+        app_label = "myproject"
+
+
+# Use it like a Django model:
+qs = Invoice.objects.filter(paid=False).order_by("-amount_cents")[:25]
+for invoice in qs:                                # → adapter.list(...)
+    print(invoice.number, invoice.amount_cents)
+
+invoice = Invoice.objects.get(pk=42)              # → adapter.retrieve(42)
+invoice.paid = True
+invoice.save()                                    # → adapter.update(42, {...})
+
+new = Invoice(number="INV-100", amount_cents=10_000, paid=False)
+new.save()                                        # → adapter.create({...})
+
+invoice.delete()                                  # → adapter.delete(42)
+```
+
+## Writing an adapter
+
+Any object with these methods works:
+
+```python
+class InvoiceAdapter:
+    def list(self, *, filters, ordering, offset, limit): ...     # → Sequence[dict]
+    def retrieve(self, pk): ...                                  # → dict
+    def create(self, data): ...                                  # → dict (with pk)
+    def update(self, pk, data): ...                              # → dict
+    def delete(self, pk): ...
+    def count(self, *, filters): ...                             # optional
+```
+
+Raise `callish.exceptions.NotFound / Unauthorized / RateLimited /
+Upstream5xx / AdapterValidationError` for errors. `NotFound` is mapped to
+the model's `DoesNotExist`; the rest surface as-is.
+
+A complete reference implementation lives in
+[`src/callish/testing/reference_adapter.py`](src/callish/testing/reference_adapter.py)
+(`InMemoryAdapter` — dict-backed, used by callish's own tests).
+
+## Django integration
+
+Everything you'd expect from a Django model works:
+
+- **ModelForm** — subclass `APIModelForm`; `form.save()` dispatches to
+  `adapter.create` / `adapter.update`.
+- **Generic class-based views** — `ListView`, `DetailView`, `CreateView`,
+  `UpdateView`, `DeleteView` all work unchanged.
+- **Function-based views** — `Invoice.objects.filter(...)` inside any
+  `def view(request)` function.
+- **Templates** — `{% for invoice in invoices %}{{ invoice.number }}`,
+  `{{ form.as_p }}` etc. all work.
+- **Admin** — `admin.site.register([Invoice], InvoiceAdmin)` (note the list
+  wrap) registers fine and `ModelAdmin` instances construct. The
+  **changelist** is out of scope (admin assumes a real DB-backed Model).
+
+## The conformance suite
+
+`callish` ships a milestone-organised pytest suite that exercises the adapter
+contract. Downstream adapter authors add one fixture and run:
+
+```python
+# your_project/conftest.py
+import pytest
+from your_project.adapters import StripeInvoiceAdapter
+
+@pytest.fixture
+def conform_adapter():
+    return StripeInvoiceAdapter(api_key="sk_test_...")
+```
+
+```bash
+pytest --pyargs callish.testing.suite
+```
+
+The pytest plugin auto-loads via the `pytest11` entry point. To opt out:
+`pytest -p no:callish`.
+
+Milestones:
+- **M1** — list / retrieve / count / filter / order / slice
+- **M2** — create / update / delete
+- **M3** — error and timeout propagation
+
+Use `--callish-skip-m3` to skip error-path tests during incremental adoption.
+
+## Non-goals (v1)
+
+- Cross-source joins (API model ↔ ORM model)
+- Relations between API models (FK, M2M, prefetch)
+- Async adapters
+- ModelAdmin changelist
+- Code generation from OpenAPI / GraphQL schemas
+- Wagtail Snippet / Chooser integration
+
+callish coexists with Wagtail 6.x and 7.x without monkey-patching Django —
+`callish.apps.CallishConfig` is intentionally inert.
+
+## Development
+
+```bash
+poetry install                  # core + dev deps
+poetry run pytest               # library suite (94 tests)
+poetry run pytest --pyargs callish.testing.suite  # shipping conformance suite
+poetry run ruff check src tests
+poetry run mypy src/callish
+```
+
+The full spec is in [`callish-spec.md`](callish-spec.md). Architecture and
+internals are documented in [`CLAUDE.md`](CLAUDE.md).
+
+## License
+
+BSD-3-Clause.

callish-0.1.0/README.md

@@ -0,0 +1,160 @@
+# callish
+
+**Django QuerySet façade for user-written API adapters.**
+
+`callish` lets a Django app expose data living behind an arbitrary API as if
+it were a Django model — so `ModelForm`, generic class-based views, templates,
+and admin register/instantiation keep working — **without** trying to
+standardise the HTTP shape. You write the adapter (`list / retrieve / create /
+update / delete`); `callish` wires it into Django.
+
+## Why
+
+Existing libraries either lock you into a specific HTTP shape
+(`wagtail/queryish` — REST-only, read-only) or rebuild Django machinery
+from scratch. APIs vary too much for one base class to fit all of them.
+callish takes the opposite stance: you write the five-method adapter, and
+callish handles the Django integration around it.
+
+The conformance suite is the spec — when the test battery is green, Django
+integration works.
+
+## Install
+
+```bash
+pip install callish      # core
+# or, with Poetry:
+poetry add callish
+```
+
+**Requires** Python ≥3.10, Django ≥5.0 (5.x or 6.x). No HTTP client
+dependency — that's the adapter's job.
+
+## Quick start
+
+```python
+from callish import APIModel, APIModelForm
+from callish.fields import CharField, IntegerField, BooleanField
+
+
+class Invoice(APIModel):
+    id = IntegerField(primary_key=True)
+    number = CharField(max_length=64)
+    amount_cents = IntegerField()
+    paid = BooleanField(default=False)
+
+    class Meta:
+        adapter = "myproject.adapters:InvoiceAdapter"
+        app_label = "myproject"
+
+
+# Use it like a Django model:
+qs = Invoice.objects.filter(paid=False).order_by("-amount_cents")[:25]
+for invoice in qs:                                # → adapter.list(...)
+    print(invoice.number, invoice.amount_cents)
+
+invoice = Invoice.objects.get(pk=42)              # → adapter.retrieve(42)
+invoice.paid = True
+invoice.save()                                    # → adapter.update(42, {...})
+
+new = Invoice(number="INV-100", amount_cents=10_000, paid=False)
+new.save()                                        # → adapter.create({...})
+
+invoice.delete()                                  # → adapter.delete(42)
+```
+
+## Writing an adapter
+
+Any object with these methods works:
+
+```python
+class InvoiceAdapter:
+    def list(self, *, filters, ordering, offset, limit): ...     # → Sequence[dict]
+    def retrieve(self, pk): ...                                  # → dict
+    def create(self, data): ...                                  # → dict (with pk)
+    def update(self, pk, data): ...                              # → dict
+    def delete(self, pk): ...
+    def count(self, *, filters): ...                             # optional
+```
+
+Raise `callish.exceptions.NotFound / Unauthorized / RateLimited /
+Upstream5xx / AdapterValidationError` for errors. `NotFound` is mapped to
+the model's `DoesNotExist`; the rest surface as-is.
+
+A complete reference implementation lives in
+[`src/callish/testing/reference_adapter.py`](src/callish/testing/reference_adapter.py)
+(`InMemoryAdapter` — dict-backed, used by callish's own tests).
+
+## Django integration
+
+Everything you'd expect from a Django model works:
+
+- **ModelForm** — subclass `APIModelForm`; `form.save()` dispatches to
+  `adapter.create` / `adapter.update`.
+- **Generic class-based views** — `ListView`, `DetailView`, `CreateView`,
+  `UpdateView`, `DeleteView` all work unchanged.
+- **Function-based views** — `Invoice.objects.filter(...)` inside any
+  `def view(request)` function.
+- **Templates** — `{% for invoice in invoices %}{{ invoice.number }}`,
+  `{{ form.as_p }}` etc. all work.
+- **Admin** — `admin.site.register([Invoice], InvoiceAdmin)` (note the list
+  wrap) registers fine and `ModelAdmin` instances construct. The
+  **changelist** is out of scope (admin assumes a real DB-backed Model).
+
+## The conformance suite
+
+`callish` ships a milestone-organised pytest suite that exercises the adapter
+contract. Downstream adapter authors add one fixture and run:
+
+```python
+# your_project/conftest.py
+import pytest
+from your_project.adapters import StripeInvoiceAdapter
+
+@pytest.fixture
+def conform_adapter():
+    return StripeInvoiceAdapter(api_key="sk_test_...")
+```
+
+```bash
+pytest --pyargs callish.testing.suite
+```
+
+The pytest plugin auto-loads via the `pytest11` entry point. To opt out:
+`pytest -p no:callish`.
+
+Milestones:
+- **M1** — list / retrieve / count / filter / order / slice
+- **M2** — create / update / delete
+- **M3** — error and timeout propagation
+
+Use `--callish-skip-m3` to skip error-path tests during incremental adoption.
+
+## Non-goals (v1)
+
+- Cross-source joins (API model ↔ ORM model)
+- Relations between API models (FK, M2M, prefetch)
+- Async adapters
+- ModelAdmin changelist
+- Code generation from OpenAPI / GraphQL schemas
+- Wagtail Snippet / Chooser integration
+
+callish coexists with Wagtail 6.x and 7.x without monkey-patching Django —
+`callish.apps.CallishConfig` is intentionally inert.
+
+## Development
+
+```bash
+poetry install                  # core + dev deps
+poetry run pytest               # library suite (94 tests)
+poetry run pytest --pyargs callish.testing.suite  # shipping conformance suite
+poetry run ruff check src tests
+poetry run mypy src/callish
+```
+
+The full spec is in [`callish-spec.md`](callish-spec.md). Architecture and
+internals are documented in [`CLAUDE.md`](CLAUDE.md).
+
+## License
+
+BSD-3-Clause.

callish-0.1.0/pyproject.toml

@@ -0,0 +1,92 @@
+[project]
+name = "callish"
+version = "0.1.0"
+description = "Django QuerySet façade for user-written API adapters."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "BSD-3-Clause" }
+authors = [{ name = "callish contributors" }]
+keywords = ["django", "api", "queryset", "modelform", "adapter"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: Django",
+    "Framework :: Django :: 5.0",
+    "Framework :: Django :: 5.1",
+    "Framework :: Django :: 5.2",
+    "Framework :: Django :: 6.0",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: BSD License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["django>=5.0,<7.0"]
+
+[project.urls]
+Homepage = "https://github.com/Technology-Company/callish"
+Issues = "https://github.com/Technology-Company/callish/issues"
+
+[project.entry-points.pytest11]
+callish = "callish.testing.plugin"
+
+[build-system]
+requires = ["poetry-core>=1.8.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+package-mode = true
+packages = [{ include = "callish", from = "src" }]
+
+[tool.poetry.dependencies]
+python = ">=3.10,<4.0"
+django = ">=5.0,<7.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = ">=8,<9"
+pytest-django = ">=4.8"
+ruff = ">=0.6"
+mypy = ">=1.10"
+
+# Opt-in: `poetry install --with compat` to run the Wagtail coexistence smoke test.
+[tool.poetry.group.compat]
+optional = true
+
+[tool.poetry.group.compat.dependencies]
+wagtail = ">=6.0,<8.0"
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.settings"
+addopts = "-ra"
+python_files = ["test_*.py"]
+testpaths = ["tests"]
+pythonpath = ["."]
+filterwarnings = [
+    "error",
+    "ignore::DeprecationWarning:django.*",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "W"]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["B011"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = false
+warn_unused_ignores = true
+warn_redundant_casts = true
+warn_unreachable = true
+ignore_missing_imports = true
+files = ["src/callish"]

callish-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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