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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 54.7MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 4.1s · import 0.000s · 55MB
54MB installed
● package 54MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DatastoreClient
✓ from gcloud_rest_datastore import DatastoreClient
✗ from gcloud_rest_datastore.client import DatastoreClient
The `DatastoreClient` is exposed directly in the top-level package `__init__.py`.
Key
✓ from gcloud_rest_datastore.entities import Key
Entity
✓ from gcloud_rest_datastore.entities import Entity
Query
✓ from gcloud_rest_datastore.query import Query
This quickstart demonstrates how to initialize the `DatastoreClient`, create an entity with a key, insert it into Datastore, and then retrieve it using `lookup`. Ensure your `GOOGLE_CLOUD_PROJECT` environment variable is set or replace 'your-project-id' directly. Authentication usually works automatically via `GOOGLE_APPLICATION_CREDENTIALS` or default GCP environment settings.
import asyncio
import os
from gcloud_rest_datastore import DatastoreClient
from gcloud_rest_datastore.entities import Key, PathElement, Entity, Property
async def main():
project_id = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-project-id')
if project_id == 'your-project-id':
print("Please set GOOGLE_CLOUD_PROJECT environment variable or replace 'your-project-id' with your actual project ID.")
return
client = DatastoreClient(project=project_id)
# Create a key
key = Key(project_id=project_id, path=[PathElement(kind='Task', name='sample-task')])
# Create an entity
entity = Entity(
key=key,
properties={
'description': Property(string_value='Learn gcloud-rest-datastore'),
'done': Property(boolean_value=False)
}
)
# Insert/Update the entity
try:
await client.commit(mode='NON_TRANSACTIONAL', mutations=[{'insertOrUpdate': entity}])
print(f"Entity inserted/updated: {key.path[0].name}")
# Lookup the entity
results = await client.lookup(keys=[key])
if results.found:
retrieved_entity = results.found[0].entity
print(f"Retrieved entity: {retrieved_entity.properties['description'].string_value}, Done: {retrieved_entity.properties['done'].boolean_value}")
else:
print("Entity not found.")
except Exception as e:
print(f"An error occurred: {e}")
finally:
await client.close()
if __name__ == '__main__':
asyncio.run(main())
Debug
Known issues
gotchaPython 3.9 Compatibility for `gcloud-rest-auth`. While `gcloud-rest-datastore` v9.1.0's PyPI metadata states `requires_python>=3.9`, its dependency `gcloud-rest-auth` v5.4.4 (and newer) explicitly dropped support for Python 3.9. Installing `gcloud-rest-datastore` on Python 3.9 might pull a problematic version of `gcloud-rest-auth`.fixUse Python 3.10 or newer. If you must use Python 3.9, explicitly pin `gcloud-rest-auth<5.4.4` in your `requirements.txt`.
affects: gcloud-rest-datastore>=9.1.0 on Python 3.9
gotchaAsynchronous API Calls. This library is fully asynchronous. All methods that interact with the Datastore API are `awaitable` coroutines. Forgetting to use `await` will result in coroutine objects being returned instead of the actual results, leading to `TypeError` or unexpected behavior.fixAlways prepend `await` to calls like `await client.commit(...)` or `await client.lookup(...)`. Ensure your code runs within an `async` function and an `asyncio` event loop (e.g., `asyncio.run(main())`).
affects: All versions
gotchaAuthentication Setup. The client relies on `google-auth` for authentication, which defaults to `GOOGLE_APPLICATION_CREDENTIALS`, GKE service accounts, or instance metadata. If your environment is not correctly configured for GCP authentication, API calls will fail.fixSet the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to the path of your service account JSON key file, or ensure your execution environment has appropriate IAM roles for Datastore access (e.g., in GKE or GCE).
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'gcloud_rest_datastore'
The `gcloud-rest-datastore` package is not installed in your Python environment.
fixRun `pip install gcloud-rest-datastore` to install the library.
TypeError: object async_generator object at 0x... is not awaitable
You attempted to call an async method without `await`, or tried to iterate over an async generator synchronously.
fixPrepend `await` to your async function calls (e.g., `await client.lookup(...)`). If dealing with async generators, use `async for`.
gcloud_rest.auth.exceptions.AuthError: Could not retrieve credentials.
The client could not find valid Google Cloud credentials in the environment.
fixEnsure `GOOGLE_APPLICATION_CREDENTIALS` points to a valid service account key file, or that your execution environment (e.g., GCP VM, Cloud Run, GKE pod) has a service account with the necessary permissions (e.g., `Datastore User` or `Datastore Editor`).
RuntimeError: Event loop is already running
You are trying to call `asyncio.run()` in an environment where an event loop is already active (e.g., Jupyter Notebook, IPython, or a nested `asyncio.run()` call).
fixIn interactive environments, use `nest_asyncio` (e.g., `import nest_asyncio; nest_asyncio.apply()`) or run coroutines directly with `await` if already in an async context. Avoid nesting `asyncio.run()` calls in applications.
Upgrade
Version history
9.1.0latest on PyPI · released Aug 26, 2025
Audit
Dependencies
gcloud-rest-authrequiredHandles authentication for all `gcloud-aio` clients.
httpxrequiredUnderlying HTTP client for async requests.
google-authrequiredProvides default Google authentication mechanisms.
Resources
No resource links recorded.