django-conjure 0.1.0__tar.gz

django_conjure-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+.eggs/
+build/
+dist/
+.tox/
+.nox/
+.coverage
+.coverage.*
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+*.sqlite3
+db.sqlite3
+
+# Node
+node_modules/
+.pnpm-store/
+*.tsbuildinfo
+.vite/
+.astro/
+
+# Build outputs
+apps/landing/dist/
+apps/docs/site/
+packages/web/dist/
+packages/conjure/conjure/static/conjure/assets/
+
+# Env
+.env
+.env.local
+.env.*.local
+!.env.example
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/*
+!.vscode/extensions.json
+*.swp

django_conjure-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Terrace Lab
+
+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.

django_conjure-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: django-conjure
+Version: 0.1.0
+Summary: Conjure your Django admin — read your models, summon a CRUD API and dashboard.
+Project-URL: Homepage, https://conjure.terracelab.dev
+Project-URL: Documentation, https://docs.conjure.terracelab.dev
+Project-URL: Repository, https://github.com/terracelab/django-conjure
+Project-URL: Changelog, https://github.com/terracelab/django-conjure/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/terracelab/django-conjure/issues
+Author-email: Terrace Lab <hello@terracelab.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: admin,codegen,crud,dashboard,django,introspection,rest
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Framework :: Django :: 5.1
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+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 :: Application Frameworks
+Requires-Python: >=3.10
+Requires-Dist: django>=4.2
+Requires-Dist: djangorestframework>=3.15
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: django>=4.2; extra == 'dev'
+Requires-Dist: djangorestframework-simplejwt>=5.3; extra == 'dev'
+Requires-Dist: djangorestframework>=3.15; extra == 'dev'
+Requires-Dist: pytest-django>=4.8; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: jwt
+Requires-Dist: djangorestframework-simplejwt>=5.3; extra == 'jwt'
+Description-Content-Type: text/markdown
+
+# django-conjure
+
+> Conjure your Django admin — read your models, summon a CRUD API + schema.
+
+The Python package behind [Conjure](https://conjure.terracelab.dev). It introspects your
+models and serves a generic admin **REST API** (`/conjure/`) plus a schema endpoint that a
+frontend — or codegen — can read. A matching React dashboard lives in the repo and is in
+active development; for the `0.1.x` line, point any client at the API below.
+
+## Install
+
+```bash
+pip install django-conjure          # session auth (default)
+pip install "django-conjure[jwt]"   # add JWT auth mode
+```
+
+```python
+# settings.py
+INSTALLED_APPS += ["conjure"]
+
+CONJURE = {
+    "AUTH": "session",                       # or "jwt"
+    "BRAND": {"name": "My Admin", "accent": "#4f46e5"},
+    # "USER_PAYLOAD": "myapp.hooks.payload", # custom user model? return any dict
+}
+```
+
+```python
+# urls.py
+urlpatterns += [path("conjure/", include("conjure.urls"))]
+```
+
+```bash
+python manage.py migrate conjure   # AdminAuditLog table (audit log, optional but recommended)
+```
+
+## Register a model
+
+Drop an `admin_config.py` into any app — it's discovered automatically, like `admin.py`:
+
+```python
+from conjure import register, AdminConfig
+from myapp.models import Product
+
+@register(Product)
+class ProductConfig(AdminConfig):
+    list_display = ["name", "price", "is_active"]
+    search_fields = ["name"]
+    list_filter = ["is_active"]
+    inlines = [(ProductImage, "product")]   # inline child editing
+    is_readonly = False                     # True => log/history models, blocks writes
+```
+
+Anything you leave unset is inferred from the model's fields.
+
+## What you get
+
+- `GET /conjure/schema/` + `…/schema/{app.Model}/` — model introspection (codegen + runtime source)
+- `GET/POST /conjure/r/{app.Model}/` and `…/{pk}/` — generic CRUD
+- `…/autocomplete/`, `…/bulk/` (atomic inline ops), `…/{pk}/related/` (delete impact)
+- Django-permission gating (`view/add/change/delete`, shared with Django admin), `is_staff` required
+- Audit log with before/after diff, staff auth (session or JWT), dashboard widget registry
+
+## Extend without forking
+
+```python
+from conjure import register_widget
+
+@register_widget("signup-trend")
+def signup_trend(request):
+    ...  # return any JSON; served at /conjure/widgets/signup-trend/
+```
+
+Full docs, the settings reference, the REST contract, and the extension SDK live at
+**[docs.conjure.terracelab.dev](https://docs.conjure.terracelab.dev)**.
+
+## Develop
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check . && ruff format --check .
+```
+
+MIT © Terrace Lab

django_conjure-0.1.0/README.md

@@ -0,0 +1,85 @@
+# django-conjure
+
+> Conjure your Django admin — read your models, summon a CRUD API + schema.
+
+The Python package behind [Conjure](https://conjure.terracelab.dev). It introspects your
+models and serves a generic admin **REST API** (`/conjure/`) plus a schema endpoint that a
+frontend — or codegen — can read. A matching React dashboard lives in the repo and is in
+active development; for the `0.1.x` line, point any client at the API below.
+
+## Install
+
+```bash
+pip install django-conjure          # session auth (default)
+pip install "django-conjure[jwt]"   # add JWT auth mode
+```
+
+```python
+# settings.py
+INSTALLED_APPS += ["conjure"]
+
+CONJURE = {
+    "AUTH": "session",                       # or "jwt"
+    "BRAND": {"name": "My Admin", "accent": "#4f46e5"},
+    # "USER_PAYLOAD": "myapp.hooks.payload", # custom user model? return any dict
+}
+```
+
+```python
+# urls.py
+urlpatterns += [path("conjure/", include("conjure.urls"))]
+```
+
+```bash
+python manage.py migrate conjure   # AdminAuditLog table (audit log, optional but recommended)
+```
+
+## Register a model
+
+Drop an `admin_config.py` into any app — it's discovered automatically, like `admin.py`:
+
+```python
+from conjure import register, AdminConfig
+from myapp.models import Product
+
+@register(Product)
+class ProductConfig(AdminConfig):
+    list_display = ["name", "price", "is_active"]
+    search_fields = ["name"]
+    list_filter = ["is_active"]
+    inlines = [(ProductImage, "product")]   # inline child editing
+    is_readonly = False                     # True => log/history models, blocks writes
+```
+
+Anything you leave unset is inferred from the model's fields.
+
+## What you get
+
+- `GET /conjure/schema/` + `…/schema/{app.Model}/` — model introspection (codegen + runtime source)
+- `GET/POST /conjure/r/{app.Model}/` and `…/{pk}/` — generic CRUD
+- `…/autocomplete/`, `…/bulk/` (atomic inline ops), `…/{pk}/related/` (delete impact)
+- Django-permission gating (`view/add/change/delete`, shared with Django admin), `is_staff` required
+- Audit log with before/after diff, staff auth (session or JWT), dashboard widget registry
+
+## Extend without forking
+
+```python
+from conjure import register_widget
+
+@register_widget("signup-trend")
+def signup_trend(request):
+    ...  # return any JSON; served at /conjure/widgets/signup-trend/
+```
+
+Full docs, the settings reference, the REST contract, and the extension SDK live at
+**[docs.conjure.terracelab.dev](https://docs.conjure.terracelab.dev)**.
+
+## Develop
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check . && ruff format --check .
+```
+
+MIT © Terrace Lab

django_conjure-0.1.0/conjure/__init__.py

@@ -0,0 +1,19 @@
+"""Conjure — conjure your Django admin.
+
+Public API:
+    from conjure import register, AdminConfig
+    from conjure import register_widget
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from conjure.registry import AdminConfig, admin_register, register, registry
+from conjure.widgets import register_widget
+
+__all__ = ["AdminConfig", "registry", "register", "admin_register", "register_widget"]
+
+try:
+    # Single source of truth = the installed package metadata (pyproject version).
+    __version__ = version("django-conjure")
+except PackageNotFoundError:  # running from source without an install
+    __version__ = "0.0.0+local"

django_conjure-0.1.0/conjure/admin_config.py

@@ -0,0 +1,12 @@
+"""Conjure registers its own audit-log model (read-only) so the dashboard's audit page works."""
+
+from conjure import AdminConfig, register
+from conjure.models import AdminAuditLog
+
+
+@register(AdminAuditLog)
+class AdminAuditLogConfig(AdminConfig):
+    is_readonly = True
+    list_display = ["id", "created_at", "actor", "action", "model_label", "object_pk", "object_repr"]
+    search_fields = ["model_label", "object_repr", "object_pk"]
+    list_filter = ["action"]

django_conjure-0.1.0/conjure/apps.py

@@ -0,0 +1,18 @@
+from django.apps import AppConfig
+
+
+class ConjureConfig(AppConfig):
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "conjure"
+    verbose_name = "Conjure"
+
+    def ready(self):
+        # Register built-in widgets.
+        from conjure import widgets  # noqa: F401
+        from conjure.conf import conjure_settings
+
+        # Discover each app's admin_config module (like admin.autodiscover()).
+        if conjure_settings.AUTODISCOVER:
+            from conjure.discovery import autodiscover
+
+            autodiscover()

django_conjure-0.1.0/conjure/audit.py

@@ -0,0 +1,55 @@
+"""
+@Domain: conjure / audit log
+@BusinessLogic: Helper to record an audit entry for each write. CRUD must keep working even when
+    the AdminAuditLog table hasn't been migrated yet, so write failures are swallowed and logged.
+@Context: DECOUPLING — uses the standard library ``logging`` (logger name from settings) instead
+    of any project-specific logger. Honors CONJURE["AUDIT"] (off => no-op).
+@Connection: conjure/viewsets.py, conjure/models.py, conjure/conf.py
+"""
+
+import logging
+
+from conjure.conf import conjure_settings
+
+logger = logging.getLogger(conjure_settings.LOGGER_NAME)
+
+
+def get_client_ip(request):
+    forwarded = request.META.get("HTTP_X_FORWARDED_FOR")
+    if forwarded:
+        return forwarded.split(",")[0].strip()
+    return request.META.get("REMOTE_ADDR")
+
+
+def build_diff(before, after):
+    """Compare before/after serializer dicts -> {field: [old, new]}. Skips internal fields."""
+    diff = {}
+    keys = set(before.keys()) | set(after.keys())
+    for key in keys:
+        if key.startswith("_") or key.endswith("_label") or key.endswith("_display"):
+            continue
+        b, a = before.get(key), after.get(key)
+        if b != a:
+            diff[key] = [b, a]
+    return diff
+
+
+def record(request, model_label, object_pk, action, object_repr="", diff=None):
+    """Record one audit entry — failure here never blocks the underlying write."""
+    if not conjure_settings.AUDIT:
+        return
+
+    from conjure.models import AdminAuditLog
+
+    try:
+        AdminAuditLog.objects.create(
+            actor=request.user if request.user.is_authenticated else None,
+            model_label=model_label,
+            object_pk=str(object_pk),
+            object_repr=str(object_repr)[:200],
+            action=action,
+            diff=diff or None,
+            ip=get_client_ip(request),
+        )
+    except Exception:  # table not migrated yet, etc. — auditing must not break CRUD
+        logger.exception("[conjure] failed to write audit log")

django_conjure-0.1.0/conjure/auth.py

@@ -0,0 +1,123 @@
+"""
+@Domain: conjure / auth
+@BusinessLogic: Staff-only login for the admin frontend. Two modes selected at request time by
+    CONJURE["AUTH"]: "session" (reuse Django's session login — works in any project, the default)
+    and "jwt" (SimpleJWT, requires the optional [jwt] extra). Non-staff accounts are always
+    rejected. The login/me response body comes from CONJURE["USER_PAYLOAD"].
+@Context: DECOUPLING — the payload is a configurable callable defaulting to get_username()/
+    get_full_name(), so it never assumes project-specific user fields (e.g. nickname/real_name).
+@Connection: conjure/urls.py, conjure/conf.py, packages/web/src/lib/auth.ts
+"""
+
+from django.contrib.auth import authenticate
+from django.contrib.auth import login as django_login
+from django.contrib.auth import logout as django_logout
+from django.core.exceptions import ImproperlyConfigured
+from django.http import Http404
+from rest_framework import status
+from rest_framework.exceptions import AuthenticationFailed
+from rest_framework.permissions import AllowAny
+from rest_framework.response import Response
+from rest_framework.views import APIView
+
+from conjure.conf import conjure_settings
+from conjure.mixins import ConjureAuthMixin
+from conjure.permissions import IsStaffUser
+
+
+def default_user_payload(user):
+    """Project-agnostic default — only uses the User API guaranteed by contrib.auth."""
+    full_name = (user.get_full_name() or "").strip()
+    return {
+        "id": user.pk,
+        "username": user.get_username(),
+        "name": full_name or user.get_username(),
+        "is_superuser": user.is_superuser,
+    }
+
+
+def user_payload(user):
+    fn = conjure_settings.USER_PAYLOAD
+    return fn(user) if callable(fn) else default_user_payload(user)
+
+
+def _require_staff(user):
+    if not (user and user.is_active and user.is_staff):
+        raise AuthenticationFailed("This account has no admin access.")
+
+
+def _jwt_module():
+    try:
+        import rest_framework_simplejwt.serializers as ser
+    except ImportError as e:  # pragma: no cover - guarded path
+        raise ImproperlyConfigured(
+            "CONJURE['AUTH'] == 'jwt' requires the optional dependency: pip install 'django-conjure[jwt]'"
+        ) from e
+    return ser
+
+
+class LoginView(APIView):
+    """POST /auth/login/ — dispatches on CONJURE['AUTH']."""
+
+    permission_classes = [AllowAny]
+    authentication_classes = []
+    swagger_schema = None
+
+    def post(self, request):
+        if conjure_settings.AUTH == "jwt":
+            serializer_cls = _jwt_module().TokenObtainPairSerializer
+            serializer = serializer_cls(data=request.data, context={"request": request})
+            serializer.is_valid(raise_exception=True)
+            _require_staff(serializer.user)
+            data = dict(serializer.validated_data)
+            data["user"] = user_payload(serializer.user)
+            return Response(data)
+
+        # session mode
+        user = authenticate(
+            request._request,
+            username=request.data.get("username"),
+            password=request.data.get("password"),
+        )
+        if user is None:
+            raise AuthenticationFailed("Invalid credentials.")
+        _require_staff(user)
+        django_login(request._request, user)
+        return Response({"user": user_payload(user)})
+
+
+class RefreshView(APIView):
+    """POST /auth/refresh/ — JWT mode only."""
+
+    permission_classes = [AllowAny]
+    authentication_classes = []
+    swagger_schema = None
+
+    def post(self, request):
+        if conjure_settings.AUTH != "jwt":
+            raise Http404
+        serializer = _jwt_module().TokenRefreshSerializer(data=request.data)
+        serializer.is_valid(raise_exception=True)
+        return Response(serializer.validated_data)
+
+
+class LogoutView(ConjureAuthMixin, APIView):
+    """POST /auth/logout/ — session mode (no-op for JWT, client just drops the token)."""
+
+    permission_classes = [IsStaffUser]
+    swagger_schema = None
+
+    def post(self, request):
+        if conjure_settings.AUTH != "jwt":
+            django_logout(request._request)
+        return Response(status=status.HTTP_204_NO_CONTENT)
+
+
+class MeView(ConjureAuthMixin, APIView):
+    """GET /auth/me/ — the currently authenticated staff user."""
+
+    permission_classes = [IsStaffUser]
+    swagger_schema = None
+
+    def get(self, request):
+        return Response(user_payload(request.user))

django_conjure-0.1.0/conjure/conf.py

@@ -0,0 +1,90 @@
+"""
+@Domain: conjure / settings
+@BusinessLogic: Single accessor for all Conjure settings. Project overrides live under the
+    ``CONJURE`` dict in Django settings and are merged over DEFAULTS. This is the decoupling
+    layer — every project-specific knob (auth mode, brand, user payload, page size, audit) is
+    read through ``conjure_settings`` instead of being hardcoded, so the app attaches to any
+    project without edits.
+@Connection: conjure/auth.py (AUTH, USER_PAYLOAD), conjure/audit.py (AUDIT, LOGGER_NAME),
+    conjure/viewsets.py (PAGE_SIZE), conjure/apps.py (AUTODISCOVER)
+"""
+
+from __future__ import annotations
+
+from django.conf import settings
+from django.core.exceptions import ImproperlyConfigured
+from django.utils.module_loading import import_string
+
+DEFAULTS = {
+    # "session" (reuse Django login, works anywhere) or "jwt" (SimpleJWT — requires the [jwt] extra)
+    "AUTH": "session",
+    # Header / login title + accent color surfaced to the frontend config endpoint.
+    "BRAND": {"name": "Conjure", "accent": "#4f46e5"},
+    # Dotted path or callable -> dict, used as the login/me response. None = built-in default
+    # (id / username / name via get_username()/get_full_name() — works with any AUTH_USER_MODEL).
+    "USER_PAYLOAD": None,
+    # List pagination.
+    "PAGE_SIZE": 50,
+    "MAX_PAGE_SIZE": 200,
+    # Write the audit log (requires `migrate conjure`). When False, writes are skipped entirely.
+    "AUDIT": True,
+    # Auto-import every installed app's ``admin_config`` module on ready() (like admin.autodiscover).
+    "AUTODISCOVER": True,
+    # Logger used for non-fatal internal errors (e.g. audit write failures).
+    "LOGGER_NAME": "conjure",
+}
+
+# Keys whose value is a dotted import path that should be resolved to the referenced object.
+_IMPORT_STRINGS = {"USER_PAYLOAD"}
+
+
+class ConjureSettings:
+    """Lazy, cached accessor over ``settings.CONJURE`` merged onto DEFAULTS."""
+
+    def __init__(self):
+        self._cache: dict = {}
+
+    @property
+    def _user(self) -> dict:
+        user = getattr(settings, "CONJURE", {})
+        if not isinstance(user, dict):
+            raise ImproperlyConfigured("settings.CONJURE must be a dict.")
+        return user
+
+    def __getattr__(self, name: str):
+        if name.startswith("_"):
+            raise AttributeError(name)
+        if name not in DEFAULTS:
+            raise AttributeError(f"Unknown Conjure setting: {name!r}")
+        if name in self._cache:
+            return self._cache[name]
+
+        default = DEFAULTS[name]
+        value = self._user.get(name, default)
+        # Shallow-merge dict defaults (e.g. BRAND) so a partial override keeps the rest.
+        if isinstance(default, dict) and isinstance(value, dict):
+            value = {**default, **value}
+        if name in _IMPORT_STRINGS and isinstance(value, str):
+            value = import_string(value)
+
+        self._cache[name] = value
+        return value
+
+    def reload(self):
+        """Drop the cache — used by tests that override settings."""
+        self._cache.clear()
+
+
+conjure_settings = ConjureSettings()
+
+
+# Keep settings live under override_settings(CONJURE=...) (same pattern DRF uses for its own settings).
+from django.test.signals import setting_changed  # noqa: E402
+
+
+def _reload_conjure_settings(*, setting, **kwargs):
+    if setting == "CONJURE":
+        conjure_settings.reload()
+
+
+setting_changed.connect(_reload_conjure_settings)

django_conjure-0.1.0/conjure/discovery.py

@@ -0,0 +1,14 @@
+"""
+@Domain: conjure / discovery
+@BusinessLogic: Auto-import each installed app's ``admin_config`` module on startup, exactly like
+    Django's ``admin.autodiscover()`` does for ``admin``. This is what lets a project register
+    models by dropping an ``admin_config.py`` into any app — no central import list.
+@Context: DECOUPLING — replaces the old hardcoded ``registrations.py`` single-file import.
+@Connection: conjure/apps.py
+"""
+
+from django.utils.module_loading import autodiscover_modules
+
+
+def autodiscover():
+    autodiscover_modules("admin_config")

django_conjure-0.1.0/conjure/management/commands/conjure_dump_schema.py

@@ -0,0 +1,44 @@
+"""
+@Domain: conjure / codegen
+@BusinessLogic: Dump the registered models' admin schema to JSON — the snapshot the frontend
+    codegen reads. Replaces the ad-hoc shell one-liner. Permissions are forced on so the dump
+    is complete regardless of who runs it.
+@Connection: conjure/schema.py (model_schema), packages/web/codegen/schema-snapshot.json
+"""
+
+import json
+
+from django.core.management.base import BaseCommand
+
+from conjure.registry import registry
+from conjure.schema import model_schema
+
+
+class _AllPerms:
+    """Stand-in user so the schema dump includes every model's full permission flags."""
+
+    is_superuser = True
+
+    def has_perm(self, perm, obj=None):
+        return True
+
+
+class Command(BaseCommand):
+    help = "Dump the registered models' admin schema to JSON (the codegen snapshot)."
+
+    def add_arguments(self, parser):
+        parser.add_argument("-o", "--output", default=None, help="Write to this path instead of stdout.")
+        parser.add_argument("--indent", type=int, default=2, help="JSON indent (default: 2).")
+
+    def handle(self, *args, **options):
+        user = _AllPerms()
+        data = {key: model_schema(key, config, user) for key, config in registry.items()}
+        text = json.dumps(data, ensure_ascii=False, indent=options["indent"])
+
+        output = options["output"]
+        if output:
+            with open(output, "w", encoding="utf-8") as fh:
+                fh.write(text)
+            self.stderr.write(self.style.SUCCESS(f"Wrote {len(data)} models to {output}"))
+        else:
+            self.stdout.write(text)