django-admin-runner 0.1.0__tar.gz

django_admin_runner-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.pyo
+.venv/
+venv/
+.env
+*.egg-info/
+dist/
+build/
+.coverage
+htmlcov/
+.pytest_cache/
+.ruff_cache/
+site/
+*.sqlite3
+uv.lock

django_admin_runner-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: django-admin-runner
+Version: 0.1.0
+Summary: Run Django management commands from the admin with auto-generated forms and pluggable task runners
+Project-URL: Homepage, https://github.com/burgdev/django-admin-runner
+Project-URL: Documentation, https://burgdev.github.io/django-admin-runner
+Project-URL: Repository, https://github.com/burgdev/django-admin-runner
+Project-URL: Issues, https://github.com/burgdev/django-admin-runner/issues
+Project-URL: Changelog, https://github.com/burgdev/django-admin-runner/blob/main/CHANGELOG.md
+License: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 6.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: >=3.12
+Requires-Dist: django>=6.0
+Provides-Extra: celery
+Requires-Dist: celery>=5.3; extra == 'celery'
+Provides-Extra: django-q2
+Requires-Dist: django-q2>=1.5; extra == 'django-q2'
+Provides-Extra: rich
+Requires-Dist: rich>=13.0; extra == 'rich'
+Provides-Extra: unfold
+Requires-Dist: django-unfold>=0.40; extra == 'unfold'
+Description-Content-Type: text/markdown
+
+<h3 align="center"><b>django-admin-runner</b></h3>
+<p align="center">
+  <em>Run Django management commands from the admin — with auto-generated forms,
+  pluggable task runners, and a unified execution log.</em>
+</p>
+<p align="center">
+    <b><a href="https://burgdev.github.io/django-admin-runner">Documentation</a></b>
+    | <b><a href="https://pypi.org/project/django-admin-runner">PyPI</a></b>
+    | <b><a href="https://github.com/burgdev/django-admin-runner/blob/main/CHANGELOG.md">Changelog</a></b>
+</p>
+
+---
+
+## Features
+
+- **`@register_command` decorator** — register any management command with metadata
+- **Auto-generated forms** — argparse arguments become Django form fields automatically
+- **Widget & form customisation** — override widgets per-argument (`widget=` on `add_argument`), supply a custom `Form` class, or use per-parameter field overrides in the decorator
+- **Built-in file fields** — `FileOrPathField` (upload or server path), `FileField`, `ImageField`
+- **Pluggable runners** — Django Tasks (default), Celery, sync, or custom
+- **Execution log** — every run is stored as a `CommandExecution` record
+- **Permission control** — per-command permission requirements (superuser, Django perms, or a list)
+- **Model attachment** — show a "Run" button on any model's admin change-list via `models=[...]`
+- **Unfold support** — auto-detected, uses Unfold templates and widgets when available
+
+## Installation
+
+```bash
+pip install django-admin-runner
+```
+
+Add to `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    ...
+    "django_admin_runner",
+]
+```
+
+Run migrations:
+
+```bash
+python manage.py migrate
+```
+
+## Quick start
+
+```python
+# myapp/management/commands/my_command.py
+from django.core.management.base import BaseCommand
+from django_admin_runner import register_command
+
+@register_command(group="Maintenance", permission="myapp.change_mymodel")
+class Command(BaseCommand):
+    help = "Does something useful"
+
+    def add_arguments(self, parser):
+        parser.add_argument("--count", type=int, default=10)
+        parser.add_argument("--dry-run", action="store_true")
+
+    def handle(self, *args, **options):
+        self.stdout.write(f"Running {options['count']} times")
+```
+
+Visit `/admin/django_admin_runner/commandexecution/commands/` to run your commands.
+
+### Custom widgets
+
+Override how individual parameters render — right inside `add_arguments`:
+
+```python
+from django_admin_runner import FileOrPathField, register_command
+
+@register_command(group="Import")
+class Command(BaseCommand):
+    def add_arguments(self, parser):
+        # File upload OR server-side path text field
+        parser.add_argument("--source", widget=FileOrPathField(), default="data.csv")
+        # Swap to a textarea
+        parser.add_argument("--notes", widget=forms.Textarea(attrs={"rows": 3}))
+        # Image upload (requires Pillow)
+        parser.add_argument("--photo", widget=forms.ImageField(required=False))
+```
+
+Or provide a fully custom form class:
+
+```python
+@register_command(form_class=MyImportForm)
+class Command(BaseCommand):
+    ...
+```
+
+See the [Widget & form customisation](https://burgdev.github.io/django-admin-runner/widgets/) docs for the full reference.
+
+## Development
+
+**Requirements:** [uv](https://docs.astral.sh/uv/) and [just](https://github.com/casey/just)
+
+```bash
+# Install dependencies and pre-commit hooks
+just install
+
+# Run tests
+just tests
+
+# Run linters
+just check
+
+# Serve docs locally
+just docs
+```
+
+## Contributing
+
+Contributions are welcome! Please open an issue or pull request on
+[GitHub](https://github.com/burgdev/django-admin-runner).
+
+## License
+
+MIT

django_admin_runner-0.1.0/README.md

@@ -0,0 +1,121 @@
+<h3 align="center"><b>django-admin-runner</b></h3>
+<p align="center">
+  <em>Run Django management commands from the admin — with auto-generated forms,
+  pluggable task runners, and a unified execution log.</em>
+</p>
+<p align="center">
+    <b><a href="https://burgdev.github.io/django-admin-runner">Documentation</a></b>
+    | <b><a href="https://pypi.org/project/django-admin-runner">PyPI</a></b>
+    | <b><a href="https://github.com/burgdev/django-admin-runner/blob/main/CHANGELOG.md">Changelog</a></b>
+</p>
+
+---
+
+## Features
+
+- **`@register_command` decorator** — register any management command with metadata
+- **Auto-generated forms** — argparse arguments become Django form fields automatically
+- **Widget & form customisation** — override widgets per-argument (`widget=` on `add_argument`), supply a custom `Form` class, or use per-parameter field overrides in the decorator
+- **Built-in file fields** — `FileOrPathField` (upload or server path), `FileField`, `ImageField`
+- **Pluggable runners** — Django Tasks (default), Celery, sync, or custom
+- **Execution log** — every run is stored as a `CommandExecution` record
+- **Permission control** — per-command permission requirements (superuser, Django perms, or a list)
+- **Model attachment** — show a "Run" button on any model's admin change-list via `models=[...]`
+- **Unfold support** — auto-detected, uses Unfold templates and widgets when available
+
+## Installation
+
+```bash
+pip install django-admin-runner
+```
+
+Add to `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    ...
+    "django_admin_runner",
+]
+```
+
+Run migrations:
+
+```bash
+python manage.py migrate
+```
+
+## Quick start
+
+```python
+# myapp/management/commands/my_command.py
+from django.core.management.base import BaseCommand
+from django_admin_runner import register_command
+
+@register_command(group="Maintenance", permission="myapp.change_mymodel")
+class Command(BaseCommand):
+    help = "Does something useful"
+
+    def add_arguments(self, parser):
+        parser.add_argument("--count", type=int, default=10)
+        parser.add_argument("--dry-run", action="store_true")
+
+    def handle(self, *args, **options):
+        self.stdout.write(f"Running {options['count']} times")
+```
+
+Visit `/admin/django_admin_runner/commandexecution/commands/` to run your commands.
+
+### Custom widgets
+
+Override how individual parameters render — right inside `add_arguments`:
+
+```python
+from django_admin_runner import FileOrPathField, register_command
+
+@register_command(group="Import")
+class Command(BaseCommand):
+    def add_arguments(self, parser):
+        # File upload OR server-side path text field
+        parser.add_argument("--source", widget=FileOrPathField(), default="data.csv")
+        # Swap to a textarea
+        parser.add_argument("--notes", widget=forms.Textarea(attrs={"rows": 3}))
+        # Image upload (requires Pillow)
+        parser.add_argument("--photo", widget=forms.ImageField(required=False))
+```
+
+Or provide a fully custom form class:
+
+```python
+@register_command(form_class=MyImportForm)
+class Command(BaseCommand):
+    ...
+```
+
+See the [Widget & form customisation](https://burgdev.github.io/django-admin-runner/widgets/) docs for the full reference.
+
+## Development
+
+**Requirements:** [uv](https://docs.astral.sh/uv/) and [just](https://github.com/casey/just)
+
+```bash
+# Install dependencies and pre-commit hooks
+just install
+
+# Run tests
+just tests
+
+# Run linters
+just check
+
+# Serve docs locally
+just docs
+```
+
+## Contributing
+
+Contributions are welcome! Please open an issue or pull request on
+[GitHub](https://github.com/burgdev/django-admin-runner).
+
+## License
+
+MIT

django_admin_runner-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "django-admin-runner"
+version = "0.1.0"
+description = "Run Django management commands from the admin with auto-generated forms and pluggable task runners"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.12"
+dependencies = ["django>=6.0"]
+
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Framework :: Django",
+  "Framework :: Django :: 6.0",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Internet :: WWW/HTTP :: Dynamic Content",
+]
+
+[project.optional-dependencies]
+celery = ["celery>=5.3"]
+django-q2 = ["django-q2>=1.5"]
+unfold = ["django-unfold>=0.40"]
+rich = ["rich>=13.0"]
+
+[project.urls]
+Homepage = "https://github.com/burgdev/django-admin-runner"
+Documentation = "https://burgdev.github.io/django-admin-runner"
+Repository = "https://github.com/burgdev/django-admin-runner"
+Issues = "https://github.com/burgdev/django-admin-runner/issues"
+Changelog = "https://github.com/burgdev/django-admin-runner/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+  "bump2version>=1.0.1",
+  "git-cliff>=2.7.0",
+  "pre-commit>=4.0.1",
+  "pyright>=1.1.0",
+  "ruff>=0.8.2",
+]
+docs = [
+  "zensical>=0.0.32",
+  "mkdocs-open-in-new-tab>=1.0.8",
+  "mkdocs-literate-nav>=0.6.1",
+  "mkdocs-section-index>=0.3.9",
+  "mkdocstrings[python]>=0.22.0",
+]
+test = [
+  "pytest>=8.3.4",
+  "pytest-django>=4.10.0",
+  "pytest-cov>=4.1.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/django_admin_runner"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/django_admin_runner"]
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.settings"
+pythonpath = ["src", "."]
+
+[tool.ruff]
+src = ["src"]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]

django_admin_runner-0.1.0/src/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-0.1.0/src/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)