Registry / type-stubs / types-google-cloud-ndb

types-google-cloud-ndb

JSON →
library2.4.0.20260518pypypiunverified

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.

pip install types-google-cloud-ndb
INSTALL
IMPORT
SIG · TYPES-GOOGLE-CLOUD
T
types-google-cloud-ndb
type-stubspythonv2.4.0.20260518
Install
3.9s avg
Import
1873ms
Disk
143MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v2.4.0.20260518 · 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.10–3.940 runs
installs and imports cleanly · install 0.0s · import 2.188s · 17.9MB
glibc
py 3.10–3.940 runs
installs and imports cleanly · install 3.9s · import 1.557s · 214MB
143MB installed
● package 143MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ndb
✓ from google-stubs import ndb
✗ from google-stubs import ndb

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())
Debug
Known issues
breakingMigration 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.
affects: All versions when migrating from legacy App Engine NDB
gotchaAll 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.
affects: All versions of `google-cloud-ndb`
gotchaAll 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)`.
affects: All versions of `google-cloud-ndb`
gotchaThe `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.
affects: All versions
gotchaWhile `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.
affects: All versions
deprecatedCloud 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.
affects: All versions of `google-cloud-ndb`
Upgrade
Version history
2.4.0.20260518latest on PyPI · released May 18, 2026
Audit
Dependencies
google-cloud-ndbrequiredThis package provides type stubs for google-cloud-ndb; it does not provide runtime functionality itself.
Agent activity
50 hits · last 30 days
node
42
OpenAI (training)
1
Resources
types-google-cloud-ndb — pip install types-google-cloud-ndb · libregistry