{"id":2520,"library":"google-api-python-client-stubs","title":"Google API Python Client Stubs","description":"This package provides type stubs for the `google-api-python-client` library, enabling type checking with tools like `mypy` and improving autocompletion in IDEs. The stubs are automatically generated based on Google's Discovery Documents. It is not officially affiliated with Google, and its releases can be infrequent.","status":"active","version":"1.34.0","language":"python","source_language":"en","source_url":"https://github.com/googleapis/google-api-python-client-stubs","tags":["google","api","client","stubs","type-hinting","mypy","discovery","google-cloud"],"install":[{"cmd":"pip install google-api-python-client-stubs","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Provides the runtime library for which these are stubs.","package":"google-api-python-client","optional":false},{"reason":"A static type checker commonly used with these stubs.","package":"mypy","optional":true}],"imports":[{"symbol":"build","correct":"from googleapiclient.discovery import build"},{"note":"Runtime type stubs are located under `googleapiclient._apis` and should only be imported within `if typing.TYPE_CHECKING:` blocks or referenced as string literals with `from __future__ import annotations`.","wrong":"from googleapiclient.sheets.v4.resources import SheetsResource","symbol":"SheetsResource","correct":"from googleapiclient._apis.sheets.v4.resources import SheetsResource"}],"quickstart":{"code":"import os\nimport typing\nfrom googleapiclient.discovery import build\n\n# Ensure annotations are processed correctly for type checkers\nfrom __future__ import annotations\n\n# Import the type stub for a specific service (e.g., Google Sheets v4)\n# This import is solely for type checking and will not be evaluated at runtime.\nif typing.TYPE_CHECKING:\n    from googleapiclient._apis.sheets.v4.resources import SheetsResource\n\n# Use a placeholder for the API key for demonstration purposes\n# In a real application, you would use proper authentication (e.g., OAuth2.0)\n# or retrieve from environment variables.\nAPI_KEY = os.environ.get(\"GOOGLE_API_KEY\", \"YOUR_API_KEY\")\n\ndef main():\n    # Build the service client (runtime code for the actual API interaction)\n    service = build(\"sheets\", \"v4\", developerKey=API_KEY)\n\n    # Example of type-hinting the service object using the imported stub type.\n    # This provides better IDE autocompletion and static type checking.\n    sheets_service: SheetsResource = build(\"sheets\", \"v4\", developerKey=API_KEY)\n\n    print(f\"Service built successfully. Runtime type: {type(service)}\")\n    print(\"IDE and type checkers will now recognize 'sheets_service' as SheetsResource.\")\n\n    # Example API call (commented out as it requires a valid API key/credentials)\n    # try:\n    #     spreadsheet_id = 'YOUR_SPREADSHEET_ID'\n    #     range_name = 'Sheet1!A1:B2'\n    #     result = sheets_service.spreadsheets().values().get(\n    #         spreadsheetId=spreadsheet_id,\n    #         range=range_name\n    #     ).execute()\n    #     print(f\"Retrieved data: {result}\")\n    # except Exception as e:\n    #     print(f\"Error accessing Sheets API: {e}\")\n\nif __name__ == \"__main__\":\n    main()\n","lang":"python","description":"This quickstart demonstrates how to set up and use the `google-api-python-client-stubs` to provide type hints for a Google Sheets service client. It shows both the runtime `build` call and how to apply an explicit type annotation for improved development experience. Note the use of `if typing.TYPE_CHECKING:` to prevent runtime errors from stub-only imports."},"warnings":[{"fix":"To safely use explicit type annotations, import types within an `if typing.TYPE_CHECKING:` block or use `from __future__ import annotations` at the top of your file (for Python 3.7+ and 3.8, it makes annotations evaluated lazily).","message":"Type classes and `TypedDict`s provided by `google-api-python-client-stubs` are design-time artifacts and do not exist at runtime. Direct runtime imports or unquoted explicit annotations (in Python < 3.9 without `from __future__ import annotations`) will cause `NameError` or `ModuleNotFoundError`.","severity":"breaking","affected_versions":"All versions"},{"fix":"Explicitly annotating the service object with the correct stub type (e.g., `sheets_service: SheetsResource = build(...)`) can significantly speed up type checking and autocompletion for that variable, but adhere to the runtime import caveats.","message":"Type inference for `googleapiclient.discovery.build` can be slow in `mypy` or IDEs due to the large number of overloads generated for various services and versions. This can impact autocompletion performance.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware that type checking coverage might be limited in these generic areas. Contributions to improve these stubs are generally welcome on the project's GitHub repository.","message":"Stubs for non-API-specific parts of the `google-api-python-client` library (e.g., parts of `googleapiclient.http` or core utility functions) are less detailed compared to the API-specific service definitions, often defaulting to `Any`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"New features or API versions in the upstream `google-api-python-client` might not immediately have corresponding stubs. Users may need to open an issue on the stub library's GitHub repository to request an update.","message":"The `google-api-python-client-stubs` library is independently maintained and not officially affiliated with Google. Its release cycle can be infrequent.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'affili':46 'api':2,15,56 'autocomplet':28 'automat':34 'base':36 'check':21 'client':4,17,57 'cloud':66 'discoveri':40,63 'document':41 'enabl':19 'generat':35 'googl':1,14,38,48,55,65 'google-api-python-cli':13 'google-cloud':64 'hint':61 'ide':30 'improv':27 'infrequ':54 'librari':18 'like':24 'mypi':25,62 'offici':45 'packag':7 'provid':8 'python':3,16 'releas':51 'stub':5,10,32,58 'tool':23 'type':9,20,60 'type-hint':59","created_at":"2026-04-11T01:31:35.268784+00:00","updated_at":"2026-04-16T15:18:39.576268+00:00","problems":[{"fix":"Install the `google-api-python-client` library: `pip install google-api-python-client`","cause":"The `google-api-python-client-stubs` package provides type hints for the `google-api-python-client` library, but it does not install the core library itself. This error occurs when the main `google-api-python-client` package is not installed in your environment.","error":"ModuleNotFoundError: No module named 'googleapiclient'"},{"fix":"Ensure `google-api-python-client-stubs` is installed (`pip install google-api-python-client-stubs`). If the error persists, check your `mypy` configuration (e.g., `MYPYPATH` environment variable) to ensure it can find the installed packages. For projects, `mypy` typically works best when run from the project root.","cause":"This error occurs when `mypy` cannot locate the type stubs for the `google-api-python-client` library, even if `google-api-python-client-stubs` is installed. This can be due to `mypy`'s import resolution path not including the location of the installed stubs, or an incorrect `MYPYPATH` configuration.","error":"mypy: Cannot find implementation or library stub for module"},{"fix":"When using types from the stubs for explicit annotations, you must ensure they are only evaluated during type checking. Use `from __future__ import annotations` (for Python 3.7+) or import types within an `if typing.TYPE_CHECKING:` block, and surround annotations with quotes. For example:\n```python\nfrom __future__ import annotations # Or use quotes around type hints\nimport typing\n\nif typing.TYPE_CHECKING:\n    from googleapiclient._apis.sheets.v4.resources import SheetsResource\n\ndef get_sheets_service() -> SheetsResource:\n    # ... build and return service\n    pass\n```","cause":"The types provided by `google-api-python-client-stubs` (like `SheetsResource`, `DriveResource`, `TypedDict`s for requests/responses) are *only* for static type checking and do not exist at runtime in the actual `google-api-python-client` library. Directly importing and using these types in your Python code without proper guards will lead to a `NameError` or similar runtime errors.","error":"NameError: name 'SheetsResource' is not defined"},{"fix":"This is generally safe to ignore as long as the imports are exclusively for type-checking. You can suppress this diagnostic in your `pyrightconfig.json` or `settings.json` (for Pylance) if it causes too much noise. For example, in `pyrightconfig.json`:\n```json\n{\n    \"reportMissingModuleSource\": \"none\"\n}\n```","cause":"Pyright/Pylance may report `reportMissingModuleSource` when importing stub-only types (e.g., from `googleapiclient._apis`). This happens because the stub files (`.pyi`) exist, but there's no corresponding runtime `.py` file for those specific type-checking-only modules.","error":"reportMissingModuleSource error (Pyright/Pylance)"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.40.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":"https://pypi.org/project/google-api-python-client-stubs/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["type-stubs","gcp"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-28","next_check":"2026-07-28","install_tag":null}}