Registry / gcp / gcloud-aio-datastore

gcloud-aio-datastore

JSON →
library9.1.0pypypi✓ verified 89d ago

gcloud-aio-datastore is an asynchronous Python client for interacting with Google Cloud Datastore. It's part of the `gcloud-aio` monorepo, which provides async interfaces for various Google Cloud services (Datastore, Storage, Pub/Sub, Auth, etc.). This library wraps the official `google-cloud-datastore` client with an `asyncio` interface. The project is actively maintained, with components releasing independently but frequently.

pip install gcloud-aio-datastore
INSTALL
IMPORT
SIG · GCLOUD-AIO-DATASTO
G
gcloud-aio-datastore
gcppythonv9.1.0
Install
5.6s avg
Import
731ms
Disk
61MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v9.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.759s · 60.3MB
glibc
py 3.10–3.920 runs
installs and imports cleanly · install 5.6s · import 0.703s · 62MB
61MB installed
● package 61MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Datastore
✓ from gcloud.aio.datastore import Datastore
Key
✓ from gcloud.aio.datastore import Key
Query
✓ from gcloud.aio.datastore import Query

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())
Debug
Known issues
breakingPython 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`.
affects: gcloud-aio-datastore >= 9.1.0 (when combined with gcloud-aio-auth >= 5.4.4)
breakingVersion 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.
affects: gcloud-aio-datastore >= 9.0.0
gotchaThis 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()`.
affects: All versions
gotchaThe `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.
affects: All versions
gotchaAuthentication 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.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'gcloud.aio.datastore'
This error occurs when the `gcloud-aio-datastore` package is not installed or is not accessible in the current Python environment.
fix
Ensure the library is correctly installed using pip: `pip install gcloud-aio-datastore` or if using `gcloud-rest-datastore`, `pip install gcloud-rest-datastore`.
google.auth.exceptions.DefaultCredentialsError: Could not automatically determine credentials.
This error indicates that your application cannot find the necessary Google Cloud credentials to authenticate with Datastore, often due to missing `GOOGLE_APPLICATION_CREDENTIALS` environment variable or not having run `gcloud auth application-default login`.
fix
Set the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of your service account key file (e.g., `export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"`), or authenticate via the gcloud CLI by running `gcloud auth application-default login`.
TypeError: object ... is not awaitable
This error happens when you call an asynchronous function (coroutine) from `gcloud-aio-datastore` without using the `await` keyword, which is required for `asyncio` operations.
fix
Prepend the call to the asynchronous function with `await`. For example, instead of `client.get(key)`, use `await client.get(key)`. Ensure your code runs within an `async` function and an `asyncio` event loop.
AttributeError: module 'grpc.experimental.aio' has no attribute 'StreamUnaryCall'
This `AttributeError` typically arises from a version incompatibility between the `google-cloud-datastore` library (which `gcloud-aio-datastore` wraps) and its `grpcio` dependency. It suggests that a newer version of `google-cloud-datastore` expects a `grpcio` feature that an older `grpcio` version does not provide.
fix
Pin `google-api-core` to a compatible version (e.g., `google-api-core==1.17.0`) and/or ensure `grpcio` and `google-cloud-datastore` are updated to their latest compatible versions by running `pip install --upgrade google-cloud-datastore grpcio` and checking the project's dependencies for specific requirements.
Upgrade
Version history
9.1.0latest on PyPI · released Aug 26, 2025
Audit
Dependencies
gcloud-aio-authrequiredHandles authentication for all gcloud-aio clients.
gcloud-aio-corerequiredProvides core utilities and base classes for gcloud-aio clients.
google-cloud-datastorerequiredUnderlying synchronous Google Cloud Datastore client, which gcloud-aio-datastore wraps.
Agent activity
37 hits · last 30 days
node
30
Anthropic
1
OpenAI (training)
1
Resources
gcloud-aio-datastore — pip install gcloud-aio-datastore · libregistry