Typing Stubs for Google Cloud NDB

2.4.0.20260408 · active · verified Tue Apr 14

This package provides static type checking stubs for the `google-cloud-ndb` library, enabling tools like MyPy or PyRight to perform compile-time type validation of NDB code. Maintained as part of the `typeshed` project, it currently targets `google-cloud-ndb==2.4.*`. Updates are automatically released, often daily, to reflect changes in the underlying library.

Warnings

breaking Migration from the original App Engine NDB (`google.appengine.ext.ndb`) to `google-cloud-ndb` (which these stubs type) requires significant code changes. This library is a standalone client for Cloud Datastore, not a direct drop-in replacement for App Engine apps. Key differences include package name, mandatory `async/await` for most operations, and different client initialization and context management.
Fix: Rewrite application logic to use `google.cloud.ndb` imports, adapt to `async/await` patterns, and implement new client and context management. Consult the official `google-cloud-ndb` migration guides.
gotcha All NDB database operations (e.g., `put()`, `get()`, `fetch()`) are asynchronous and return 'futures'. Forgetting to `await` these operations will result in the operation not being executed, or returning the future object itself rather than its result.
Fix: Always use `await` before any NDB operation that interacts with the Datastore, such as `await entity.put()`, `await key.get_async()`, `await query.fetch_async()`, etc.
gotcha All Datastore interactions must occur within an NDB context. Failing to establish a context (or letting it expire) will raise a `RuntimeError: A context is required for this operation.`
Fix: For `async` code, use `async with client.context():`. For non-`async` code, use the `@ndb.toplevel` decorator or explicitly enter/exit the context using `context = client.context(); context.__enter__(); try: ... finally: context.__exit__(None, None, None)`.
gotcha The `types-google-cloud-ndb` package provides *only* type annotations. It does not contain any executable code. Importing symbols from `types_google_cloud_ndb` for runtime use will result in `ModuleNotFoundError` or `AttributeError`.
Fix: Always import NDB symbols from `google.cloud.ndb`. The `types-google-cloud-ndb` package is consumed solely by type checkers.
gotcha While `types-google-cloud-ndb` aims to provide accurate annotations for `google-cloud-ndb==2.4.*`, significant discrepancies between the stub version and the runtime library version can lead to incorrect type checking results or missed errors.
Fix: Keep `types-google-cloud-ndb` and `google-cloud-ndb` versions as close as possible. The stub's version (e.g., `2.4.0.20260408`) indicates it targets `google-cloud-ndb==2.4.*`. Regularly update both packages to their latest compatible versions.
deprecated Cloud NDB is primarily intended as a migration path for applications moving from App Engine NDB. For *new* Python 3 applications that require Datastore, Google recommends using the native Cloud Datastore client library (`google-cloud-datastore`) instead of Cloud NDB, as it supports newer Firestore in Datastore mode features.
Fix: For greenfield Python 3 projects or new features, consider using `google-cloud-datastore`. If migrating an existing App Engine NDB app, Cloud NDB remains a viable intermediate step.

Install

pip install types-google-cloud-ndb Install typing stubs
pip install google-cloud-ndb Install runtime library (if not already present)

Imports

ndb
```
from google.cloud import ndb
```
The `types-google-cloud-ndb` package provides type information, not runtime code. All NDB classes and functions are imported from the `google.cloud.ndb` package.
Client
```
from google.cloud import ndb
client = ndb.Client()
```
The `Client` class is the entry point for NDB interactions.

Model

from google.cloud import ndb
class MyModel(ndb.Model): ...

Models are defined by inheriting from `ndb.Model`.

Quickstart

This quickstart demonstrates basic CRUD operations using `google-cloud-ndb` with `async/await` and context management. Installing `types-google-cloud-ndb` alongside `google-cloud-ndb` will enable your type checker to provide rich completions and error detection for this code, enhancing developer experience. Ensure you have the Cloud Datastore emulator running for local testing and `GOOGLE_CLOUD_PROJECT` environment variable set for deployment.

import os
from google.cloud import ndb
import asyncio

# For local development, point to the Datastore emulator
os.environ['DATASTORE_EMULATOR_HOST'] = os.environ.get('DATASTORE_EMULATOR_HOST', 'localhost:8081')
# Ensure your GOOGLE_CLOUD_PROJECT is set, e.g., in your environment or 'your-gcp-project-id'
project_id = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-gcp-project-id')

class User(ndb.Model):
    name = ndb.StringProperty()
    email = ndb.StringProperty()
    joined_date = ndb.DateTimeProperty(auto_now_add=True)

async def main():
    client = ndb.Client(project=project_id)
    async with client.context():
        # Create a user
        user = User(name='Alice', email='alice@example.com')
        user_key = await user.put()
        print(f'Created user with key: {user_key.id()}')

        # Fetch the user back by key
        fetched_user = await user_key.get_async()
        if fetched_user:
            print(f'Fetched user: {fetched_user.name} ({fetched_user.email})')

        # Query for users
        query = User.query(User.name == 'Alice')
        users_with_name = await query.fetch_async(limit=1)
        if users_with_name:
            print(f'Query result: {users_with_name[0].name}')

        # Update user
        if fetched_user:
            fetched_user.email = 'alice.updated@example.com'
            await fetched_user.put()
            print(f'Updated user: {fetched_user.email}')

        # Delete user
        await user_key.delete_async()
        print(f'Deleted user with key: {user_key.id()}')

if __name__ == '__main__':
    asyncio.run(main())

view raw JSON →