labtasker-client 2.0.0__py3-none-any.whl

labtasker/__init__.py

@@ -0,0 +1,77 @@
+"""Public package for the Labtasker v2 client and Worker runtime."""
+
+from labtasker.api import (
+    cancel_task,
+    count_tasks,
+    create_queue,
+    delete_queue,
+    delete_task,
+    get_task,
+    list_queues,
+    list_tasks,
+    requeue_task,
+    submit_task,
+    update_task,
+    update_tasks,
+)
+from labtasker.binding import TaskArg
+from labtasker.client import Client
+from labtasker.errors import (
+    APIError,
+    ConfigError,
+    FatalWorkerError,
+    LabtaskerError,
+    TaskError,
+    TransientError,
+    TransportError,
+)
+from labtasker.execution import (
+    cancellation_requested,
+    finish,
+    set_force_stop_timeout,
+    task_info,
+)
+from labtasker.models import BulkUpdateResult, LastError, Queue, Task, TaskInfo, TaskPage
+from labtasker.types import JSONValue, TaskOrderField, TaskStatus, TaskUpdate
+from labtasker.worker import loop
+
+__version__ = "2.0.0"
+
+__all__ = [
+    "APIError",
+    "BulkUpdateResult",
+    "Client",
+    "ConfigError",
+    "FatalWorkerError",
+    "JSONValue",
+    "LabtaskerError",
+    "LastError",
+    "Queue",
+    "Task",
+    "TaskArg",
+    "TaskError",
+    "TaskInfo",
+    "TaskOrderField",
+    "TaskPage",
+    "TaskStatus",
+    "TaskUpdate",
+    "TransientError",
+    "TransportError",
+    "cancel_task",
+    "cancellation_requested",
+    "count_tasks",
+    "create_queue",
+    "delete_queue",
+    "delete_task",
+    "finish",
+    "get_task",
+    "list_queues",
+    "list_tasks",
+    "loop",
+    "requeue_task",
+    "set_force_stop_timeout",
+    "submit_task",
+    "task_info",
+    "update_task",
+    "update_tasks",
+]

labtasker/__main__.py

@@ -0,0 +1,3 @@
+from labtasker.cli import app
+
+app()

labtasker/api.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from threading import Lock
+
+from labtasker.client import Client
+from labtasker.models import BulkUpdateResult, Queue, Task, TaskPage
+from labtasker.types import JSONValue, TaskOrderField, TaskStatus, TaskUpdate
+
+_default_client: Client | None = None
+_default_client_lock = Lock()
+
+
+def submit_task(
+    args: dict[str, JSONValue] | None = None,
+    *,
+    name: str | None = None,
+    metadata: dict[str, JSONValue] | None = None,
+    priority: int = 0,
+    max_attempts: int = 3,
+    routes: list[str] | None = None,
+    task_id: str | None = None,
+    queue: str | None = None,
+) -> Task:
+    return _client().submit_task(
+        args,
+        name=name,
+        metadata=metadata,
+        priority=priority,
+        max_attempts=max_attempts,
+        routes=routes,
+        task_id=task_id,
+        queue=queue,
+    )
+
+
+def get_task(task_id: str, *, queue: str | None = None) -> Task:
+    return _client().get_task(task_id, queue=queue)
+
+
+def list_tasks(
+    *,
+    status: TaskStatus | None = None,
+    name: str | None = None,
+    filter: str | None = None,
+    order_by: TaskOrderField = "created_at",
+    descending: bool = True,
+    limit: int = 100,
+    cursor: str | None = None,
+    queue: str | None = None,
+) -> TaskPage:
+    return _client().list_tasks(
+        status=status,
+        name=name,
+        filter=filter,
+        order_by=order_by,
+        descending=descending,
+        limit=limit,
+        cursor=cursor,
+        queue=queue,
+    )
+
+
+def count_tasks(
+    *,
+    status: TaskStatus | None = None,
+    name: str | None = None,
+    filter: str | None = None,
+    queue: str | None = None,
+) -> int:
+    return _client().count_tasks(status=status, name=name, filter=filter, queue=queue)
+
+
+def update_task(
+    task_id: str,
+    changes: TaskUpdate,
+    *,
+    queue: str | None = None,
+) -> Task:
+    return _client().update_task(task_id, changes, queue=queue)
+
+
+def update_tasks(
+    *,
+    filter: str,
+    changes: TaskUpdate,
+    queue: str | None = None,
+) -> BulkUpdateResult:
+    return _client().update_tasks(filter=filter, changes=changes, queue=queue)
+
+
+def cancel_task(task_id: str, *, queue: str | None = None) -> Task:
+    return _client().cancel_task(task_id, queue=queue)
+
+
+def requeue_task(task_id: str, *, queue: str | None = None) -> Task:
+    return _client().requeue_task(task_id, queue=queue)
+
+
+def delete_task(task_id: str, *, queue: str | None = None) -> None:
+    _client().delete_task(task_id, queue=queue)
+
+
+def create_queue(name: str) -> Queue:
+    return _client().create_queue(name)
+
+
+def list_queues() -> list[Queue]:
+    return _client().list_queues()
+
+
+def delete_queue(name: str, *, cascade: bool = False) -> None:
+    _client().delete_queue(name, cascade=cascade)
+
+
+def _client() -> Client:
+    global _default_client
+    if _default_client is not None:
+        return _default_client
+    with _default_client_lock:
+        if _default_client is None:
+            _default_client = Client()
+        return _default_client

labtasker/binding.py

@@ -0,0 +1,184 @@
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, TypeVar, get_type_hints, overload
+
+from pydantic import TypeAdapter, ValidationError
+
+from labtasker.paths import PathError, parse_path, select_path
+from labtasker.types import JSONValue
+
+T = TypeVar("T")
+_MISSING = object()
+
+
+@dataclass(frozen=True, slots=True)
+class _TaskArgMarker:
+    default: object
+    path: str | None
+    resolver: Callable[[Any], Any] | None
+
+
+@overload
+def TaskArg(
+    *,
+    default: T,
+    path: str | None = None,
+    resolver: None = None,
+) -> T: ...
+
+
+@overload
+def TaskArg(
+    *,
+    default: object = _MISSING,
+    path: str | None = None,
+    resolver: Callable[[Any], T],
+) -> T: ...
+
+
+@overload
+def TaskArg(
+    *,
+    default: object = _MISSING,
+    path: str | None = None,
+    resolver: None = None,
+) -> Any: ...
+
+
+def TaskArg(
+    *,
+    default: object = _MISSING,
+    path: str | None = None,
+    resolver: Callable[[Any], Any] | None = None,
+) -> Any:
+    """Mark one decorated Worker parameter as coming from Task args."""
+    return _TaskArgMarker(default=default, path=path, resolver=resolver)
+
+
+class BindingError(ValueError):
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class _Injection:
+    name: str
+    path: tuple[str, ...]
+    default: object
+    resolver: Callable[[Any], Any] | None
+    adapter: TypeAdapter[Any] | None
+
+    def resolve(self, args: dict[str, JSONValue]) -> Any:
+        try:
+            value = select_path(args, self.path)
+        except PathError as error:
+            if self.default is _MISSING:
+                raise BindingError(f"TaskArg {self.name!r}: {error}") from error
+            value = self.default
+        if self.resolver is not None:
+            try:
+                value = self.resolver(value)
+            except Exception as error:
+                raise BindingError(f"TaskArg {self.name!r} resolver failed: {error}") from error
+        if self.adapter is not None:
+            try:
+                value = self.adapter.validate_python(value, strict=True)
+            except ValidationError as error:
+                message = f"TaskArg {self.name!r} failed strict validation: {error}"
+                raise BindingError(message) from error
+        return value
+
+
+@dataclass(frozen=True, slots=True)
+class CompiledBinding:
+    function: Callable[..., Any]
+    signature: inspect.Signature
+    injections: tuple[_Injection, ...]
+
+    def validate_invocation(self, args: tuple[object, ...], kwargs: dict[str, object]) -> None:
+        bound = self.signature.bind(*args, **kwargs)
+        supplied = {injection.name for injection in self.injections} & bound.arguments.keys()
+        if supplied:
+            names = ", ".join(sorted(supplied))
+            raise TypeError(
+                f"TaskArg parameters are supplied by Labtasker and cannot be passed: {names}"
+            )
+
+    def invoke(
+        self,
+        task_args: dict[str, JSONValue],
+        startup_args: tuple[object, ...],
+        startup_kwargs: dict[str, object],
+    ) -> Any:
+        bound = self.signature.bind(*startup_args, **startup_kwargs)
+        for injection in self.injections:
+            bound.arguments[injection.name] = injection.resolve(task_args)
+        return self.function(*bound.args, **bound.kwargs)
+
+
+def compile_binding(function: Callable[..., Any]) -> CompiledBinding:
+    if inspect.iscoroutinefunction(function):
+        raise TypeError("Labtasker v2 Worker handlers must be synchronous functions.")
+    signature = inspect.signature(function)
+    try:
+        hints = get_type_hints(function, include_extras=True)
+    except Exception as error:
+        raise TypeError(f"Could not resolve Worker annotations: {error}") from error
+    injections: list[_Injection] = []
+    for parameter in signature.parameters.values():
+        marker = parameter.default
+        if not isinstance(marker, _TaskArgMarker):
+            continue
+        if parameter.kind in {
+            inspect.Parameter.POSITIONAL_ONLY,
+            inspect.Parameter.VAR_POSITIONAL,
+            inspect.Parameter.VAR_KEYWORD,
+        }:
+            raise TypeError(f"TaskArg parameter {parameter.name!r} must accept a keyword value.")
+        if marker.path is not None and not isinstance(marker.path, str):
+            raise TypeError(f"TaskArg path for {parameter.name!r} must be a string or None.")
+        try:
+            path = parse_path(parameter.name if marker.path is None else marker.path)
+        except PathError as error:
+            raise TypeError(f"Invalid TaskArg path for {parameter.name!r}: {error}") from error
+        resolver = marker.resolver
+        if resolver is not None:
+            _validate_resolver(resolver, parameter.name)
+        annotation = hints.get(parameter.name, parameter.annotation)
+        adapter: TypeAdapter[Any] | None = None
+        if annotation is not inspect.Parameter.empty:
+            try:
+                adapter = TypeAdapter(annotation)
+            except Exception as error:
+                raise TypeError(
+                    f"Could not compile annotation for TaskArg {parameter.name!r}: {error}"
+                ) from error
+        injections.append(
+            _Injection(
+                name=parameter.name,
+                path=path,
+                default=marker.default,
+                resolver=resolver,
+                adapter=adapter,
+            )
+        )
+    return CompiledBinding(function=function, signature=signature, injections=tuple(injections))
+
+
+def _validate_resolver(resolver: object, name: str) -> None:
+    if not callable(resolver):
+        raise TypeError(f"TaskArg resolver for {name!r} must be callable.")
+    if inspect.iscoroutinefunction(resolver):
+        raise TypeError(f"TaskArg resolver for {name!r} must be synchronous.")
+    try:
+        signature = inspect.signature(resolver)
+    except (TypeError, ValueError) as error:
+        raise TypeError(f"Could not inspect TaskArg resolver for {name!r}.") from error
+    parameters = list(signature.parameters.values())
+    if len(parameters) != 1 or parameters[0].kind not in {
+        inspect.Parameter.POSITIONAL_ONLY,
+        inspect.Parameter.POSITIONAL_OR_KEYWORD,
+    }:
+        raise TypeError(f"TaskArg resolver for {name!r} must accept exactly one value.")