django-pudding 0.1.0__tar.gz

django_pudding-0.1.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: django-pudding
+Version: 0.1.0
+Summary: Declarative Python framework for Django to build dashboards and internal apps fast.
+Author: Zishan Kadri
+Author-email: Zishan Kadri <zishankadri01@gmail.com>
+License-Expression: MIT
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Dist: django>=5.2
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+

django_pudding-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "django-pudding"
+version = "0.1.0"
+description = "Declarative Python framework for Django to build dashboards and internal apps fast."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = ["django>=5.2"]
+classifiers = [
+    "Environment :: Web Environment",
+    "Framework :: Django",
+    "Framework :: Django :: 5.2",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+]
+license = "MIT"
+
+[[project.authors]]
+name = "Zishan Kadri"
+email = "zishankadri01@gmail.com"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = "src"
+module-name = "pudding"
+
+[tool.mypy]
+plugins = ["mypy_django_plugin.main"]
+
+[tool.django-stubs]
+django_settings_module = "tests.settings"
+
+[dependency-groups]
+dev = [
+    "django-stubs[compatible-mypy]>=6.0.9",
+    "mypy>=2.3.0",
+    "ruff>=0.16.2",
+]

django_pudding-0.1.0/pyproject.toml.orig

@@ -0,0 +1,49 @@
+[project]
+name = "django-pudding"
+version = "0.1.0"
+description = "Declarative Python framework for Django to build dashboards and internal apps fast."
+readme = "README.md"
+authors = [
+    { name = "Zishan Kadri", email = "zishankadri01@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "django>=5.2",
+]
+classifiers = [
+    "Environment :: Web Environment",
+    "Framework :: Django",
+    "Framework :: Django :: 5.2",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+]
+license = "MIT"
+
+[build-system]
+requires = ["uv_build>=0.12.3,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = "src"
+module-name = "pudding"
+
+[dependency-groups]
+dev = [
+    "django-stubs[compatible-mypy]>=6.0.9",
+    "mypy>=2.3.0",
+    "ruff>=0.16.2",
+]
+
+[tool.mypy]
+plugins = ["mypy_django_plugin.main"]
+
+[tool.django-stubs]
+django_settings_module = "tests.settings"

django_pudding-0.1.0/src/pudding/actions/__init__.py

@@ -0,0 +1,9 @@
+from pudding.actions.base import action_handler
+from pudding.actions.contracts import Action
+from pudding.actions.defaults.add import Add
+from pudding.actions.defaults.delete import Delete
+from pudding.actions.defaults.edit import Edit
+from pudding.actions.defaults.view import View
+from pudding.actions.utils import is_htmx
+
+__all__ = ["Action", "Add", "Delete", "Edit", "View", "action_handler", "is_htmx"]

django_pudding-0.1.0/src/pudding/actions/base.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from django.http import HttpRequest, HttpResponse, HttpResponseNotAllowed
+
+from pudding import ui
+from pudding.actions.contracts import ActionHook, ActionStep
+
+
+@dataclass(kw_only=True)
+class InteractiveAction(ABC):
+    """
+    Base class for actions requiring user interaction (like confirmation or forms)
+    before the backend logic runs.
+    """
+
+    slug: str
+    icon: str | None = None
+    permission: Callable[[HttpRequest], bool] | None = None
+
+    def handle(self, request: HttpRequest, ctx: dict[str, Any]) -> HttpResponse:
+        match request.method:
+            case "GET":
+                return self.before(request, ctx)
+            case "POST":
+                return self.execute(request, ctx)
+            case _:
+                return HttpResponseNotAllowed(["GET", "POST"])
+
+    @abstractmethod
+    def before(self, request: HttpRequest, ctx: dict[str, Any]) -> HttpResponse: ...
+
+    @abstractmethod
+    def execute(self, request: HttpRequest, ctx: dict[str, Any]) -> HttpResponse: ...
+
+
+@dataclass(kw_only=True)
+class FunctionalAction:
+    slug: str
+    trigger: ui.Trigger
+    icon: str | None = None
+    permission: Callable[[HttpRequest], bool] | None = None
+
+    execute: ActionStep | None = None
+    before: ActionStep | None = None
+
+    allowed_methods: list[str] = field(init=False, repr=False)
+
+    def __post_init__(self):
+        allowed = []
+        if self.before:
+            allowed.append("GET")
+        if self.execute:
+            allowed.append("POST")
+
+        if not allowed:
+            raise ValueError("At least one of `execute` or `before` must be provided.")
+
+        self.allowed_methods = allowed
+
+    def handle(self, request: HttpRequest, ctx: dict[str, Any]) -> HttpResponse:
+        if request.method == "GET" and self.before:
+            return self.before(self, request, ctx)
+
+        if request.method == "POST" and self.execute:
+            return self.execute(self, request, ctx)
+
+        return HttpResponseNotAllowed(self.allowed_methods)
+
+    def __repr__(self):
+        return (
+            f"FunctionalAction("
+            f"slug={self.slug!r}, "
+            f"execute={getattr(self.execute, '__name__', None)!r}, "
+            f"before={getattr(self.before, '__name__', None)!r})"
+        )
+
+
+def action_handler(
+    *,
+    slug: str,
+    label: str | None = None,
+    icon: str | None = None,
+    before: ActionHook | Callable | None = None,
+    permission: Callable[[HttpRequest], bool] | None = None,
+) -> Callable[[Callable], FunctionalAction]:
+    def decorator(func: Callable) -> FunctionalAction:
+        display_label = label or slug.replace("_", " ").replace("-", " ").capitalize()
+        trigger = ui.action(
+            slug,
+            label=display_label,
+            icon=icon,
+        )
+
+        before_func = None
+
+        if isinstance(before, ActionHook):
+            frame = before.frame
+            before_func = before.before
+            trigger = trigger(**frame.loading_mod)
+        elif callable(before):
+            before_func = before
+
+        action = FunctionalAction(
+            slug=slug,
+            icon=icon,
+            trigger=trigger,
+            execute=func,
+            before=before_func,
+            permission=permission,
+        )
+
+        return action
+
+    return decorator

django_pudding-0.1.0/src/pudding/actions/contracts.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from pudding.ui.frames.base import Frame
+
+from django.http import HttpRequest, HttpResponse
+
+
+@runtime_checkable
+class Action(Protocol):
+    slug: str
+    icon: str | None
+    permission: Callable[[HttpRequest], bool] | None
+
+    def handle(self, request: HttpRequest, ctx: dict[str, Any]) -> HttpResponse: ...
+
+
+type ActionStep = Callable[[Action, HttpRequest, dict[str, Any]], HttpResponse]
+
+
+@dataclass(frozen=True, slots=True)
+class ActionHook:
+    frame: Frame
+    before: ActionStep

django_pudding-0.1.0/src/pudding/actions/defaults/__init__.py

@@ -0,0 +1,3 @@
+from . import add, delete, edit, view
+
+__all__ = ["add", "delete", "edit", "view"]

django_pudding-0.1.0/src/pudding/actions/defaults/add.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from django.contrib import messages
+from django.http import HttpRequest, HttpResponse
+from django.shortcuts import render
+from django.template.loader import render_to_string
+from django.urls import reverse
+from django.utils.html import format_html
+from django.utils.translation import gettext_lazy as _
+
+from pudding import actions, ui
+from pudding.actions.base import InteractiveAction
+from pudding.actions.defaults.utils import (
+    build_sidebar_from_domains,
+    get_form_class,
+)
+
+
+def get_content(self, form, request, ctx):
+    submit_btn = ui.action(
+        self.slug,
+        label=_("Save"),
+        method="post",
+        look=ui.looks.button(variant="solid"),
+    )
+
+    form_id = "modal-form"
+    validity_guard = (
+        f"const f = document.getElementById('{form_id}');"
+        " if (!f.checkValidity()) { event.preventDefault(); f.reportValidity(); }"
+    )
+    submit_btn = submit_btn(
+        attrs={
+            "form": form_id,
+            "hx-on::before-request": validity_guard,
+            "hx-encoding": "multipart/form-data",
+        }
+    )
+    form_html = render_to_string(
+        "pudding/components/form.html",
+        {"form": form, "form_id": form_id},
+        request=request,
+    )
+
+    submit_btn = submit_btn.render(ctx=ctx)
+
+    return form_html, submit_btn
+
+
+class Add(InteractiveAction):
+    def __init__(
+        self,
+        slug: str = "add",
+        icon: str | None = "plus",
+        modal_frame: ui.Frame = ui.modal_frame,
+        **kwargs,
+    ):
+        self.modal_frame = modal_frame
+        super().__init__(slug=slug, icon=icon, **kwargs)
+
+    def before(self, request: HttpRequest, ctx: dict[str, Any]) -> HttpResponse:
+        domain = ctx["domain"]
+        model = domain.model
+
+        pks = request.POST.getlist("pks[]") or request.GET.getlist("pks[]")
+
+        FormClass = get_form_class(model=model)
+
+        base_label = _(model._meta.verbose_name_plural).title()
+        breadcrumbs = ui.Breadcrumbs(
+            children=tuple(
+                [
+                    ui.action("view", label=base_label, icon=domain.icon),
+                    ui.BreadcrumbLabel(label=_("Add"), icon="plus"),
+                ]
+            )
+        ).render(request=request, ctx=ctx)
+
+        form_html, submit_btn = get_content(
+            self, form=FormClass(), request=request, ctx=ctx
+        )
+        header_triggers = format_html(
+            '<div hx-vals="{ids}" class="flex gap-2 items-center"> {submit}</div>',
+            ids=json.dumps({"pks[]": pks}),
+            submit=submit_btn,
+        )
+
+        if actions.is_htmx(request):
+            return ui.ship(
+                ui.view_frame.fill(form_html),
+                ui.breadcrumb_frame.fill(breadcrumbs),
+                ui.header_triggers_frame.fill(header_triggers),
+                push_action_url={"action_slug": "add", "domain_slug": domain.slug},
+            )
+
+        context = ctx | {
+            "sidebar": build_sidebar_from_domains(ctx=ctx),
+            "breadcrumbs": ui.breadcrumb_frame(default_content=breadcrumbs).render(
+                request=request
+            ),
+            "view_area": ui.view_frame(default_content=form_html).render(
+                request=request
+            ),
+            "modal_frame": self.modal_frame.render(request=request),
+            "header_actions": ui.header_triggers_frame(
+                default_content=header_triggers
+            ).render(request=request),
+        }
+        response = render(request, "pudding/table.html", context)
+        return response
+
+    def execute(self, request: HttpRequest, ctx: dict[str, Any]) -> HttpResponse:
+        domain = ctx["domain"]
+        model = domain.model
+
+        FormClass = get_form_class(model=model)
+
+        form = FormClass(request.POST, request.FILES)
+        if form.is_valid():
+            form.save()
+            messages.success(
+                request,
+                _("{name} created successfully!").format(
+                    name=_(model._meta.verbose_name.capitalize())
+                ),
+            )
+            response = HttpResponse(status=204)
+            response["HX-Redirect"] = reverse(
+                "pudding:run_action",
+                kwargs={
+                    "domain_slug": domain.slug,
+                    "action_slug": "view",
+                },
+            )
+            return response
+        else:
+            form_html, submit_btn = get_content(
+                self, form=form, request=request, ctx=ctx
+            )
+            return ui.ship(
+                ui.view_frame.fill(form_html), ui.header_triggers_frame.fill(submit_btn)
+            )

django_pudding-0.1.0/src/pudding/actions/defaults/delete.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from typing import Any
+
+from django.contrib import messages
+from django.http import Http404, HttpRequest, HttpResponse
+from django.urls import reverse
+from django.utils.translation import gettext_lazy as _
+from django.utils.translation import ngettext
+
+from pudding import ui
+from pudding.actions.base import InteractiveAction
+from pudding.ui.frames.base import Frame
+
+
+class Delete(InteractiveAction):
+    def __init__(
+        self,
+        slug: str = "delete",
+        icon: str | None = "trash-2",
+        modal_frame: Frame = ui.modal_frame,
+        *args,
+        **kwargs,
+    ):
+        self.modal_frame = modal_frame
+        super().__init__(slug=slug, icon=icon, *args, **kwargs)
+
+    def before(self, request: HttpRequest, ctx: dict[str, Any]) -> HttpResponse:
+        domain = ctx["domain"]
+        model = domain.model
+
+        opts = model._meta
+        queryset = ctx["queryset"]
+        count = queryset.count()
+        if count == 0:
+            raise Http404(_("No items selected for deletion."))
+
+        if count == 1:
+            title = str(queryset.first())
+        else:
+            title = ngettext(
+                "{count} {model_name}", "{count} {model_name_plural}", count
+            ).format(
+                count=count,
+                model_name=opts.verbose_name,
+                model_name_plural=opts.verbose_name_plural,
+            )
+        return ui.ship(
+            self.modal_frame.fill(
+                ui.ActionModal(
+                    action=self,
+                    eyebrow=_("Delete"),
+                    title=title,
+                    button=lambda btn: btn(look=ui.looks.button(variant="danger")),
+                    icon_color="danger",
+                ).render(ctx=ctx)
+            )
+        )
+
+    def execute(self, request: HttpRequest, ctx: dict[str, Any]) -> HttpResponse:
+        model = ctx["domain"].model
+
+        opts = model._meta
+        queryset = ctx["queryset"]
+        count = queryset.count()
+        if count == 0:
+            raise Http404(_("No items selected for deletion."))
+
+        queryset.delete()
+
+        success_message = ngettext(
+            "Deleted {count} {model_name}.",
+            "Deleted {count} {model_name_plural}.",
+            count,
+        ).format(
+            count=count,
+            model_name=opts.verbose_name,
+            model_name_plural=opts.verbose_name_plural,
+        )
+
+        messages.success(request, success_message)
+        response = HttpResponse()
+        response["HX-Redirect"] = reverse(
+            "pudding:run_action",
+            kwargs={
+                "domain_slug": ctx["domain"].slug,
+                "action_slug": "view",
+                "step": "init",
+            },
+        )
+        return response

django_pudding-0.1.0/src/pudding/actions/defaults/edit.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from typing import Any
+
+from django.contrib import messages
+from django.http import HttpRequest, HttpResponse
+from django.urls import reverse
+from django.utils.translation import gettext_lazy as _
+
+from pudding import ui
+from pudding.actions.base import InteractiveAction
+from pudding.actions.defaults.utils import get_form_class
+
+
+class Edit(InteractiveAction):
+    def __init__(
+        self,
+        slug: str = "edit",
+        icon: str | None = "pen-line",
+        fields: list[str] | None = None,
+        exclude: list[str] | None = None,
+        dock_actions: list[ui.Trigger] | None = None,
+        modal_frame: ui.Frame = ui.modal_frame,
+        **kwargs,
+    ):
+        self.fields = fields
+        self.exclude = exclude
+        self.dock_actions: list[ui.Trigger] = dock_actions or []
+        self.modal_frame = modal_frame
+
+        super().__init__(slug=slug, icon=icon, **kwargs)
+
+    def before(self, request: HttpRequest, ctx: dict[str, Any]) -> HttpResponse:
+        domain = ctx["domain"]
+        model = domain.model
+
+        FormClass = get_form_class(model=model)
+
+        instance = ctx["queryset"][0] if ctx["queryset"] else None
+        form = FormClass(instance=instance)
+
+        return ui.ship(
+            self.modal_frame.fill(
+                ui.ActionModal(
+                    action=self, form=form, icon=None, title=f"Edit {instance}"
+                ).render(ctx=ctx)
+            )
+        )
+
+    def execute(self, request: HttpRequest, ctx: dict[str, Any]) -> HttpResponse:
+        domain = ctx["domain"]
+        model = domain.model
+
+        FormClass = get_form_class(model=model)
+
+        instance = ctx["queryset"][0] if ctx["queryset"] else None
+        form = FormClass(request.POST, request.FILES, instance=instance)
+        if form.is_valid():
+            form.save()
+            messages.success(
+                request,
+                _("{name} edited successfully!").format(
+                    name=_(model._meta.verbose_name.capitalize())
+                ),
+            )
+            response = HttpResponse(status=204)
+            response["HX-Redirect"] = reverse(
+                "pudding:run_action",
+                kwargs={
+                    "domain_slug": domain.slug,
+                    "action_slug": "view",
+                },
+            )
+            return response
+        else:
+            return ui.ship(
+                self.modal_frame.fill(
+                    ui.ActionModal(
+                        action=self, form=form, icon=None, title=f"Edit {instance}"
+                    ).render(ctx=ctx)
+                )
+            )