Registry / gcp / gcloud-aio-datastore

gcloud-aio-datastore

JSON →
library9.1.0pypypi✓ verified 87d 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.93.13
musl
3.93.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.103.920 runs
installs and imports cleanly · install 0.0s · import 0.759s · 60.3MB
glibc
py 3.103.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
34 hits · last 30 days
node
28
OpenAI (training)
1
Resources
gcloud-aio-datastore — pip install gcloud-aio-datastore · libregistry