Asynchronous Google Cloud Datastore Client

Warnings

• breaking Python 3.9 support was dropped by `gcloud-aio-auth` in version `5.4.4`. While `gcloud-aio-datastore 9.1.0` lists `Python >= 3.9` as compatible, installing `gcloud-aio-auth >= 5.4.4` (which is within `gcloud-aio-datastore`'s dependency range `<6.0.0,>=5.0.0`) will lead to compatibility issues for Python 3.9 users.
  Fix: Upgrade your Python environment to 3.10 or newer. If you must use Python 3.9, pin `gcloud-aio-auth` to `<5.4.4` (e.g., `gcloud-aio-auth<5.4.4,>=5.0.0`) in your requirements, although this might prevent future security updates for `gcloud-aio-auth`.
• breaking Version 9.0.0 of `gcloud-aio-datastore` removed the `Datastore.from_service_account()` and `Datastore.from_dict()` convenience constructors. Authentication should now be handled explicitly by building credentials via `gcloud.aio.auth.build_from_service_account()` and passing them to the `Datastore` client constructor.
  Fix: Migrate your authentication setup to use `gcloud.aio.auth.build_from_service_account()` and pass the resulting credentials object directly to the `Datastore` constructor. Refer to the quickstart example for the updated pattern.
• gotcha This library is entirely asynchronous (`aio`). All client methods are `await`able coroutines and must be called within an `asyncio` event loop. Attempting to call them synchronously will result in `RuntimeError: 'coroutine' object is not awaited`.
  Fix: Ensure your code uses `async def` functions and `await` for all `gcloud-aio-datastore` calls. Run your main `async` function using `asyncio.run()`.
• gotcha The `gcloud-aio` project is a monorepo, meaning individual client libraries like `gcloud-aio-datastore`, `gcloud-aio-storage`, and `gcloud-aio-auth` have independent versioning. Upgrading one component does not automatically upgrade others, and you must manage dependencies for each sub-package carefully to avoid version conflicts or unexpected behavior.
  Fix: Always check the `requires_dist` for specific `gcloud-aio-*` packages on PyPI to understand their compatible version ranges for dependencies. Use a dependency manager like `pip-tools` or `Poetry` to ensure a consistent environment.
• gotcha Authentication relies on `gcloud-aio-auth`. It primarily supports service account keys (JSON string or path). Ensure `GCP_PROJECT` and `GCP_SERVICE_KEY` (or `GCP_SERVICE_KEY_PATH`) environment variables are correctly configured or explicitly passed to `build_from_service_account`.
  Fix: Verify your environment variables or direct arguments for authentication. Debug authentication issues by ensuring `build_from_service_account` successfully returns credentials before initializing the Datastore client.

Install

• pip install gcloud-aio-datastore Install stable version

Imports

• Datastore

  from gcloud.aio.datastore import Datastore

• Key

  from gcloud.aio.datastore import Key

• Query

  from gcloud.aio.datastore import Query

Quickstart

This quickstart demonstrates how to initialize the Datastore client using service account credentials, create, retrieve, and query entities. Ensure `GCP_PROJECT` is set to your Google Cloud project ID and `GCP_SERVICE_KEY` is set to your service account key JSON string (or path via `GCP_SERVICE_KEY_PATH`) in the environment. The client uses `async with` for proper resource management.

import asyncio
import os
from gcloud.aio.auth import build_from_service_account
from gcloud.aio.datastore import Datastore, Key, Query

async def main():
    project = os.environ.get('GCP_PROJECT', 'your-gcp-project-id')
    service_account_info = os.environ.get('GCP_SERVICE_KEY') # or path via GCP_SERVICE_KEY_PATH

    if not project or not service_account_info:
        print("Please set GCP_PROJECT and GCP_SERVICE_KEY environment variables.")
        return

    # Credentials can also be built from a path using build_from_service_account_path()
    creds = build_from_service_account(service_account_info)
    
    async with Datastore(project=project, credentials=creds) as client:
        # 1. Create an entity
        kind = 'MyEntity'
        name = 'my-unique-entity-name'
        key = Key([kind, name], project=project)
        
        entity_data = {
            'property1': 'value1',
            'property2': 123
        }
        await client.put_entity(key, entity_data)
        print(f"Created/updated entity: {key.path[0]['id']}")

        # 2. Get an entity
        retrieved_entity = await client.get_entity(key)
        if retrieved_entity:
            print(f"Retrieved entity: {retrieved_entity.properties}")
        else:
            print(f"Entity {key.path[0]['id']} not found.")

        # 3. Run a query
        query = Query(kind=kind, project=project)
        results = await client.run_query(query)
        print("Query results:")
        for entity in results:
            print(f"  Kind: {entity.kind}, ID: {entity.id}, Properties: {entity.properties}")

        # 4. Delete an entity (optional cleanup)
        # await client.delete_entity(key)
        # print(f"Deleted entity: {key.path[0]['id']}")

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