{"id":14592,"library":"gcloud-rest-datastore","title":"Google Cloud Datastore REST Client (Async)","description":"gcloud-rest-datastore is an asynchronous Python client for interacting with Google Cloud Datastore via its REST API. It is part of the `gcloud-aio` monorepo, which provides async clients for various Google Cloud services. The current version is 9.1.0, and the project releases updates to individual service clients as needed, often with shared core dependencies.","status":"active","version":"9.1.0","language":"en","source_language":"en","source_url":"https://github.com/talkiq/gcloud-aio","tags":["google cloud","datastore","async","rest","gcloud-aio"],"install":[{"cmd":"pip install gcloud-rest-datastore","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Handles authentication for all `gcloud-aio` clients.","package":"gcloud-rest-auth","optional":false},{"reason":"Underlying HTTP client for async requests.","package":"httpx","optional":false},{"reason":"Provides default Google authentication mechanisms.","package":"google-auth","optional":false}],"imports":[{"note":"The `DatastoreClient` is exposed directly in the top-level package `__init__.py`.","wrong":"from gcloud_rest_datastore.client import DatastoreClient","symbol":"DatastoreClient","correct":"from gcloud_rest_datastore import DatastoreClient"},{"symbol":"Key","correct":"from gcloud_rest_datastore.entities import Key"},{"symbol":"Entity","correct":"from gcloud_rest_datastore.entities import Entity"},{"symbol":"Query","correct":"from gcloud_rest_datastore.query import Query"}],"quickstart":{"code":"import asyncio\nimport os\nfrom gcloud_rest_datastore import DatastoreClient\nfrom gcloud_rest_datastore.entities import Key, PathElement, Entity, Property\n\nasync def main():\n    project_id = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-project-id')\n    if project_id == 'your-project-id':\n        print(\"Please set GOOGLE_CLOUD_PROJECT environment variable or replace 'your-project-id' with your actual project ID.\")\n        return\n\n    client = DatastoreClient(project=project_id)\n\n    # Create a key\n    key = Key(project_id=project_id, path=[PathElement(kind='Task', name='sample-task')])\n\n    # Create an entity\n    entity = Entity(\n        key=key,\n        properties={\n            'description': Property(string_value='Learn gcloud-rest-datastore'),\n            'done': Property(boolean_value=False)\n        }\n    )\n\n    # Insert/Update the entity\n    try:\n        await client.commit(mode='NON_TRANSACTIONAL', mutations=[{'insertOrUpdate': entity}])\n        print(f\"Entity inserted/updated: {key.path[0].name}\")\n\n        # Lookup the entity\n        results = await client.lookup(keys=[key])\n        if results.found: \n            retrieved_entity = results.found[0].entity\n            print(f\"Retrieved entity: {retrieved_entity.properties['description'].string_value}, Done: {retrieved_entity.properties['done'].boolean_value}\")\n        else:\n            print(\"Entity not found.\")\n            \n    except Exception as e:\n        print(f\"An error occurred: {e}\")\n    finally:\n        await client.close()\n\nif __name__ == '__main__':\n    asyncio.run(main())","lang":"python","description":"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."},"warnings":[{"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`.","message":"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`.","severity":"gotcha","affected_versions":"gcloud-rest-datastore>=9.1.0 on Python 3.9"},{"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())`).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install gcloud-rest-datastore` to install the library.","cause":"The `gcloud-rest-datastore` package is not installed in your Python environment.","error":"ModuleNotFoundError: No module named 'gcloud_rest_datastore'"},{"fix":"Prepend `await` to your async function calls (e.g., `await client.lookup(...)`). If dealing with async generators, use `async for`.","cause":"You attempted to call an async method without `await`, or tried to iterate over an async generator synchronously.","error":"TypeError: object async_generator object at 0x... is not awaitable"},{"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`).","cause":"The client could not find valid Google Cloud credentials in the environment.","error":"gcloud_rest.auth.exceptions.AuthError: Could not retrieve credentials."},{"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.","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).","error":"RuntimeError: Event loop is already running"}],"ecosystem":"pypi"}