{"id":6285,"library":"types-google-cloud-ndb","title":"Typing Stubs for Google Cloud NDB","description":"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.","status":"active","version":"2.4.0.20260408","language":"en","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","google-cloud","ndb","google-cloud-ndb","typeshed","datastore"],"install":[{"cmd":"pip install types-google-cloud-ndb","lang":"bash","label":"Install typing stubs"},{"cmd":"pip install google-cloud-ndb","lang":"bash","label":"Install runtime library (if not already present)"}],"dependencies":[{"reason":"This package provides type stubs for google-cloud-ndb; it does not provide runtime functionality itself.","package":"google-cloud-ndb","optional":false}],"imports":[{"note":"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.","wrong":"from types_google_cloud_ndb import ndb","symbol":"ndb","correct":"from google.cloud import ndb"},{"note":"The `Client` class is the entry point for NDB interactions.","symbol":"Client","correct":"from google.cloud import ndb\nclient = ndb.Client()"},{"note":"Models are defined by inheriting from `ndb.Model`.","symbol":"Model","correct":"from google.cloud import ndb\nclass MyModel(ndb.Model): ..."}],"quickstart":{"code":"import os\nfrom google.cloud import ndb\nimport asyncio\n\n# For local development, point to the Datastore emulator\nos.environ['DATASTORE_EMULATOR_HOST'] = os.environ.get('DATASTORE_EMULATOR_HOST', 'localhost:8081')\n# Ensure your GOOGLE_CLOUD_PROJECT is set, e.g., in your environment or 'your-gcp-project-id'\nproject_id = os.environ.get('GOOGLE_CLOUD_PROJECT', 'your-gcp-project-id')\n\nclass User(ndb.Model):\n    name = ndb.StringProperty()\n    email = ndb.StringProperty()\n    joined_date = ndb.DateTimeProperty(auto_now_add=True)\n\nasync def main():\n    client = ndb.Client(project=project_id)\n    async with client.context():\n        # Create a user\n        user = User(name='Alice', email='alice@example.com')\n        user_key = await user.put()\n        print(f'Created user with key: {user_key.id()}')\n\n        # Fetch the user back by key\n        fetched_user = await user_key.get_async()\n        if fetched_user:\n            print(f'Fetched user: {fetched_user.name} ({fetched_user.email})')\n\n        # Query for users\n        query = User.query(User.name == 'Alice')\n        users_with_name = await query.fetch_async(limit=1)\n        if users_with_name:\n            print(f'Query result: {users_with_name[0].name}')\n\n        # Update user\n        if fetched_user:\n            fetched_user.email = 'alice.updated@example.com'\n            await fetched_user.put()\n            print(f'Updated user: {fetched_user.email}')\n\n        # Delete user\n        await user_key.delete_async()\n        print(f'Deleted user with key: {user_key.id()}')\n\nif __name__ == '__main__':\n    asyncio.run(main())","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"All versions when migrating from legacy App Engine NDB"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions of `google-cloud-ndb`"},{"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)`.","message":"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.`","severity":"gotcha","affected_versions":"All versions of `google-cloud-ndb`"},{"fix":"Always import NDB symbols from `google.cloud.ndb`. The `types-google-cloud-ndb` package is consumed solely by type checkers.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"deprecated","affected_versions":"All versions of `google-cloud-ndb`"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[]}