google-api-python-client-stubs

google-api-python-client-stubs is a stubs-only package that adds static type information to the widely used google-api-python-client library. The base library is highly dynamic — resources are instances of a single class with methods attached at runtime, and requests and responses are plain dictionaries — which leaves type checkers and editors with almost nothing to work with.

These stubs, generated automatically from Google’s Discovery Documents, model each API, resource, and request/response shape as classes and TypedDicts so tools like mypy, Pyright, Pylance, and Pyre can type-check your Google API usage and provide accurate autocomplete. The package is not affiliated with Google.

What You Get

• PEP 561 type stubs auto-discovered by mypy, Pyright, Pylance, and Pyre
• TypedDict definitions for request and response bodies of Google APIs
• Class-based models for the dynamically attached resource methods
• Improved editor autocomplete when calling Google API endpoints
• Coverage generated from the same Discovery Documents that ship with the client

Common Use Cases

• Type-checking code that calls Google APIs via google-api-python-client with mypy
• Getting accurate autocomplete for Google API resources and requests in an IDE
• Catching wrong field names or shapes in Google API request bodies at check time
• Adding static typing to an existing Google Cloud or Workspace integration

Under The Hood

Architecture — The distribution is stubs-only: googleapiclient-stubs/ and apiclient-stubs/ contain .pyi files that mirror the runtime library’s import paths, plus a top-level discovery.pyi. Types that only exist for checking (the per-API resource and TypedDict definitions) live under a googleapiclient._apis namespace, organized by API name and version. A create_stubs.py generator produces all of this from Google’s Discovery Documents.

Tech Stack — Pure type-stub Python distributed under Apache-2.0, packaged via pyproject.toml with uv for dependency management. It contains no importable runtime code; its only role is to be consumed by static type checkers under PEP 561.

Code Quality — Because the stubs are machine-generated from authoritative Discovery Documents, coverage is broad and consistent across hundreds of Google APIs. The README documents the important caveat that the checking-only types must not be imported at runtime, and issues are used to trigger regeneration when annotations drift.

API Design — There is no API surface to call — installation alone activates the stubs. The main developer-experience consideration is the documented pattern for explicit annotations (use from future import annotations or TYPE_CHECKING imports), since the stub-only types are not available at runtime.