{"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":"en","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,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}