hunt-framework 0.2.2__py3-none-any.whl

hunt/__init__.py

@@ -0,0 +1,15 @@
+"""
+hunt — A Python web framework.
+
+Quick start:
+    from hunt.application import Application
+    from hunt.http.router import Router
+    from hunt.http.kernel import HttpKernel
+    from hunt.database.model import Model
+    from hunt.database.schema.builder import Schema
+    from hunt.database.schema.migration import Migration
+    from hunt.view.factory import ViewFactory
+    from hunt.validation.validator import Validator
+"""
+
+__version__ = "0.2.2"

hunt/admin/__init__.py

@@ -0,0 +1,53 @@
+from hunt.admin.action import Action, ActionResponse
+from hunt.admin.application import Admin
+from hunt.admin.fields import (
+    Badge,
+    BelongsTo,
+    Boolean,
+    Currency,
+    Date,
+    DateTime,
+    Email,
+    HasMany,
+    Number,
+    Password,
+    Select,
+    Slug,
+    Text,
+    Textarea,
+)
+from hunt.admin.filter import BooleanFilter, Filter, SelectFilter, TrashedFilter
+from hunt.admin.metrics import PartitionMetric, TrendMetric, ValueMetric
+from hunt.admin.navigation import NavGroup, NavLink, NavResource
+from hunt.admin.resource import AdminResource
+
+__all__ = [
+    "Action",
+    "ActionResponse",
+    "Admin",
+    "AdminResource",
+    "Badge",
+    "BelongsTo",
+    "Boolean",
+    "BooleanFilter",
+    "Currency",
+    "Date",
+    "DateTime",
+    "Email",
+    "Filter",
+    "HasMany",
+    "NavGroup",
+    "NavLink",
+    "NavResource",
+    "Number",
+    "PartitionMetric",
+    "Password",
+    "Select",
+    "SelectFilter",
+    "Slug",
+    "Text",
+    "Textarea",
+    "TrashedFilter",
+    "TrendMetric",
+    "ValueMetric",
+]

hunt/admin/action.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from hunt.support.str import Str
+
+
+class ActionResponse:
+    """Result returned from an Action.handle() call."""
+
+    def __init__(
+        self,
+        type: str,
+        text: str = "",
+        url: str = "",
+        message_type: str = "success",
+    ) -> None:
+        self.type = type  # "message" | "redirect"
+        self.text = text
+        self.url = url
+        self.message_type = message_type  # "success" | "error" | "warning" | "info"
+
+    @classmethod
+    def success(cls, text: str) -> ActionResponse:
+        return cls(type="message", text=text, message_type="success")
+
+    @classmethod
+    def error(cls, text: str) -> ActionResponse:
+        return cls(type="message", text=text, message_type="error")
+
+    @classmethod
+    def message(cls, text: str, type: str = "success") -> ActionResponse:
+        return cls(type="message", text=text, message_type=type)
+
+    @classmethod
+    def redirect(cls, url: str) -> ActionResponse:
+        return cls(type="redirect", url=url)
+
+    def to_dict(self) -> dict:
+        return {
+            "type": self.type,
+            "text": self.text,
+            "url": self.url,
+            "message_type": self.message_type,
+        }
+
+
+class Action:
+    """Base class for admin actions that operate on one or more model instances."""
+
+    name: str = "Action"
+    destructive: bool = False
+    confirmation_text: str = ""
+
+    @classmethod
+    def slug(cls) -> str:
+        return Str.snake(cls.name).replace(" ", "_").lower()
+
+    def handle(self, request: object, models: list) -> ActionResponse:
+        raise NotImplementedError(f"{type(self).__name__} must implement handle()")

hunt/admin/application.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+from jinja2 import ChoiceLoader, Environment, FileSystemLoader, select_autoescape
+
+from hunt.http.response import Response
+
+
+@lru_cache(maxsize=1)
+def _get_env() -> Environment:
+    package_templates = Path(__file__).parent / "templates"
+    loaders: list = []
+    # App-level overrides: resources/views takes priority over package templates
+    app_views = Path.cwd() / "resources" / "views"
+    if app_views.is_dir():
+        loaders.append(FileSystemLoader(str(app_views)))
+    loaders.append(FileSystemLoader(str(package_templates)))
+    env = Environment(
+        loader=ChoiceLoader(loaders),
+        autoescape=select_autoescape(["html", "xml"]),
+    )
+    env.filters["tojson"] = lambda value, **kw: json.dumps(value, default=str, **kw)
+    return env
+
+
+class _Admin:
+    """
+    Singleton admin application.
+
+    Usage::
+
+        from hunt.admin import Admin
+
+        @Admin.resource
+        class PostResource(AdminResource):
+            ...
+
+        Admin.dashboard(TotalPostsMetric)
+        Admin.gate(lambda request: Auth.user() and Auth.user().is_admin)
+        Admin.register_to(router)
+    """
+
+    def __init__(self) -> None:
+        self._resources: list[type] = []
+        self._dashboard_cards: list = []
+        self._tools: list[dict] = []
+        self._gate: Callable | None = None
+        self._nav: list | None = None
+        self.prefix: str = "/hunt-admin"
+        self.brand_name: str = "Hunt Admin"
+
+    # ------------------------------------------------------------------
+    # Registration API
+    # ------------------------------------------------------------------
+
+    def resource(self, cls: type) -> type:
+        """Decorator that registers an AdminResource subclass."""
+        self._resources.append(cls)
+        return cls
+
+    def dashboard(self, *cards: Any) -> None:
+        """Set the metric cards shown on the dashboard."""
+        self._dashboard_cards = list(cards)
+
+    def gate(self, fn: Callable) -> None:
+        """Set a callable that receives the request and returns True/False."""
+        self._gate = fn
+
+    def tool(self, label: str, cls: type) -> None:
+        """Register a custom tool page."""
+        self._tools.append({"label": label, "cls": cls})
+
+    def navigation(self, items: list) -> None:
+        """Set a custom navigation structure for the admin sidebar."""
+        self._nav = items
+
+    def _build_nav(self) -> list:
+        from hunt.admin.navigation import _DEFAULT_TOOL_ICON, NavGroup, NavLink, NavResource
+
+        if self._nav is not None:
+            return self._nav
+        items: list = []
+        if self._resources:
+            items.append(NavGroup("Resources", [NavResource(r) for r in self._resources]))
+        if self._tools:
+            tool_links = [
+                NavLink(
+                    t["label"],
+                    f"{self.prefix}/tools/{t['label'].lower().replace(' ', '-')}",
+                    icon=_DEFAULT_TOOL_ICON,
+                )
+                for t in self._tools
+            ]
+            items.append(NavGroup("Tools", tool_links))
+        return items
+
+    # ------------------------------------------------------------------
+    # Resource lookup
+    # ------------------------------------------------------------------
+
+    def find_resource(self, key: str) -> type | None:
+        """Find a registered AdminResource class by its slug."""
+        for cls in self._resources:
+            if cls.slug() == key:
+                return cls
+        return None
+
+    # ------------------------------------------------------------------
+    # Route registration
+    # ------------------------------------------------------------------
+
+    def register_to(self, router: Any) -> None:
+        """Register all admin routes under self.prefix with AdminGate middleware."""
+        from hunt.admin.controllers import action as action_ctrl
+        from hunt.admin.controllers import dashboard as dash_ctrl
+        from hunt.admin.controllers import resource as res_ctrl
+        from hunt.admin.controllers import search as search_ctrl
+        from hunt.admin.middleware.gate import AdminGate
+
+        with router.group(prefix=self.prefix, middleware=[AdminGate]):
+            # Dashboard
+            router.get("/", dash_ctrl.index)
+
+            # Resource CRUD
+            router.get("/resources/{resource_key}", res_ctrl.index)
+            router.get("/resources/{resource_key}/create", res_ctrl.create)
+            router.post("/resources/{resource_key}", res_ctrl.store)
+            router.get("/resources/{resource_key}/{id}", res_ctrl.show)
+            router.get("/resources/{resource_key}/{id}/edit", res_ctrl.edit)
+            # Use POST with hidden _method field for update/delete (HTML form compat)
+            router.post("/resources/{resource_key}/{id}", _method_router)
+            router.post("/resources/{resource_key}/{id}/delete", res_ctrl.destroy)
+
+            # Actions
+            router.post("/resources/{resource_key}/actions/{action_slug}", action_ctrl.run)
+
+            # Global search
+            router.get("/search", search_ctrl.index)
+
+    # ------------------------------------------------------------------
+    # Rendering
+    # ------------------------------------------------------------------
+
+    def _render(self, template_name: str, context: dict, status: int = 200) -> Response:
+        env = _get_env()
+        template = env.get_template(template_name)
+        html = template.render(**context)
+        return Response(html, status=status)
+
+    def _base_context(self, request: Any) -> dict:
+        from hunt.auth.manager import Auth
+
+        store = getattr(request, "_session", None)
+        flash: dict[str, Any] = {}
+        if store is not None:
+            flash = store.all_flash()
+
+        auth_user = None
+        try:
+            auth_user = Auth.user()
+        except Exception:
+            pass
+
+        csrf_token = ""
+        if store is not None:
+            try:
+                csrf_token = store.csrf_token()
+            except Exception:
+                pass
+
+        return {
+            "admin": self,
+            "request": request,
+            "resources": self._resources,
+            "nav": self._build_nav(),
+            "prefix": self.prefix,
+            "flash": flash,
+            "errors": flash.get("_errors", {}),
+            "old": flash.get("_old_input", {}),
+            "auth_user": auth_user,
+            "brand_name": self.brand_name,
+            "tools": self._tools,
+            "csrf_token": csrf_token,
+        }
+
+
+def _method_router(request: Any, resource_key: str, id: str) -> Any:
+    """
+    Dispatch POST /resources/{key}/{id} to update or destroy based on _method field.
+
+    HTML forms only support GET/POST. A hidden `_method` field with value "PUT",
+    "PATCH", or "DELETE" signals the intended semantic method.
+    """
+    from hunt.admin.controllers import resource as res_ctrl
+
+    method_override = (request.input("_method") or "").upper()
+    if method_override in ("PUT", "PATCH"):
+        return res_ctrl.update(request, resource_key, id)
+    if method_override == "DELETE":
+        return res_ctrl.destroy(request, resource_key, id)
+    # Default to update if no override (plain POST to /{id})
+    return res_ctrl.update(request, resource_key, id)
+
+
+# Module-level singleton
+Admin = _Admin()

hunt/admin/console/make_admin_resource.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import click
+
+from hunt.support.str import Str
+
+_CLASS_RE = re.compile(r"^class ([A-Za-z_][A-Za-z0-9_]*)\b", re.MULTILINE)
+
+
+@click.command("make:admin-resource")
+@click.argument("model")
+def make_admin_resource_command(model: str) -> None:
+    """Generate a stub AdminResource for MODEL (a filename in app/models/)."""
+
+    model_slug = Str.snake(model.removesuffix(".py")).lower()
+    model_file = Path.cwd() / "app" / "models" / f"{model_slug}.py"
+
+    if not model_file.exists():
+        raise click.ClickException(
+            f"Model file not found: app/models/{model_slug}.py\n"
+            f"  Create it first with: hunt make:model {Str.pascal(model_slug)}"
+        )
+
+    # Read the class name directly from the file
+    model_source = model_file.read_text()
+    match = _CLASS_RE.search(model_source)
+    if not match:
+        raise click.ClickException(f"No class definition found in app/models/{model_slug}.py")
+    model_class = match.group(1)
+
+    class_name = f"{model_class}Resource"
+    snake_name = Str.snake(class_name)
+
+    # Check not already registered
+    routes_file = Path.cwd() / "routes" / "admin.py"
+    if routes_file.exists() and f"Admin.resource({class_name})" in routes_file.read_text():
+        raise click.ClickException(f"{class_name} is already registered in routes/admin.py")
+
+    target_dir = Path.cwd() / "app" / "admin"
+    target_dir.mkdir(parents=True, exist_ok=True)
+
+    file_path = target_dir / f"{snake_name}.py"
+    if file_path.exists():
+        raise click.ClickException(f"File already exists: app/admin/{snake_name}.py")
+
+    content = (
+        "from hunt.admin import AdminResource\n"
+        "from hunt.admin.fields import Text, Number, DateTime\n"
+        f"from app.models.{model_slug} import {model_class}\n"
+        "\n\n"
+        f"class {class_name}(AdminResource):\n"
+        f"    model = {model_class}\n"
+        f'    label = "{model_class}"\n'
+        '    search_columns = ["id"]\n'
+        '    default_order = ("id", "desc")\n'
+        "    per_page = 15\n"
+        "\n"
+        "    def fields(self):\n"
+        "        return [\n"
+        '            Text("Id", attribute="id").sortable().readonly(),\n'
+        "            # TODO: add your fields here\n"
+        '            DateTime("Created At", attribute="created_at").sortable().hide_from_forms(),\n'
+        '            DateTime("Updated At", attribute="updated_at").sortable().hide_from_forms(),\n'
+        "        ]\n"
+        "\n"
+        "    def filters(self):\n"
+        "        return []\n"
+        "\n"
+        "    def actions(self):\n"
+        "        return []\n"
+        "\n"
+        "    def metrics(self):\n"
+        "        return []\n"
+    )
+
+    file_path.write_text(content)
+    click.echo(f"  AdminResource created: app/admin/{snake_name}.py")
+
+    _inject_into_routes(model_slug, class_name)
+
+
+def _inject_into_routes(model_slug: str, class_name: str) -> None:
+    routes_file = Path.cwd() / "routes" / "admin.py"
+    if not routes_file.exists():
+        return
+
+    source = routes_file.read_text()
+
+    import_stmt = f"from app.admin.{Str.snake(class_name)} import {class_name}"
+    register_stmt = f"Admin.resource({class_name})"
+
+    if import_stmt in source:
+        return
+
+    lines = source.splitlines()
+
+    # Insert import after the last `from app.admin.*` line, falling back to
+    # the last import line in the file.
+    last_app_admin_import = -1
+    last_import = -1
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+        if stripped.startswith("from app.admin."):
+            last_app_admin_import = i
+        if stripped.startswith(("from ", "import ")):
+            last_import = i
+
+    import_insert_at = last_app_admin_import if last_app_admin_import >= 0 else last_import
+    if import_insert_at >= 0:
+        lines.insert(import_insert_at + 1, import_stmt)
+    else:
+        lines.insert(0, import_stmt)
+
+    # Insert Admin.resource() after the last existing call, or before the
+    # first non-import statement (Admin.dashboard, def register, etc.).
+    last_resource_call = -1
+    first_non_resource_stmt = -1
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+        if stripped.startswith("Admin.resource("):
+            last_resource_call = i
+        elif (
+            first_non_resource_stmt < 0
+            and stripped
+            and not stripped.startswith(("from ", "import ", "#", "Admin.resource("))
+        ):
+            first_non_resource_stmt = i
+
+    if last_resource_call >= 0:
+        lines.insert(last_resource_call + 1, register_stmt)
+    elif first_non_resource_stmt >= 0:
+        lines.insert(first_non_resource_stmt, register_stmt)
+    else:
+        lines.append(register_stmt)
+
+    routes_file.write_text("\n".join(lines) + "\n")
+    click.echo("  Registered in:        routes/admin.py")

hunt/admin/controllers/action.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import json
+
+from hunt.http.request import Request
+from hunt.http.response import HttpException, RedirectResponse, Response
+
+
+def run(request: Request, resource_key: str, action_slug: str) -> Response:
+    from hunt.admin.application import Admin
+
+    resource_cls = Admin.find_resource(resource_key)
+    if resource_cls is None:
+        raise HttpException(404, "Resource not found.")
+    resource = resource_cls()
+
+    # Require at least update permission to run any action.
+    if not resource.can_update(request):
+        raise HttpException(403, "Forbidden.")
+
+    # Resolve selected IDs — accept comma-separated string or JSON array.
+    raw_ids = request.input("ids", "")
+    if isinstance(raw_ids, list):
+        candidate_ids = [str(i) for i in raw_ids]
+    elif raw_ids:
+        raw_str = str(raw_ids).strip()
+        if raw_str.startswith("["):
+            try:
+                candidate_ids = [str(i) for i in json.loads(raw_str)]
+            except (json.JSONDecodeError, ValueError):
+                candidate_ids = [s.strip() for s in raw_str.split(",") if s.strip()]
+        else:
+            candidate_ids = [s.strip() for s in raw_str.split(",") if s.strip()]
+    else:
+        candidate_ids = []
+
+    # Find the action by slug.
+    matched_action = None
+    for action in resource.actions():
+        if action.slug() == action_slug:
+            matched_action = action
+            break
+
+    if matched_action is None:
+        raise HttpException(404, "Action not found.")
+
+    # Scope the IDs through index_query so that users cannot act on records
+    # outside the scope they can see (prevents IDOR).
+    try:
+        accessible = {str(item._attributes.get("id")) for item in resource.index_query(request).get()}
+    except Exception:
+        accessible = set()
+
+    safe_ids = [i for i in candidate_ids if i in accessible]
+
+    # Load model instances for the verified IDs.
+    instances = []
+    for record_id in safe_ids:
+        try:
+            instance = resource.model.find(record_id)
+            if instance is not None:
+                instances.append(instance)
+        except Exception:
+            pass
+
+    try:
+        result = matched_action.handle(request, instances)
+    except Exception:
+        store = getattr(request, "_session", None)
+        if store is not None:
+            store.flash("admin_error", "The action could not be completed. Please try again.")
+        return RedirectResponse(f"{Admin.prefix}/resources/{resource_key}")
+
+    store = getattr(request, "_session", None)
+
+    if result.type == "redirect":
+        # Reject external redirects — only allow relative paths.
+        url = result.url or ""
+        if url.startswith(("http://", "https://", "//")):
+            url = f"{Admin.prefix}/resources/{resource_key}"
+        return RedirectResponse(url)
+
+    if store is not None:
+        flash_key = "admin_success" if result.message_type == "success" else "admin_error"
+        store.flash(flash_key, result.text)
+
+    return RedirectResponse(f"{Admin.prefix}/resources/{resource_key}")

hunt/admin/controllers/dashboard.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from hunt.http.request import Request
+from hunt.http.response import Response
+
+
+def index(request: Request) -> Response:
+    from hunt.admin.application import Admin
+
+    ctx = Admin._base_context(request)
+    metrics = []
+    for card in Admin._dashboard_cards:
+        try:
+            data = card.calculate()
+            data["metric_type"] = card.metric_type
+            metrics.append(data)
+        except Exception:
+            pass
+    ctx["metrics"] = metrics
+    ctx["title"] = "Dashboard"
+    return Admin._render("admin/dashboard.html", ctx)