django-admin-runner 0.1.0__py3-none-any.whl

django_admin_runner/__init__.py

@@ -0,0 +1,15 @@
+from django_admin_runner.context import is_admin_runner, set_result_html
+from django_admin_runner.forms import FileField, FileOrPathField, FileOrPathWidget, ImageField
+from django_admin_runner.registry import register_command
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "register_command",
+    "is_admin_runner",
+    "set_result_html",
+    "FileOrPathField",
+    "FileOrPathWidget",
+    "FileField",
+    "ImageField",
+]

django_admin_runner/_ansi.py

@@ -0,0 +1,227 @@
+"""Minimal ANSI escape sequence to HTML converter.
+
+Converts SGR (Select Graphic Rendition) escape sequences to HTML ``<span>``
+elements with CSS classes and/or inline ``style`` attributes.
+
+Supported codes:
+- ``0``  — reset
+- ``1``  bold, ``2`` dim, ``3`` italic, ``4`` underline
+- ``22`` reset bold/dim, ``23`` reset italic, ``24`` reset underline
+- ``30–37`` / ``90–97``  — 4-bit foreground (standard + bright) → CSS class
+- ``40–47`` / ``100–107`` — 4-bit background → CSS class
+- ``38;5;N`` / ``48;5;N`` — 256-colour: N<16 → CSS class, N≥16 → inline rgb()
+- ``38;2;r;g;b`` / ``48;2;r;g;b`` — truecolor → inline rgb()
+- ``39`` / ``49`` — reset foreground / background
+
+4-bit colours map to ``ansi-fg-N`` / ``ansi-bg-N`` CSS classes (N = 0–15).
+Style attributes are provided by ``ansi-output.css`` via CSS custom properties,
+making the palette theme-aware (dark / light mode).
+"""
+
+from __future__ import annotations
+
+import html as _html
+import re
+from dataclasses import dataclass, field
+
+_ANSI_RE = re.compile(r"\x1b\[([0-9;]*)m")
+_URL_RE = re.compile(r"https?://[^\s<>\"]+")
+
+
+@dataclass
+class _State:
+    fg: int | None = None  # 0-15 → CSS class
+    bg: int | None = None
+    fg_rgb: tuple[int, int, int] | None = None  # truecolor / 256-colour ≥16
+    bg_rgb: tuple[int, int, int] | None = None
+    attrs: set[str] = field(default_factory=set)  # bold, dim, italic, underline
+
+    def reset(self) -> None:
+        self.fg = None
+        self.bg = None
+        self.fg_rgb = None
+        self.bg_rgb = None
+        self.attrs.clear()
+
+    def is_default(self) -> bool:
+        return (
+            self.fg is None
+            and self.bg is None
+            and self.fg_rgb is None
+            and self.bg_rgb is None
+            and not self.attrs
+        )
+
+    def css_classes(self) -> list[str]:
+        classes = [f"ansi-{a}" for a in sorted(self.attrs)]
+        if self.fg is not None:
+            classes.append(f"ansi-fg-{self.fg}")
+        if self.bg is not None:
+            classes.append(f"ansi-bg-{self.bg}")
+        return classes
+
+    def inline_styles(self) -> list[str]:
+        styles = []
+        if self.fg_rgb is not None:
+            r, g, b = self.fg_rgb
+            styles.append(f"color:rgb({r},{g},{b})")
+        if self.bg_rgb is not None:
+            r, g, b = self.bg_rgb
+            styles.append(f"background:rgb({r},{g},{b})")
+        return styles
+
+
+def _256_to_rgb(n: int) -> tuple[int, int, int]:
+    """Convert 256-colour index ≥16 to ``(r, g, b)``."""
+    if n < 232:
+        n -= 16
+        return ((n // 36) * 51, ((n % 36) // 6) * 51, (n % 6) * 51)
+    v = (n - 232) * 10 + 8
+    return (v, v, v)
+
+
+def _apply_sgr(state: _State, params: list[int]) -> None:
+    """Apply a list of SGR parameter values to *state* in-place."""
+    i = 0
+    while i < len(params):
+        p = params[i]
+
+        if p == 0:
+            state.reset()
+        elif p == 1:
+            state.attrs.add("bold")
+        elif p == 2:
+            state.attrs.add("dim")
+        elif p == 3:
+            state.attrs.add("italic")
+        elif p == 4:
+            state.attrs.add("underline")
+        elif p == 22:
+            state.attrs.discard("bold")
+            state.attrs.discard("dim")
+        elif p == 23:
+            state.attrs.discard("italic")
+        elif p == 24:
+            state.attrs.discard("underline")
+        elif 30 <= p <= 37:
+            state.fg = p - 30
+            state.fg_rgb = None
+        elif p == 38:
+            if i + 1 < len(params) and params[i + 1] == 5 and i + 2 < len(params):
+                n = params[i + 2]
+                if n < 16:
+                    state.fg = n
+                    state.fg_rgb = None
+                else:
+                    state.fg = None
+                    state.fg_rgb = _256_to_rgb(n)
+                i += 2
+            elif i + 1 < len(params) and params[i + 1] == 2 and i + 4 < len(params):
+                state.fg = None
+                state.fg_rgb = (params[i + 2], params[i + 3], params[i + 4])
+                i += 4
+        elif p == 39:
+            state.fg = None
+            state.fg_rgb = None
+        elif 40 <= p <= 47:
+            state.bg = p - 40
+            state.bg_rgb = None
+        elif p == 48:
+            if i + 1 < len(params) and params[i + 1] == 5 and i + 2 < len(params):
+                n = params[i + 2]
+                if n < 16:
+                    state.bg = n
+                    state.bg_rgb = None
+                else:
+                    state.bg = None
+                    state.bg_rgb = _256_to_rgb(n)
+                i += 2
+            elif i + 1 < len(params) and params[i + 1] == 2 and i + 4 < len(params):
+                state.bg = None
+                state.bg_rgb = (params[i + 2], params[i + 3], params[i + 4])
+                i += 4
+        elif p == 49:
+            state.bg = None
+            state.bg_rgb = None
+        elif 90 <= p <= 97:
+            state.fg = p - 90 + 8  # bright colours → indices 8–15
+            state.fg_rgb = None
+        elif 100 <= p <= 107:
+            state.bg = p - 100 + 8
+            state.bg_rgb = None
+
+        i += 1
+
+
+def ansi_to_html(text: str) -> str:
+    """Convert ANSI escape sequences in *text* to HTML ``<span>`` elements.
+
+    Text content is HTML-escaped.  Spans use CSS classes for 4-bit colours
+    (``ansi-fg-N`` / ``ansi-bg-N``) and inline ``style`` attributes for
+    256-colour (indices ≥16) and truecolor values.
+    """
+    result: list[str] = []
+    state = _State()
+    span_open = False
+
+    def flush_span() -> None:
+        nonlocal span_open
+        if span_open:
+            result.append("</span>")
+            span_open = False
+
+    def emit_text(chunk: str) -> None:
+        nonlocal span_open
+        if not chunk:
+            return
+        if not span_open and not state.is_default():
+            classes = state.css_classes()
+            styles = state.inline_styles()
+            attrs = ""
+            if classes:
+                attrs += f' class="{" ".join(classes)}"'
+            if styles:
+                attrs += f' style="{";".join(styles)}"'
+            result.append(f"<span{attrs}>")
+            span_open = True
+        result.append(_html.escape(chunk))
+
+    pos = 0
+    for match in _ANSI_RE.finditer(text):
+        start, end = match.span()
+        emit_text(text[pos:start])
+        flush_span()
+        raw = match.group(1)
+        params = [int(x) for x in raw.split(";") if x] if raw else [0]
+        _apply_sgr(state, params)
+        pos = end
+
+    emit_text(text[pos:])
+    flush_span()
+
+    return "".join(result)
+
+
+def linkify_urls(html: str) -> str:
+    """Wrap plain-text URLs in *html* with ``<a>`` tags.
+
+    Operates on the output of :func:`ansi_to_html` — text content has already
+    been HTML-escaped (e.g. ``&amp;``), so URL detection runs on the escaped
+    form.  The regex avoids matching inside existing HTML tags by excluding
+    ``<``, ``>``, and ``"`` characters.
+    """
+    trailing_punct = set(".,;:!?")
+
+    def _replace(m: re.Match[str]) -> str:
+        url = m.group(0)
+        # Strip trailing punctuation that's unlikely to be part of the URL
+        stripped = []
+        while url and url[-1] in trailing_punct:
+            stripped.append(url[-1])
+            url = url[:-1]
+        href = _html.unescape(url)
+        link = f'<a href="{_html.escape(href)}" target="_blank">{url}</a>'
+        # Re-append stripped punctuation after the link
+        return link + "".join(reversed(stripped))
+
+    return _URL_RE.sub(_replace, html)

django_admin_runner/admin.py

@@ -0,0 +1,450 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+from django.contrib import admin
+from django.http import Http404, HttpResponse, HttpResponseForbidden
+from django.shortcuts import redirect, render
+from django.urls import path, reverse
+from django.utils.safestring import SafeString, mark_safe
+
+from ._ansi import ansi_to_html as _convert_ansi
+from ._ansi import linkify_urls as _linkify
+from .admin_compat import get_model_admin_base, get_template, is_unfold_installed
+from .forms import form_from_command
+from .models import CommandExecution, RegisteredCommand
+from .registry import _registry, has_permission
+from .runners import get_runner
+
+if TYPE_CHECKING:
+    from django.db import models as _models
+
+
+def _ansi_to_html(text: str) -> SafeString:
+    """Wrap ANSI-coded *text* in a themed ``<pre>`` block with clickable URLs."""
+    html = _linkify(_convert_ansi(text))
+    return cast(SafeString, mark_safe(f'<pre class="ansi-output">{html}</pre>'))
+
+
+# ---------------------------------------------------------------------------
+# Mixin for model admins that want attached command run links
+# ---------------------------------------------------------------------------
+
+
+class CommandRunnerModelAdminMixin:
+    """Mix into any ``ModelAdmin`` to show "Run" links for commands registered with
+    ``models=[ThisModel]``.
+
+    Example:
+
+    ```python
+    from django.contrib import admin
+    from django_admin_runner.admin import CommandRunnerModelAdminMixin
+
+    @admin.register(Book)
+    class BookAdmin(CommandRunnerModelAdminMixin, admin.ModelAdmin):
+        ...
+    ```
+    """
+
+    model: type[_models.Model]  # provided by the ModelAdmin subclass
+
+    def changelist_view(self, request, extra_context=None):
+        attached = [
+            entry
+            for entry in _registry.values()
+            if self.model in entry["models"] and has_permission(request.user, entry)
+        ]
+        extra_context = extra_context or {}
+        extra_context["admin_runner_commands"] = attached
+        return super().changelist_view(request, extra_context=extra_context)  # type: ignore[misc]
+
+
+# ---------------------------------------------------------------------------
+# CommandExecution admin (also hosts the command list/run views)
+# ---------------------------------------------------------------------------
+
+_ModelAdminBase = get_model_admin_base()
+
+
+class ActiveListFilter(admin.SimpleListFilter):
+    title = "active"
+    parameter_name = "active"
+
+    def lookups(self, request, model_admin):
+        return [("1", "Yes"), ("0", "No")]
+
+    def queryset(self, request, queryset):
+        if self.value() == "0":
+            return queryset.filter(active=False)
+        return queryset.filter(active=True)
+
+
+@admin.register(RegisteredCommand)
+class RegisteredCommandAdmin(_ModelAdminBase):  # type: ignore[misc]
+    list_display = [
+        "name_link",
+        "group",
+        "active",
+        "updated_at",
+        "buttons",
+    ]
+    list_display_links = None
+    search_fields = ["name", "display_name"]
+    list_filter = [ActiveListFilter, "group"]
+    ordering = ["group", "name"]
+
+    def has_add_permission(self, request):
+        return False
+
+    def has_change_permission(self, request, obj=None):
+        return False
+
+    def has_delete_permission(self, request, obj=None):
+        return request.user.is_superuser
+
+    def changelist_view(self, request, extra_context=None):
+        # Default the active filter to "Yes" when no active param is present
+        if "active" not in request.GET:
+            qp = request.GET.copy()
+            qp["active"] = "1"
+            return redirect(f"{request.path}?{qp.urlencode()}")
+        return super().changelist_view(request, extra_context=extra_context)
+
+    @admin.display(description="Name", ordering="name")
+    def name_link(self, obj: RegisteredCommand) -> SafeString:
+        name_html = f"<strong>{obj.display_name}</strong>"
+        desc_html = ""
+        if obj.description:
+            desc_html = (
+                f'<br><span style="color:var(--body-quiet-color,#666);'
+                f"max-width:300px;display:inline-block;overflow:hidden;"
+                f"text-overflow:ellipsis;white-space:nowrap;"
+                f'font-size:12px;">{obj.description}</span>'
+            )
+        if obj.active:
+            run_url = reverse("admin:django_admin_runner_command_run", args=[obj.name])
+            return cast(SafeString, mark_safe(f'<a href="{run_url}">{name_html}</a>{desc_html}'))
+        return cast(SafeString, mark_safe(f"{name_html}{desc_html}"))
+
+    @admin.display(description="")
+    def buttons(self, obj: RegisteredCommand) -> SafeString:
+        parts: list[str] = []
+        if obj.active:
+            run_url = reverse("admin:django_admin_runner_command_run", args=[obj.name])
+            parts.append(
+                f'<a href="{run_url}" '
+                f'style="display:inline-block;padding:4px 10px;border-radius:4px;'
+                f"font-size:11px;font-weight:600;color:#fff;"
+                f'background:#28a745;text-decoration:none;">Run</a>'
+            )
+        history_url = (
+            reverse("admin:django_admin_runner_commandexecution_changelist")
+            + f"?command_name={obj.name}"
+        )
+        parts.append(
+            f'<a href="{history_url}" '
+            f'style="display:inline-block;padding:4px 10px;border-radius:4px;'
+            f"font-size:11px;font-weight:600;color:#fff;"
+            f'background:#0d6efd;text-decoration:none;">History</a>'
+        )
+        return cast(SafeString, mark_safe(" ".join(parts)))
+
+
+@admin.register(CommandExecution)
+class CommandExecutionAdmin(_ModelAdminBase):  # type: ignore[misc]
+    class Media:
+        css = {"all": ("django_admin_runner/ansi-output.css",)}
+
+    list_display = [
+        "command_name",
+        "status",
+        "triggered_by",
+        "backend",
+        "created_at",
+        "result_button",
+    ]
+    list_filter = ["status", "backend"]
+    search_fields = ["command_name", "triggered_by__username"]
+    readonly_fields = [
+        "command_name",
+        "status",
+        "result_html_display",
+        "stdout_display",
+        "stderr_display",
+        "kwargs",
+        "triggered_by",
+        "backend",
+        "task_id",
+        "created_at",
+        "started_at",
+        "finished_at",
+    ]
+    fieldsets = [
+        (
+            None,
+            {
+                "fields": [
+                    "command_name",
+                    "status",
+                    "kwargs",
+                    "triggered_by",
+                    "backend",
+                    "task_id",
+                ]
+            },
+        ),
+        (
+            "Result",
+            {
+                "fields": ["result_html_display"],
+            },
+        ),
+        (
+            "Output",
+            {
+                "fields": ["stdout_display", "stderr_display"],
+            },
+        ),
+        (
+            "Timing",
+            {
+                "fields": ["created_at", "started_at", "finished_at"],
+                "classes": ["collapse"],
+            },
+        ),
+    ]
+    ordering = ["-created_at"]
+
+    @admin.display(description="Standard output")
+    def stdout_display(self, obj: CommandExecution) -> SafeString:
+        stdout = str(obj.stdout)
+        if not stdout:
+            return cast(SafeString, mark_safe("<em>—</em>"))
+        url = reverse(
+            "admin:django_admin_runner_commandexecution_stdout",
+            args=[obj.pk],
+        )
+        html = f'{_ansi_to_html(stdout)}<p><a href="{url}">Full View</a></p>'
+        return cast(SafeString, mark_safe(html))
+
+    @admin.display(description="Standard error / traceback")
+    def stderr_display(self, obj: CommandExecution) -> SafeString:
+        stderr = str(obj.stderr)
+        if not stderr:
+            return cast(SafeString, mark_safe("<em>—</em>"))
+        url = reverse(
+            "admin:django_admin_runner_commandexecution_stderr",
+            args=[obj.pk],
+        )
+        html = f'{_ansi_to_html(stderr)}<p><a href="{url}">Full View</a></p>'
+        return cast(SafeString, mark_safe(html))
+
+    @admin.display(description="Result")
+    def result_html_display(self, obj: CommandExecution) -> SafeString:
+        if not obj.result_html:
+            return cast(SafeString, mark_safe("<em>—</em>"))
+        result_url = reverse(
+            "admin:django_admin_runner_commandexecution_result",
+            args=[obj.pk],
+        )
+        html = (
+            f'<div style="max-height:300px;overflow:auto;border:1px solid #ddd;'
+            f'padding:8px;border-radius:4px;margin-bottom:8px;">'
+            f"{obj.result_html}</div>"
+            f'<a href="{result_url}">Full View</a>'
+        )
+        return cast(SafeString, mark_safe(html))
+
+    @admin.display(description="", ordering="created_at")
+    def result_button(self, obj: CommandExecution) -> SafeString:
+        buttons: list[str] = []
+        if obj.result_html:
+            url = reverse(
+                "admin:django_admin_runner_commandexecution_result",
+                args=[obj.pk],
+            )
+            buttons.append(
+                f'<a href="{url}" '
+                f'style="display:inline-block;padding:4px 10px;border-radius:4px;'
+                f"font-size:11px;font-weight:600;color:#fff;"
+                f'background:#28a745;text-decoration:none;margin-right:4px;"'
+                f">View</a>"
+            )
+        if obj.stdout:
+            url = reverse(
+                "admin:django_admin_runner_commandexecution_stdout",
+                args=[obj.pk],
+            )
+            buttons.append(
+                f'<a href="{url}" '
+                f'style="display:inline-block;padding:4px 10px;border-radius:4px;'
+                f"font-size:11px;font-weight:600;color:#fff;"
+                f'background:#0d6efd;text-decoration:none;margin-right:4px;"'
+                f">Stdout</a>"
+            )
+        if obj.stderr:
+            url = reverse(
+                "admin:django_admin_runner_commandexecution_stderr",
+                args=[obj.pk],
+            )
+            buttons.append(
+                f'<a href="{url}" '
+                f'style="display:inline-block;padding:4px 10px;border-radius:4px;'
+                f"font-size:11px;font-weight:600;color:#fff;"
+                f'background:#dc3545;text-decoration:none;margin-right:4px;"'
+                f">Stderr</a>"
+            )
+        if not buttons:
+            return cast(SafeString, mark_safe("<span>—</span>"))
+        return cast(SafeString, mark_safe("".join(buttons)))
+
+    def has_add_permission(self, request):
+        return False
+
+    def get_queryset(self, request):
+        qs = super().get_queryset(request)
+        if request.user.has_perm("django_admin_runner.view_all_executions"):
+            return qs
+        return qs.filter(triggered_by=request.user)
+
+    # ------------------------------------------------------------------
+    # Extra URLs: command list + run form
+    # ------------------------------------------------------------------
+
+    def get_urls(self):
+        urls = super().get_urls()
+        custom = [
+            path(
+                "commands/<str:command_name>/run/",
+                self.admin_site.admin_view(self._command_run_view),
+                name="django_admin_runner_command_run",
+            ),
+            path(
+                "<path:object_id>/result/",
+                self.admin_site.admin_view(self._result_view),
+                name="django_admin_runner_commandexecution_result",
+            ),
+            path(
+                "<path:object_id>/stdout/",
+                self.admin_site.admin_view(self._stdout_view),
+                name="django_admin_runner_commandexecution_stdout",
+            ),
+            path(
+                "<path:object_id>/stderr/",
+                self.admin_site.admin_view(self._stderr_view),
+                name="django_admin_runner_commandexecution_stderr",
+            ),
+        ]
+        return custom + urls
+
+    def _get_execution(self, request, object_id):
+        """Fetch execution or 404, respecting queryset permissions."""
+        execution = self.get_queryset(request).filter(pk=object_id).first()
+        if execution is None:
+            raise Http404
+        return execution
+
+    def _render_output(
+        self,
+        request,
+        execution: CommandExecution,
+        title: str,
+        content: SafeString,
+    ) -> HttpResponse:
+        change_url = reverse(
+            "admin:django_admin_runner_commandexecution_change",
+            args=[execution.pk],
+        )
+        context = {
+            **self.admin_site.each_context(request),
+            "title": title,
+            "execution": execution,
+            "content": content,
+            "change_url": change_url,
+            "opts": self.model._meta,
+            "is_unfold": is_unfold_installed(),
+        }
+        return render(request, get_template("result"), context)
+
+    def _result_view(self, request, object_id):
+        """Standalone result page: result_html if set, otherwise stdout."""
+        execution = self._get_execution(request, object_id)
+
+        if execution.result_html:
+            content = cast(SafeString, mark_safe(execution.result_html))
+        else:
+            stdout = str(execution.stdout)
+            content = _ansi_to_html(stdout) if stdout else cast(SafeString, mark_safe(""))
+
+        return self._render_output(
+            request,
+            execution,
+            f"Result: {execution.command_name}",
+            content,
+        )
+
+    def _stdout_view(self, request, object_id):
+        """Standalone stdout page."""
+        execution = self._get_execution(request, object_id)
+        stdout = str(execution.stdout)
+        content = _ansi_to_html(stdout) if stdout else cast(SafeString, mark_safe("<em>—</em>"))
+        return self._render_output(
+            request,
+            execution,
+            f"Output: {execution.command_name}",
+            content,
+        )
+
+    def _stderr_view(self, request, object_id):
+        """Standalone stderr/traceback page."""
+        execution = self._get_execution(request, object_id)
+        stderr = str(execution.stderr)
+        content = _ansi_to_html(stderr) if stderr else cast(SafeString, mark_safe("<em>—</em>"))
+        return self._render_output(
+            request,
+            execution,
+            f"Traceback: {execution.command_name}",
+            content,
+        )
+
+    def _command_run_view(self, request, command_name: str):
+        if command_name not in _registry:
+            raise Http404(f"Command '{command_name}' is not registered.")
+
+        entry = _registry[command_name]
+        if not has_permission(request.user, entry):
+            return HttpResponseForbidden(b"You do not have permission to run this command.")
+
+        FormClass = form_from_command(command_name)
+
+        if request.method == "POST":
+            form = FormClass(request.POST, request.FILES)
+            if form.is_valid():
+                kwargs = {}
+                for k, v in form.cleaned_data.items():
+                    if isinstance(v, bool):
+                        kwargs[k] = v  # always include booleans (True and False)
+                    elif v not in ("", None):
+                        kwargs[k] = v  # exclude empty strings and None
+                execution = CommandExecution.objects.create(
+                    command_name=command_name,
+                    kwargs=kwargs,
+                    triggered_by=request.user,
+                )
+                runner = get_runner()
+                result = runner.run(command_name, kwargs, request.user, execution)
+                return redirect(result.redirect_url)
+        else:
+            form = FormClass()
+
+        context = {
+            **self.admin_site.each_context(request),
+            "title": f"Run: {command_name}",
+            "form": form,
+            "command_name": command_name,
+            "entry": entry,
+            "opts": self.model._meta,
+            "is_unfold": is_unfold_installed(),
+        }
+        return render(request, get_template("run"), context)