taskferry-cloudtasks 0.2.0__tar.gz → 0.3.0__tar.gz

{taskferry_cloudtasks-0.2.0 → taskferry_cloudtasks-0.3.0}/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to `taskferry-cloudtasks` are documented here.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.3.0] — 2026-09-19
+
+### Added
+
+- **Native async submit** via `CloudTasksAsyncClient`. `asubmit` creates the task
+  through the async client (injected, or built from the existing `gcp` extra),
+  skipping the worker thread, and falls back to the thread path when the SDK is
+  absent. No new dependency — the async client ships with `google-cloud-tasks`.
+
 ## [0.2.0] — 2026-07-26
 
 ### Added

{taskferry_cloudtasks-0.2.0 → taskferry_cloudtasks-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: taskferry-cloudtasks
-Version: 0.2.0
+Version: 0.3.0
 Summary: Google Cloud Tasks backend for Taskferry — push-based serverless tasks.
 Project-URL: Homepage, https://github.com/xiidigital/taskferry
 Project-URL: Documentation, https://taskferry.dev

{taskferry_cloudtasks-0.2.0 → taskferry_cloudtasks-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "taskferry-cloudtasks"
-version = "0.2.0"
+version = "0.3.0"
 description = "Google Cloud Tasks backend for Taskferry — push-based serverless tasks."
 readme = "README.md"
 requires-python = ">=3.12"

{taskferry_cloudtasks-0.2.0 → taskferry_cloudtasks-0.3.0}/src/taskferry_cloudtasks/backend.py

@@ -24,6 +24,8 @@ by accident.
 from __future__ import annotations
 
 import json
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
 from datetime import UTC, datetime
 from typing import Any
 
@@ -90,6 +92,7 @@ class CloudTasksBackend(BaseBackend):
         service_account_email: str | None = None,
         audience: str | None = None,
         client: Any = None,
+        async_client: Any = None,
         name: str = "cloudtasks",
     ) -> None:
         missing = [
@@ -110,6 +113,7 @@ class CloudTasksBackend(BaseBackend):
         self._service_account_email = service_account_email
         self._audience = audience
         self._client = client
+        self._async_client = async_client
         self._name = name
 
     @property
@@ -143,12 +147,18 @@ class CloudTasksBackend(BaseBackend):
             return str(builder(self._project, self._location, queue))
         return f"projects/{self._project}/locations/{self._location}/queues/{queue}"
 
+    def _queue_path_str(self, queue: str) -> str:
+        """Fully-qualified queue path without needing a client (async path)."""
+        return f"projects/{self._project}/locations/{self._location}/queues/{queue}"
+
     # -- submission -------------------------------------------------------------- #
-    def _submit(self, spec: ExecutionSpec) -> Execution:
-        assert isinstance(spec, TaskSpec)
+    def _queue_for(self, spec: TaskSpec) -> str:
         options = spec.options_for("cloudtasks")
-        queue = str(options.get("queue") or spec.queue or self._queue)
+        return str(options.get("queue") or spec.queue or self._queue)
 
+    def _build_task(self, spec: TaskSpec, queue_path: str) -> dict[str, Any]:
+        """The Cloud Tasks task body. Pure, shared by the sync and async paths."""
+        options = spec.options_for("cloudtasks")
         http_request: dict[str, Any] = {
             "http_method": "POST",
             "url": self._url,
@@ -175,18 +185,12 @@ class CloudTasksBackend(BaseBackend):
             # A named task is refused if the name was used recently — Cloud Tasks'
             # own, real, time-bounded deduplication. The window is Google's, not
             # ours, and this is not an exactly-once promise.
-            task["name"] = f"{self.queue_path(queue)}/tasks/{_safe_name(spec.idempotency_key)}"
-
-        try:
-            created = self._tasks().create_task(
-                request={"parent": self.queue_path(queue), "task": task}
-            )
-        except Exception as exc:
-            raise SubmissionError(
-                f"Cloud Tasks could not create a task for {spec.task!r} on queue {queue!r}: {exc}",
-                backend=self._name,
-            ) from exc
+            task["name"] = f"{queue_path}/tasks/{_safe_name(spec.idempotency_key)}"
+        return task
 
+    def _execution_from(
+        self, spec: TaskSpec, created: Any, queue_path: str, queue: str
+    ) -> Execution:
         external_id = getattr(created, "name", None)
         return Execution(
             id=new_execution_id(ExecutionKind.TASK),
@@ -203,12 +207,64 @@ class CloudTasksBackend(BaseBackend):
                 provider="gcp",
                 provider_id=str(external_id) if external_id else None,
                 region=self._location,
-                resource=self.queue_path(queue),
+                resource=queue_path,
                 labels=dict(spec.labels),
             ),
             metadata={"queue": queue, "url": self._url},
         )
 
+    def _submit(self, spec: ExecutionSpec) -> Execution:
+        assert isinstance(spec, TaskSpec)
+        queue = self._queue_for(spec)
+        queue_path = self.queue_path(queue)
+        task = self._build_task(spec, queue_path)
+        try:
+            created = self._tasks().create_task(request={"parent": queue_path, "task": task})
+        except Exception as exc:
+            raise SubmissionError(
+                f"Cloud Tasks could not create a task for {spec.task!r} on queue {queue!r}: {exc}",
+                backend=self._name,
+            ) from exc
+        return self._execution_from(spec, created, queue_path, queue)
+
+    # -- native async (CloudTasksAsyncClient) ------------------------------------- #
+    @asynccontextmanager
+    async def _async_tasks(self) -> AsyncIterator[Any]:
+        if self._async_client is not None:
+            yield self._async_client
+            return
+        client = _async_tasks_client()
+        try:
+            yield client
+        finally:  # pragma: no cover - real gRPC client only
+            close = getattr(getattr(client, "transport", None), "close", None)
+            if callable(close):
+                await close()
+
+    async def asubmit(self, spec: ExecutionSpec) -> Execution:
+        """Native async submit via ``CloudTasksAsyncClient``, else the thread path."""
+        if self._async_client is None and not _has_cloud_tasks():
+            return await super().asubmit(spec)
+        assert isinstance(spec, TaskSpec)
+        self.validate(spec)
+        self.hooks.before_submit(spec, self.name)
+        queue = self._queue_for(spec)
+        queue_path = self._queue_path_str(queue)
+        task = self._build_task(spec, queue_path)
+        try:
+            async with self._async_tasks() as client:
+                created = await client.create_task(request={"parent": queue_path, "task": task})
+            execution = self._execution_from(spec, created, queue_path, queue)
+        except Exception as exc:
+            error = SubmissionError(
+                f"Cloud Tasks could not create a task for {spec.task!r} on queue {queue!r}: {exc}",
+                backend=self._name,
+            )
+            self.hooks.on_submit_error(spec, self.name, error)
+            raise error from exc
+        self.hooks.after_submit(spec, execution)
+        return execution
+
     @staticmethod
     def _correlation_headers(correlation: Correlation | None) -> dict[str, str]:
         """Propagate correlation and trace context as HTTP headers.
@@ -226,6 +282,29 @@ def _safe_name(key: str) -> str:
     return cleaned[:500] or "taskferry"
 
 
+def _has_cloud_tasks() -> bool:
+    """Whether the Google Cloud Tasks SDK is importable, without importing it."""
+    from importlib.util import find_spec
+
+    try:
+        # A dotted name raises (not returns None) when a parent package like
+        # ``google`` is absent, so both outcomes mean "not installed".
+        return find_spec("google.cloud.tasks_v2") is not None
+    except ModuleNotFoundError:
+        return False
+
+
+def _async_tasks_client() -> Any:
+    """A lazily-built ``CloudTasksAsyncClient``, with an actionable error."""
+    try:
+        from google.cloud import tasks_v2
+    except ImportError as exc:  # pragma: no cover - depends on the environment
+        raise ConfigurationError(
+            "the Cloud Tasks backend needs the Google SDK: pip install 'taskferry-cloudtasks[gcp]'"
+        ) from exc
+    return tasks_v2.CloudTasksAsyncClient()
+
+
 def make_backend(**options: Any) -> CloudTasksBackend:
     """Entry point for ``{"factory": "cloudtasks", ...}`` configuration."""
     return CloudTasksBackend(
@@ -236,6 +315,7 @@ def make_backend(**options: Any) -> CloudTasksBackend:
         service_account_email=options.get("service_account_email"),
         audience=options.get("audience"),
         client=options.get("client"),
+        async_client=options.get("async_client"),
         name=str(options.get("name", "cloudtasks")),
     )