djcrud 0.2.0__py3-none-any.whl

djcrud/__init__.py

@@ -0,0 +1,145 @@
+"""djcrud public API.
+
+:data:`site` is the root :class:`Site` router. Append routers to
+``site.routes`` in each app's ``djcrud.py`` module; :meth:`Site.build` imports
+those modules via autodiscovery (like Django admin's ``admin.py``).
+"""
+
+from django.db import models as db_models
+from django.utils.module_loading import autodiscover_modules
+
+from .backends import ViewPermissionBackend, resolve_permission_backend
+from .router import Router
+from .view import View
+from .model import ModelMixin
+from .views import generic
+
+
+class ModelRouter(ModelMixin, Router):
+    """CRUD router for a single Django model.
+
+    Attributes:
+        routes: Default list, detail, create, update, delete, and bulk-delete
+            views. Extend with ``ModelRouter.routes + [MyView]`` or
+            replace entries by codename (see :class:`~djcrud.registry.Registry`).
+        model: Django model class managed by this router.
+        icon (str): Bootstrap Icons name for the navigation list view.
+        color (str): Bulma color for the navigation list icon.
+        permission_backend: Optional :class:`~djcrud.backends.ViewPermissionBackend`
+            subclass, dotted path, or instance. Also settable on
+            :class:`django.apps.AppConfig`.
+    """
+
+    permission_backend = None
+
+    routes = [
+        generic.ListView,
+        generic.DetailView,
+        generic.UpdateView,
+        generic.DeleteView,
+        generic.DeleteObjectsView,
+        generic.CreateView,
+    ]
+
+    @property
+    def codename(self):
+        """URL segment from :attr:`model` name (lowercase)."""
+        return self.model.__name__.lower()
+
+    def has_permission(self, view):
+        """Check Django permissions for *view* via the permission backend."""
+        return view.has_permission_backend()
+
+    def get_queryset(self, view):
+        """Return rows visible to *view* via the permission backend."""
+        return view.get_queryset_backend()
+
+    json_fields = None
+
+    def get_json_fields(self):
+        """Field names exposed in JSON responses."""
+        if self.json_fields is not None:
+            return list(self.json_fields)
+        return [f.name for f in self.model._meta.fields]
+
+    def get_FIELD_json(self, obj, field):
+        value = getattr(obj, field)
+        if callable(value):
+            value = value()
+        if value is not None and not isinstance(value, (str, int, float, bool)):
+            value = str(value)
+        return value
+
+    def serialize(self, obj, fields=None):
+        """Map a model instance to a JSON-serializable dict."""
+        fields = fields or self.get_json_fields()
+        return {
+            field: getattr(
+                self,
+                f"get_{field}_json",
+                self.get_FIELD_json,
+            )(obj, field)
+            for field in fields
+        }
+
+    def get_swagger_model_name(self, request):
+        return self.model.__name__
+
+    def get_swagger_model_definition(self, request):
+        result = {"properties": {}, "type": "object"}
+        int_fields = (
+            db_models.IntegerField,
+            db_models.BigIntegerField,
+            db_models.AutoField,
+            db_models.PositiveIntegerField,
+            db_models.PositiveSmallIntegerField,
+            db_models.SmallIntegerField,
+        )
+        for field in self.model._meta.fields:
+            custom = getattr(self, f"swagger_field_{field.name}_definition", None)
+            if custom:
+                result["properties"][field.name] = custom
+                continue
+            field_def = {}
+            if isinstance(field, int_fields):
+                field_def["type"] = "integer"
+            elif isinstance(field, db_models.BooleanField):
+                field_def["type"] = "boolean"
+            elif isinstance(field, db_models.JSONField):
+                field_def["type"] = "object"
+            else:
+                field_def["type"] = "string"
+            result["properties"][field.name] = field_def
+        return result
+
+
+class Home(generic.TemplateView):
+    """Site root page at ``/``."""
+
+    urlpath = ""
+
+    def has_permission(self):
+        """Allow anonymous access to the home page."""
+        return True
+
+
+class Site(Router):
+    """Root site router; autodiscovers ``djcrud.py`` in installed apps."""
+
+    urlpath = ""
+    routes = [
+        Home,
+    ]
+
+    def autodiscover(self):
+        """Import ``djcrud`` modules from every installed app."""
+        autodiscover_modules("djcrud")
+        return self
+
+    def build(self):
+        """Autodiscover app routes, then build the route registry."""
+        self.autodiscover()
+        return super().build()
+
+
+site = Site()

djcrud/admin.py

@@ -0,0 +1,3 @@
+from django.contrib import admin
+
+# Register your models here.

djcrud/apps.py

@@ -0,0 +1,5 @@
+from django.apps import AppConfig
+
+
+class DjcrudConfig(AppConfig):
+    name = "djcrud"

djcrud/backends.py

@@ -0,0 +1,159 @@
+"""View-aware permission backends for djcrud.
+
+Default :attr:`~djcrud.view.ViewMixin.permission_shortcode` values on generic
+views (Django permission codenames are ``{shortcode}_{model}``):
+
+- ``view`` — :class:`~djcrud.views.list.ListView`,
+  :class:`~djcrud.views.detail.DetailView`,
+  :class:`~djcrud_dal.views.AutocompleteView`
+- ``add`` — :class:`~djcrud.views.create.CreateView`
+- ``change`` — :class:`~djcrud.views.update.UpdateView`
+- ``delete`` — :class:`~djcrud.views.delete.DeleteView`,
+  :class:`~djcrud.views.delete.DeleteObjectsView`
+"""
+
+from django.apps import apps
+from django.contrib.auth import get_backends
+from django.utils.module_loading import import_string
+
+
+class ViewPermissionBackend:
+    """Base permission backend with convention-based handler dispatch.
+
+    Implement handlers named ``has_perm_{model}_{shortcode}``,
+    ``has_perm_{model}``, ``get_queryset_{model}_{shortcode}``, or
+    ``get_queryset_{model}`` where *shortcode* is the view's
+    :attr:`~djcrud.view.ViewMixin.permission_shortcode`.
+    """
+
+    def handler(self, prefix, view):
+        """Return the handler callable for *prefix* and *view*, or None."""
+        if view is None or view.router is None:
+            return None
+        model_name = view.router.model_router.model._meta.model_name
+        shortcode = view.permission_shortcode
+        for name in (
+            f"{prefix}_{model_name}_{shortcode}",
+            f"{prefix}_{model_name}",
+            prefix,
+        ):
+            method = getattr(self, name, None)
+            if method is not None:
+                return method
+        return None
+
+    def has_perm(self, user_obj, perm, obj=None):
+        handler = self.handler("has_perm", obj)
+        if handler is None:
+            return False
+        return handler(user_obj, perm=perm, obj=obj)
+
+    def get_queryset(self, user_obj, perm, obj=None, **kwargs):
+        handler = self.handler("get_queryset", obj)
+        if handler is None:
+            return None
+        return handler(user_obj, perm=perm, obj=obj, **kwargs)
+
+
+def load_permission_backend(value):
+    """Return a backend instance from a class, path string, or instance."""
+    if value is None:
+        return None
+    if isinstance(value, ViewPermissionBackend):
+        return value
+    if isinstance(value, str):
+        value = import_string(value)
+    if isinstance(value, type) and issubclass(value, ViewPermissionBackend):
+        return value()
+    raise TypeError(
+        "permission_backend must be a ViewPermissionBackend subclass, "
+        "dotted path, or instance — got %r" % (value,)
+    )
+
+
+def permission_backend_from_router(router):
+    current = router
+    while current is not None:
+        value = type(current).__dict__.get("permission_backend")
+        if value is not None:
+            return load_permission_backend(value)
+        current = getattr(current, "router", None)
+    return None
+
+
+def permission_backend_from_app(model):
+    app_config = apps.get_app_config(model._meta.app_label)
+    value = getattr(app_config, "permission_backend", None)
+    if value is None:
+        return None
+    return load_permission_backend(value)
+
+
+def resolve_permission_backend(*, view=None, router=None, model=None):
+    """Return the permission backend for *view*, *router*, and/or *model*."""
+    if view is not None:
+        if "permission_backend" in view.__dict__:
+            return view.__dict__["permission_backend"]
+        if router is None and view.router is not None:
+            router = view.router.model_router
+        if model is None and router is not None:
+            model = router.model
+
+    if router is not None:
+        backend = permission_backend_from_router(router)
+        if backend is not None:
+            return backend
+
+    if model is not None:
+        backend = permission_backend_from_app(model)
+        if backend is not None:
+            return backend
+
+    from . import site
+
+    site_backend = type(site).__dict__.get("permission_backend")
+    if site_backend is not None:
+        return load_permission_backend(site_backend)
+    return None
+
+
+def default_has_perm(user_obj, perm):
+    """Check global DB permissions (superuser or ModelBackend)."""
+    if user_obj.is_active and user_obj.is_superuser:
+        return True
+    from django.contrib.auth.backends import ModelBackend
+
+    return ModelBackend().has_perm(user_obj, perm, None)
+
+
+def detail_view_for(router, request):
+    """Return a detail-route view instance for *router*, or None."""
+    detail_route = router.model_router.find_route("detail")
+    if detail_route is None:
+        return None
+    view = type(detail_route)(request=request)
+    view.router = router
+    return view
+
+
+def queryset_from_backends(user, view):
+    """Return a queryset from permission backends for *view*, or None.
+
+    Checks the resolved :class:`ViewPermissionBackend` first, then each entry
+    in ``AUTHENTICATION_BACKENDS`` that implements ``get_queryset``.
+    """
+    model = view.router.model_router.model
+    perm = view.permission_fullcode
+    backend = resolve_permission_backend(view=view)
+    if backend is not None:
+        qs = backend.get_queryset(user, perm, view, model=model)
+        if qs is not None:
+            return qs
+    for auth_backend in get_backends():
+        get_qs = getattr(auth_backend, "get_queryset", None)
+        if get_qs is None:
+            continue
+        qs = get_qs(user, perm, view)
+        if qs is not None:
+            return qs
+    return None

djcrud/clonable.py

@@ -0,0 +1,15 @@
+class Clonable:
+    """Mixin for declaring specialized subclasses at runtime.
+
+    Controllers and views use :meth:`clone` to override attributes without
+    defining a new module-level class.
+    """
+
+    @classmethod
+    def clone(cls, *mixins, **attributes):
+        """Return a subclass with the given attributes.
+
+        If a model is found, it will prefix the class name with the model.
+        """
+        name = cls.__name__
+        return type(name, (cls,) + mixins, attributes)

djcrud/errors.py

@@ -0,0 +1,81 @@
+from django.template.response import TemplateResponse
+from django.utils.translation import gettext_lazy as _
+
+DEFAULT_ERROR_PAGES = {
+    400: (
+        _("Bad request"),
+        _("The request could not be understood by the server."),
+    ),
+    403: (
+        _("Forbidden"),
+        _("You don't have permission to view or edit anything."),
+    ),
+    404: (
+        _("Page not found"),
+        _("We're sorry, but the requested page could not be found."),
+    ),
+    500: (
+        _("Server error"),
+        _(
+            "There's been an error. It's been reported to the site "
+            "administrators via email and should be fixed shortly. "
+            "Thanks for your patience."
+        ),
+    ),
+}
+
+
+def layout_view_for_request(request):
+    import djcrud
+    from .views.template import TemplateView
+
+    if not hasattr(djcrud.site, "registry"):
+        djcrud.site.build()
+
+    class LayoutView(TemplateView):
+        def has_permission(self):
+            return True
+
+    view_class = LayoutView.clone(router=djcrud.site)
+    view = view_class()
+    view.request = request
+    view.kwargs = {}
+    view.args = ()
+    return view
+
+
+def error_response(request, status, view=None, title=None, message=None):
+    view = view or layout_view_for_request(request)
+    default_title, default_message = DEFAULT_ERROR_PAGES[status]
+    context = {
+        "view": view,
+        "error_status": status,
+        "error_title": title or default_title,
+        "error_message": message or default_message,
+    }
+    return TemplateResponse(
+        request,
+        [
+            f"djcrud/{status}.html",
+            "djcrud/error.html",
+            f"{status}.html",
+        ],
+        context,
+        status=status,
+    )
+
+
+def bad_request_response(request, view=None, title=None, message=None):
+    return error_response(request, 400, view=view, title=title, message=message)
+
+
+def forbidden_response(request, view=None, title=None, message=None):
+    return error_response(request, 403, view=view, title=title, message=message)
+
+
+def not_found_response(request, view=None, title=None, message=None):
+    return error_response(request, 404, view=view, title=title, message=message)
+
+
+def server_error_response(request, view=None, title=None, message=None):
+    return error_response(request, 500, view=view, title=title, message=message)

djcrud/handlers.py

@@ -0,0 +1,23 @@
+from .errors import (
+    bad_request_response,
+    forbidden_response,
+    layout_view_for_request,
+    not_found_response,
+    server_error_response,
+)
+
+
+def handler400(request, exception=None):
+    return bad_request_response(request, view=layout_view_for_request(request))
+
+
+def handler403(request, exception=None):
+    return forbidden_response(request, view=layout_view_for_request(request))
+
+
+def handler404(request, exception=None):
+    return not_found_response(request, view=layout_view_for_request(request))
+
+
+def handler500(request):
+    return server_error_response(request, view=layout_view_for_request(request))

djcrud/introspection.py

@@ -0,0 +1,95 @@
+import re
+
+import djcrud
+
+from .router import Router
+
+
+def compute_fullurlpath(route):
+    """Return the URL path for *route* by walking router ancestors."""
+    try:
+        return route.url
+    except Exception:
+        parts = []
+        current = route
+        while current is not None:
+            segment = getattr(current, "urlpath", "")
+            if segment:
+                parts.insert(0, segment.strip("/"))
+            current = getattr(current, "router", None)
+        if not parts:
+            return "/"
+        return "/" + "/".join(parts) + "/"
+
+
+def swagger_path(fullurlpath):
+    """Convert Django URL path converters to Swagger brace syntax."""
+    return "/" + re.sub(r"<(?:[^:>]+:)?([^>]+)>", r"{\1}", fullurlpath.strip("/"))
+
+
+def walk_leaf_views(router):
+    """Yield built view route instances under *router*."""
+    routes = getattr(router, "routes", None)
+    if routes is None:
+        return
+    for route in routes:
+        if isinstance(route, Router):
+            yield from walk_leaf_views(route)
+        else:
+            yield route
+
+
+def walk_model_routers(router):
+    """Yield :class:`~djcrud.ModelRouter` instances in the tree."""
+    if getattr(type(router), "model", None) is not None:
+        yield router
+    routes = getattr(router, "routes", None)
+    if routes is None:
+        return
+    for route in routes:
+        if isinstance(route, Router):
+            yield from walk_model_routers(route)
+
+
+def get_built_site(site):
+    """Return *site* after :meth:`~djcrud.Site.build` if needed."""
+    if not hasattr(site, "registry"):
+        site.build()
+    return site
+
+
+def has_json_handler(view_class):
+    """Return whether *view_class* defines any ``json_*`` handler."""
+    return any(
+        hasattr(view_class, f"json_{method}")
+        for method in ("get", "post", "put", "patch", "delete")
+    )
+
+
+def instantiate_view(route, request):
+    """Return a view instance bound to *request* from a built route."""
+    view = type(route)(request=request)
+    view.args = ()
+    view.kwargs = {}
+    return view
+
+
+def iter_schema_json_views(request, site=None):
+    """Yield every JSON-capable view for Swagger schema (no permission filter)."""
+    site = get_built_site(site or djcrud.site)
+    for route in walk_leaf_views(site):
+        if has_json_handler(type(route)):
+            yield instantiate_view(route, request)
+
+
+def iter_schema_model_routers(request, site=None):
+    """Yield model controllers referenced by JSON-capable views in the schema."""
+    seen = set()
+    for view in iter_schema_json_views(request, site):
+        mc = view.router.model_router
+        if getattr(type(mc), "model", None) is None:
+            continue
+        key = id(mc)
+        if key not in seen:
+            seen.add(key)
+            yield mc

djcrud/locale/en/LC_MESSAGES/django.po

@@ -0,0 +1,150 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
+# This file is distributed under the same license as the PACKAGE package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
+#
+#, fuzzy
+msgid ""
+msgstr ""
+"Project-Id-Version: PACKAGE VERSION\n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2026-06-28 12:49+0000\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language-Team: LANGUAGE <LL@li.org>\n"
+"Language: \n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Plural-Forms: nplurals=2; plural=(n != 1);\n"
+
+#: src/djcrud/errors.py:7
+msgid "Bad request"
+msgstr ""
+
+#: src/djcrud/errors.py:8
+msgid "The request could not be understood by the server."
+msgstr ""
+
+#: src/djcrud/errors.py:11
+msgid "Forbidden"
+msgstr ""
+
+#: src/djcrud/errors.py:12
+msgid "You don't have permission to view or edit anything."
+msgstr ""
+
+#: src/djcrud/errors.py:15
+msgid "Page not found"
+msgstr ""
+
+#: src/djcrud/errors.py:16
+msgid "We're sorry, but the requested page could not be found."
+msgstr ""
+
+#: src/djcrud/errors.py:19
+msgid "Server error"
+msgstr ""
+
+#: src/djcrud/errors.py:21
+msgid ""
+"There's been an error. It's been reported to the site administrators via "
+"email and should be fixed shortly. Thanks for your patience."
+msgstr ""
+
+#: src/djcrud/views/create.py:19
+#, python-format
+msgid "Add %(name)s"
+msgstr ""
+
+#: src/djcrud/views/delete.py:19
+#, python-format
+msgid ""
+"Are you sure you want to delete the %(object_name)s \"%(escaped_object)s\"? "
+"All of the following related items will be deleted:"
+msgstr ""
+
+#: src/djcrud/views/delete.py:24
+#, python-format
+msgid ""
+"Are you sure you want to delete the selected %(objects_name)s? All of the "
+"following objects and their related items will be deleted:"
+msgstr ""
+
+#: src/djcrud/views/delete.py:81 src/djcrud/views/delete.py:158
+#: src/djcrud/views/delete.py:191
+msgid "Delete"
+msgstr ""
+
+#: src/djcrud/views/delete.py:130
+#, python-format
+msgid ""
+"Deleting the selected %(objects_name)s would require deleting the following "
+"protected related objects:"
+msgstr ""
+
+#: src/djcrud/views/delete.py:137
+#, python-format
+msgid ""
+"Deleting the %(object_name)s \"%(escaped_object)s\" would require deleting "
+"the following protected related objects:"
+msgstr ""
+
+#: src/djcrud/views/delete.py:170
+#, python-format
+msgid "The %(name)s \"%(obj)s\" was deleted successfully."
+msgstr ""
+
+#: src/djcrud/views/delete.py:199
+#, python-format
+msgid "Successfully deleted %(count)d %(items)s."
+msgstr ""
+
+#: src/djcrud/views/form.py:49
+msgid "Please correct the error below."
+msgid_plural "Please correct the errors below."
+msgstr[0] ""
+msgstr[1] ""
+
+#: src/djcrud/views/list.py:32
+#, python-format
+msgid "No %(verbose_name)s found matching the query"
+msgstr ""
+
+#: src/djcrud/views/list.py:39 src/djcrud/views/list.py:47
+#, python-format
+msgid "%(total_count)s selected"
+msgid_plural "All %(total_count)s selected"
+msgstr[0] ""
+msgstr[1] ""
+
+#: src/djcrud/views/filter.py:33
+msgid "Apply"
+msgstr ""
+
+#: src/djcrud/views/modelform.py:14
+#, python-brace-format
+msgid "The {name} \"{obj}\" was added successfully."
+msgstr ""
+
+#: src/djcrud/views/objectform.py:13 src/djcrud/views/objectform.py:24
+#, python-brace-format
+msgid "The {name} \"{obj}\" was changed successfully."
+msgstr ""
+
+#: src/djcrud/views/pagination.py:94
+msgid "Page is not “last”, nor can it be converted to an int."
+msgstr ""
+
+#: src/djcrud/views/search.py:38
+msgid "Search"
+msgstr ""
+
+#: src/djcrud/views/tables2.py:18
+msgid "Actions"
+msgstr ""
+
+#: src/djcrud/views/update.py:17
+#, python-format
+msgid "Change %(name)s"
+msgstr ""