Google Cloud Task Queue Client (gcloud-aio)

Common errors

• NameError: name 'await' is not defined

  cause Attempting to use the `await` keyword outside of an `async` function.
  fix Wrap your asynchronous code in an `async def` function and run it using `asyncio.run(your_async_function())`.

• google.auth.exceptions.DefaultCredentialsError: Could not automatically determine credentials.

  cause The client could not find valid Google Application Credentials to authenticate with Google Cloud. This usually means the `GOOGLE_APPLICATION_CREDENTIALS` environment variable is not set, or the specified file is invalid/inaccessible.
  fix Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the file path of your service account JSON key, or ensure your application is running in an environment (e.g., GCE, Cloud Run) where default credentials are automatically provided.

• aiohttp.client_exceptions.ClientConnectorError: Cannot connect to host taskqueue.googleapis.com:443 ssl:default [Name or service not known]

  cause Network connectivity issue preventing the client from reaching the Google Cloud Task Queue API endpoint. This can be due to DNS resolution problems, firewall rules, or an unstable internet connection.
  fix Verify your internet connection, check local and network firewall rules (port 443), ensure DNS resolution is working, and confirm the Google Cloud Task Queue API is enabled for your project.

• AttributeError: module 'gcloud.aio.taskqueue' has no attribute 'TaskQueueClient'

  cause You are likely using an older version of the `gcloud-aio-taskqueue` library, or a very old version where the class might have been named differently or imported from a submodule (e.g., `gcloud.aio.taskqueue.client`).
  fix Ensure you are using `gcloud-rest-taskqueue` version 7.0.0+ and importing with `from gcloud.aio.taskqueue import TaskQueueClient`. If on an older version, consult its specific documentation for the correct import path.

Warnings

• breaking Version 7.0.0 of `gcloud-rest-taskqueue` (and `gcloud-aio-taskqueue`) drops support for Python 3.7. Users on Python 3.7 should remain on version 6.x or upgrade their Python interpreter.
  Fix: Upgrade Python to 3.8+ or pin `gcloud-rest-taskqueue` to `<7.0.0`.
• breaking Version 6.0.0 of `gcloud-rest-taskqueue` (and `gcloud-aio-taskqueue`) dropped support for Python 3.6. Users on Python 3.6 should remain on version 5.x or upgrade their Python interpreter.
  Fix: Upgrade Python to 3.7+ or pin `gcloud-rest-taskqueue` to `<6.0.0`.
• gotcha This library is an asynchronous client. All API calls must be `await`ed within an `async def` function, which then needs to be executed using `asyncio.run()` (or similar event loop management). Direct synchronous calls will result in `RuntimeError` or `NameError`.
  Fix: Ensure all client method calls are prefixed with `await` and the entry point uses `asyncio.run()`.
• gotcha Authentication relies on Google Application Credentials. If not explicitly provided, the client will attempt to infer them from the environment (e.g., `GOOGLE_APPLICATION_CREDENTIALS` environment variable pointing to a service account key file, or default credentials when running on GCP services).
  Fix: Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of your service account JSON key file, or ensure appropriate IAM roles are assigned to your GCP service.
• gotcha This `gcloud-rest-taskqueue` library (part of `gcloud-aio`) is an *asynchronous* client using `aiohttp`. It is distinct from Google's official `google-cloud-tasks` client library, which uses gRPC and offers both synchronous and wrapped asynchronous APIs. The API signatures and underlying implementations are different.
  Fix: Choose the client that best fits your application's asynchronous requirements and ensure you consult the correct documentation for the chosen library.

Install

• pip install gcloud-rest-taskqueue Install latest version

Imports

• TaskQueueClient
  wrong:

  from gcloud.aio.taskqueue.client import TaskQueueClient

  correct:

  from gcloud.aio.taskqueue import TaskQueueClient

  For versions 7.0.0+, TaskQueueClient is directly exposed by the package's top-level __init__. Earlier versions might have required importing from a .client submodule.
• build_from_env

  from gcloud.aio.auth import build_from_env

  This helper function from `gcloud-aio-auth` is commonly used to set up an authenticated aiohttp.ClientSession.

Quickstart

This quickstart demonstrates how to initialize the `TaskQueueClient` and create a task asynchronously. Ensure your `GCLOUD_PROJECT` environment variable is set and that Google Application Credentials are available for authentication.

import asyncio
import os

from gcloud.aio.auth import build_from_env
from gcloud.aio.taskqueue import TaskQueueClient

async def main():
    async with build_from_env() as client_session:
        # Replace with your actual project ID and desired location
        project_id = os.environ.get("GCLOUD_PROJECT", "your-gcp-project-id")
        location = os.environ.get("GCLOUD_TASKQUEUE_LOCATION", "us-east1") # e.g., 'us-central1'
        queue_name = os.environ.get("GCLOUD_TASKQUEUE_NAME", "my-queue") # e.g., 'my-queue'
        
        if not project_id or project_id == "your-gcp-project-id":
            print("Please set GCLOUD_PROJECT environment variable or replace 'your-gcp-project-id'.")
            return

        client = TaskQueueClient(
            project=project_id,
            location=location,
            session=client_session
        )

        task_name = "my-test-task-1"
        payload = {"data": "hello world", "timestamp": "2023-01-01T12:00:00Z"}

        try:
            await client.create_task(
                project=project_id,
                location=location,
                queue_name=queue_name,
                task_name=task_name,
                payload=payload
            )
            print(f"Task '{task_name}' created successfully in queue '{queue_name}' in project '{project_id}'.")
        except Exception as e:
            print(f"Failed to create task: {e}")

if __name__ == '__main__':
    asyncio.run(main())