refactor(web): migrate controllers to explicit FromPath markers (#107)

Migrate controllers.py route handlers from inferred/implicit path parameters to explicit FromPath type annotations to address Litestar deprecation warnings.

Author: cofin

.gitignore

@@ -171,4 +171,11 @@ CLAUDE.md
 GEMINI.md
 # Flow specification files (local-only)
 .agent/
+.agents/
 .geminiignore
+
+# Beads / Dolt files (added by bd init)
+.dolt/
+*.db
+.beads-credential-key
+opencode.json

.pre-commit-config.yaml

@@ -17,7 +17,7 @@ repos:
       - id: mixed-line-ending
       - id: trailing-whitespace
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: "v0.15.4"
+    rev: "v0.15.15"
     hooks:
       # Run the linter.
     - id: ruff
@@ -27,7 +27,7 @@ repos:
     - id: ruff-format
       types_or: [ python, pyi ]
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.4.1
+    rev: v2.4.2
     hooks:
       - id: codespell
         exclude: "uv.lock|package.json|package-lock.json"

litestar_saq/__metadata__.py

@@ -1,4 +1,5 @@
 """Metadata for the Project."""
+# pyright: reportUnknownVariableType=false
 
 from __future__ import annotations
 

litestar_saq/config.py

@@ -519,6 +519,6 @@ def _has_otel_plugin(app: "Litestar") -> bool:
             OpenTelemetryPlugin,  # pyright: ignore[reportAttributeAccessIssue,reportMissingImports,reportUnknownVariableType]
         )
 
-        return app.plugins.get(OpenTelemetryPlugin) is not None  # pyright: ignore[reportUnknownArgumentType]
+        return bool(app.plugins.get(OpenTelemetryPlugin))
     except ImportError:
         return False

litestar_saq/controllers.py

@@ -3,6 +3,7 @@
 from typing import TYPE_CHECKING, Any, Optional, cast
 
 from litestar.exceptions import NotFoundException
+from litestar.params import FromPath
 
 if TYPE_CHECKING:
     from litestar import Controller
@@ -131,7 +132,7 @@ async def queue_list(self, task_queues: "TaskQueues") -> "dict[str, list[QueueIn
             summary="Queue Detail",
             description="List queue details.",
         )
-        async def queue_detail(self, task_queues: "TaskQueues", queue_id: str) -> "dict[str, QueueInfo]":
+        async def queue_detail(self, task_queues: "TaskQueues", queue_id: FromPath[str]) -> "dict[str, QueueInfo]":
             """Get queue information.
 
             Args:
@@ -157,7 +158,7 @@ async def queue_detail(self, task_queues: "TaskQueues", queue_id: str) -> "dict[
             description="List job details.",
         )
         async def job_detail(
-            self, task_queues: "TaskQueues", queue_id: str, job_id: str
+            self, task_queues: "TaskQueues", queue_id: FromPath[str], job_id: FromPath[str]
         ) -> "dict[str, dict[str, Any]]":
             """Get job information.
 
@@ -191,7 +192,9 @@ async def job_detail(
             description="Retry a failed job..",
             status_code=HTTP_202_ACCEPTED,
         )
-        async def job_retry(self, task_queues: "TaskQueues", queue_id: str, job_id: str) -> "dict[str, str]":
+        async def job_retry(
+            self, task_queues: "TaskQueues", queue_id: FromPath[str], job_id: FromPath[str]
+        ) -> "dict[str, str]":
             """Retry job.
 
             Args:
@@ -217,7 +220,9 @@ async def job_retry(self, task_queues: "TaskQueues", queue_id: str, job_id: str)
             description="Abort active job.",
             status_code=HTTP_202_ACCEPTED,
         )
-        async def job_abort(self, task_queues: "TaskQueues", queue_id: str, job_id: str) -> "dict[str, str]":
+        async def job_abort(
+            self, task_queues: "TaskQueues", queue_id: FromPath[str], job_id: FromPath[str]
+        ) -> "dict[str, str]":
             """Abort job.
 
             Args:
@@ -280,8 +285,8 @@ async def health(self, task_queues: "TaskQueues") -> Response[str]:
         )
         async def index(
             self,
-            queue_id: Optional[str] = None,
-            job_id: Optional[str] = None,
+            queue_id: FromPath[Optional[str]] = None,
+            job_id: FromPath[Optional[str]] = None,
         ) -> str:
             return html_template
 

litestar_saq/plugin.py

@@ -169,7 +169,7 @@ def get_queues(self) -> "TaskQueues":
     def get_queue(self, name: str) -> "Queue":
         return self.get_queues().get(name)
 
-    @contextmanager
+    @contextmanager  # pyright: ignore[reportDeprecated]
     def server_lifespan(self, app: "Litestar") -> "Iterator[None]":
         import multiprocessing
         import platform