Google Cloud Datastore REST Client (Async)

Common errors

• ModuleNotFoundError: No module named 'gcloud_rest_datastore'

  cause The `gcloud-rest-datastore` package is not installed in your Python environment.
  fix Run `pip install gcloud-rest-datastore` to install the library.

• TypeError: object async_generator object at 0x... is not awaitable

  cause You attempted to call an async method without `await`, or tried to iterate over an async generator synchronously.
  fix Prepend `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.

  cause The client could not find valid Google Cloud credentials in the environment.
  fix Ensure `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

  cause 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).
  fix In 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.

Warnings

• gotcha Python 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`.
  Fix: Use Python 3.10 or newer. If you must use Python 3.9, explicitly pin `gcloud-rest-auth<5.4.4` in your `requirements.txt`.
• gotcha Asynchronous 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.
  Fix: Always 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())`).
• gotcha Authentication 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.
  Fix: Set 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).

Install

• pip install gcloud-rest-datastore Install latest version

Imports

• DatastoreClient
  wrong:

  from gcloud_rest_datastore.client import DatastoreClient

  correct:

  from gcloud_rest_datastore 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

Quickstart

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())