labtasker-client 2.3.0__tar.gz → 2.4.1__tar.gz

{labtasker_client-2.3.0 → labtasker_client-2.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: labtasker-client
-Version: 2.3.0
+Version: 2.4.1
 Summary: A small task queue for parallel model inference and evaluation
 Project-URL: Homepage, https://github.com/luocfprime/labtasker
 Project-URL: Repository, https://github.com/luocfprime/labtasker.git
@@ -8,10 +8,12 @@ Author-email: lcf <luocfprime@gmail.com>
 License-Expression: Apache-2.0
 License-File: LICENSE
 Requires-Python: >=3.10
-Requires-Dist: httpx[socks]<1,>=0.25.2
+Requires-Dist: httpx<1,>=0.25.2
 Requires-Dist: packaging>=21.3
 Requires-Dist: pydantic<3,>=2.12; python_version >= '3.14'
 Requires-Dist: pydantic<3,>=2.5.3; python_version < '3.13'
 Requires-Dist: pydantic<3,>=2.9; python_version >= '3.13' and python_version < '3.14'
 Requires-Dist: tomli>=2.0.1; python_version < '3.11'
 Requires-Dist: typer<1,>=0.19
+Provides-Extra: socks
+Requires-Dist: socksio==1.*; extra == 'socks'

{labtasker_client-2.3.0 → labtasker_client-2.4.1}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "hatchling.build"
 
 [project]
 name = "labtasker-client"
-version = "2.3.0"
+version = "2.4.1"
 description = "A small task queue for parallel model inference and evaluation"
 requires-python = ">=3.10"
 license = "Apache-2.0"
 license-files = ["LICENSE"]
 authors = [{ name = "lcf", email = "luocfprime@gmail.com" }]
 dependencies = [
-  "httpx[socks]>=0.25.2,<1",
+  "httpx>=0.25.2,<1",
   "packaging>=21.3",
   "pydantic>=2.5.3,<3; python_version < '3.13'",
   "pydantic>=2.9,<3; python_version >= '3.13' and python_version < '3.14'",
@@ -20,6 +20,9 @@ dependencies = [
   "typer>=0.19,<1",
 ]
 
+[project.optional-dependencies]
+socks = ["socksio==1.*"]
+
 [project.urls]
 Homepage = "https://github.com/luocfprime/labtasker"
 Repository = "https://github.com/luocfprime/labtasker.git"

{labtasker_client-2.3.0 → labtasker_client-2.4.1}/src/labtasker/__init__.py

@@ -30,6 +30,7 @@ from labtasker.errors import (
 from labtasker.execution import (
     cancellation_requested,
     finish,
+    report_progress,
     set_force_stop_timeout,
     task_info,
 )
@@ -48,7 +49,7 @@ from labtasker.models import (
 from labtasker.types import JSONValue, TaskOrderField, TaskStatus, TaskUpdate
 from labtasker.worker import loop
 
-__version__ = "2.3.0"
+__version__ = "2.4.1"
 
 __all__ = [
     "APIError",
@@ -87,6 +88,7 @@ __all__ = [
     "list_tasks",
     "list_workers",
     "loop",
+    "report_progress",
     "requeue_task",
     "set_force_stop_timeout",
     "submit_task",

{labtasker_client-2.3.0 → labtasker_client-2.4.1}/src/labtasker/cli.py

@@ -15,6 +15,7 @@ from labtasker.command_template import TemplateSyntaxError
 from labtasker.command_worker import run_command_worker
 from labtasker.config import resolve_config
 from labtasker.errors import LabtaskerError
+from labtasker.execution import report_progress as report_current_progress
 from labtasker.types import TaskOrderField, TaskStatus, TaskUpdate
 from labtasker.validation import RequestValidationError, validate_grouping, validate_json_object
 
@@ -169,6 +170,29 @@ def worker_loop(
         raise typer.Exit(1) from error
 
 
+@app.command("progress")
+def progress_report(
+    data: Annotated[
+        str,
+        typer.Option(help="Latest progress as one strict JSON object."),
+    ],
+) -> None:
+    """Replace the current Task run's progress snapshot.
+
+    This command is available inside a command launched by ``labtasker loop``.
+    It prints whether the best-effort report was accepted; transport failures
+    and confirmed revocation return ``reported: false`` without failing the
+    command workload.
+    """
+    try:
+        progress = _json_object(data, option="--data")
+        reported = _invoke(lambda: report_current_progress(progress))
+    except RuntimeError as error:
+        typer.echo(str(error), err=True)
+        raise typer.Exit(1) from error
+    _write_json({"reported": reported})
+
+
 @task_app.command("submit")
 def task_submit(
     args: Annotated[

{labtasker_client-2.3.0 → labtasker_client-2.4.1}/src/labtasker/client.py

@@ -589,6 +589,24 @@ class Client:
             parser=lambda response: _parse_none(response, {204}),
         )
 
+    def _report_progress(
+        self,
+        *,
+        task_id: str,
+        run_id: str,
+        progress: dict[str, JSONValue],
+        queue: str | None = None,
+    ) -> None:
+        normalized = validate_json_object(progress, field="progress")
+        self._run_action(
+            "progress",
+            task_id=task_id,
+            run_id=run_id,
+            queue=queue,
+            body={"progress": normalized},
+            parser=lambda response: _parse_none(response, {204}),
+        )
+
     def _fail(
         self,
         *,

{labtasker_client-2.3.0 → labtasker_client-2.4.1}/src/labtasker/execution.py

@@ -17,6 +17,7 @@ from labtasker.types import JSONValue
 from labtasker.validation import RequestValidationError, validate_json_object
 
 CompletionReporter = Callable[[dict[str, JSONValue]], bool]
+ProgressReporter = Callable[[dict[str, JSONValue]], bool]
 ContextKind = Literal["python", "command"]
 
 
@@ -128,12 +129,14 @@ class ExecutionContext:
         journal: LocalRunJournal,
         reporter: CompletionReporter,
         control: RunControl | None,
+        progress_reporter: ProgressReporter | None = None,
     ) -> None:
         self.info = info
         self.kind = kind
         self.journal = journal
         self.reporter = reporter
         self.control = control
+        self.progress_reporter = progress_reporter
         self._lock = threading.Lock()
         self._finish_started = False
         self._finished = False
@@ -161,6 +164,17 @@ class ExecutionContext:
             self.control.complete()
         _best_effort_journal(self.journal.acknowledged)
 
+    def report_progress(self, progress: dict[str, JSONValue]) -> bool:
+        with self._lock:
+            if self._finished:
+                raise RuntimeError("The current run has already completed.")
+            if self.control is not None and not self.control.active:
+                return False
+            reporter = self.progress_reporter
+        if reporter is None:
+            raise RuntimeError("Progress reporting is unavailable for this execution.")
+        return reporter(progress)
+
 
 _CONTEXT_LOCK = threading.RLock()
 _ACTIVE_CONTEXT: ExecutionContext | None = None
@@ -212,6 +226,20 @@ def finish(
     context.finish(normalized)
 
 
+def report_progress(
+    progress: dict[str, JSONValue],
+    *,
+    skip_if_no_labtasker: bool = False,
+) -> bool:
+    context = _get_context()
+    if context is None:
+        if skip_if_no_labtasker:
+            return False
+        raise RuntimeError("No active Labtasker Task execution is available.")
+    normalized = validate_json_object(progress, field="progress")
+    return context.report_progress(normalized)
+
+
 def cancellation_requested() -> bool:
     context = _require_python_context()
     if context.finished or context.control is None:
@@ -340,12 +368,24 @@ def _load_environment_context() -> ExecutionContext | None:
                 result=result,
             )
 
+        def progress_reporter(progress: dict[str, JSONValue]) -> bool:
+            from labtasker.worker import report_progress_once
+
+            return report_progress_once(
+                client,
+                queue=values["queue"] or "",
+                task_id=values["task_id"] or "",
+                run_id=run_id,
+                progress=progress,
+            )
+
         _ENV_CONTEXT = ExecutionContext(
             info=info,
             kind="command",
             journal=journal,
             reporter=report,
             control=None,
+            progress_reporter=progress_reporter,
         )
         return _ENV_CONTEXT
 

{labtasker_client-2.3.0 → labtasker_client-2.4.1}/src/labtasker/models.py

@@ -68,6 +68,9 @@ class Task(ResponseModel):
     max_attempts: int
     routes: list[str]
     result: dict[str, JSONValue]
+    progress: dict[str, JSONValue] | None = None
+    progress_updated_at: datetime | None = None
+    progress_attempt: int | None = None
     last_error: LastError | None
     last_route: str | None
     created_at: datetime
@@ -90,9 +93,15 @@ class Task(ResponseModel):
     def validate_name(cls, value: str | None) -> str | None:
         return validate_task_name(value)
 
-    @field_validator("args", "metadata", "result")
+    @field_validator("args", "metadata", "result", "progress")
     @classmethod
-    def validate_objects(cls, value: dict[str, JSONValue], info: object) -> dict[str, JSONValue]:
+    def validate_objects(
+        cls,
+        value: dict[str, JSONValue] | None,
+        info: object,
+    ) -> dict[str, JSONValue] | None:
+        if value is None:
+            return None
         return validate_json_object(value, field=getattr(info, "field_name", "task"))
 
     @field_validator("priority", "attempt")
@@ -100,6 +109,23 @@ class Task(ResponseModel):
     def validate_numbers(cls, value: int, info: object) -> int:
         return validate_int64(value, field=getattr(info, "field_name", "task"))
 
+    @field_validator("progress_attempt")
+    @classmethod
+    def validate_progress_attempt(cls, value: int | None) -> int | None:
+        if value is None:
+            return None
+        value = validate_int64(value, field="progress_attempt")
+        if value < 0:
+            raise ValueError("progress_attempt must be non-negative")
+        return value
+
+    @model_validator(mode="after")
+    def validate_progress_fields(self) -> Task:
+        fields = (self.progress, self.progress_updated_at, self.progress_attempt)
+        if any(value is None for value in fields) and any(value is not None for value in fields):
+            raise ValueError("progress fields must be all null or all present")
+        return self
+
     @field_validator("max_attempts")
     @classmethod
     def validate_max_attempts(cls, value: int) -> int:
@@ -118,7 +144,13 @@ class Task(ResponseModel):
     def validate_last_route(cls, value: str | None) -> str | None:
         return None if value is None else validate_identifier(value, field="last_route")
 
-    @field_validator("created_at", "updated_at", "started_at", "finished_at")
+    @field_validator(
+        "created_at",
+        "updated_at",
+        "started_at",
+        "finished_at",
+        "progress_updated_at",
+    )
     @classmethod
     def validate_times(cls, value: datetime | None) -> datetime | None:
         return None if value is None else _utc_datetime(value)

{labtasker_client-2.3.0 → labtasker_client-2.4.1}/src/labtasker/worker.py

@@ -19,6 +19,7 @@ from labtasker.errors import (
     APIError,
     ConfigError,
     FatalWorkerError,
+    LabtaskerError,
     TransientError,
     TransportError,
 )
@@ -260,6 +261,16 @@ def _run_python_claim(
             control.revoke("stale_run")
         return accepted
 
+    def progress_reporter(progress: dict[str, JSONValue]) -> bool:
+        return report_progress_once(
+            client,
+            queue=queue,
+            task_id=claim.task.id,
+            run_id=claim.run_id,
+            progress=progress,
+            control=control,
+        )
+
     info = TaskInfo(
         **claim.task.model_dump(),
         run_id=claim.run_id,
@@ -271,6 +282,7 @@ def _run_python_claim(
         journal=journal,
         reporter=report_complete,
         control=control,
+        progress_reporter=progress_reporter,
     )
     heartbeat = Heartbeat(
         client,
@@ -358,6 +370,39 @@ def report_complete_until_resolved(
     )
 
 
+def report_progress_once(
+    client: Client,
+    *,
+    queue: str,
+    task_id: str,
+    run_id: str,
+    progress: dict[str, JSONValue],
+    control: RunControl | None = None,
+) -> bool:
+    try:
+        client._report_progress(
+            task_id=task_id,
+            run_id=run_id,
+            progress=progress,
+            queue=queue,
+        )
+    except APIError as error:
+        if error.code == "run_finalized" and error.details.get("action") == "complete":
+            if control is not None:
+                control.complete()
+        elif error.code in {"run_finalized", "stale_run"} and control is not None:
+            control.revoke(str(error.details.get("action", error.code)))
+        logger.warning("Progress report rejected; continuing Task: %s", error.message)
+        return False
+    except TransportError as error:
+        logger.warning("Progress report transport error; continuing Task: %s", error.message)
+        return False
+    except LabtaskerError as error:
+        logger.warning("Progress report failed; continuing Task: %s", error.message)
+        return False
+    return True
+
+
 def _report_complete(
     client: Client,
     journal: LocalRunJournal,