{"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":"python","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":[{"wrong":"from google-stubs import ndb","symbol":"ndb","correct":"from google-stubs import ndb"}],"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,"search_vec":"'2.4':51 'automat':54 'chang':60 'check':12 'cloud':5,18,49,69,73 'code':36 'compil':30 'compile-tim':29 'current':45 'daili':57 'datastor':76 'enabl':21 'googl':4,17,48,68,72 'google-cloud':67 'google-cloud-ndb':16,47,71 'librari':20,64 'like':23 'maintain':37 'mypi':24 'ndb':6,19,35,50,70,74 'often':56 'packag':8 'part':39 'perform':28 'project':43 'provid':9 'pyright':26 'reflect':59 'releas':55 'static':10 'stub':2,13,66 'target':46 'time':31 'tool':22 'type':1,11,32,65 'typesh':42,75 'under':63 'updat':52 'valid':33","created_at":"2026-04-14T18:49:58.862656+00:00","updated_at":"2026-04-14T18:49:58.862656+00:00","problems":{"verify_error":"File \"<string>\", line 1\n    from google-stubs import ndb\n               ^\nSyntaxError: invalid syntax"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"2.4.0.20260518","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/typeshed-internal/stub_uploader","docs":null,"changelog":"https://github.com/typeshed-internal/stub_uploader/blob/main/data/changelogs/google-cloud-ndb.md","pypi":"https://pypi.org/project/types-google-cloud-ndb/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["type-stubs","gcp"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"import_fail","verified_at":"2026-07-03","last_verified":"2026-07-03","next_check":"2026-07-10","install_tag":null}}