{"id":7271,"library":"googleapis-common-protos-stubs","title":"Google API Common Protos Type Stubs","description":"The `googleapis-common-protos-stubs` library provides PEP 561-compliant type stubs for the `googleapis-common-protos` Python package. It enables static type checking tools like Mypy to understand the types provided by Google's common protocol buffer definitions, which are widely used across Google API services. The current version is 2.3.1, and it maintains an active release cadence, often aligning with updates to the underlying `googleapis-common-protos` or `mypy-protobuf` toolchain.","status":"active","version":"2.3.1","language":"en","source_language":"en","source_url":"https://github.com/henribru/googleapis-common-protos-stubs","tags":["typing","stubs","protobuf","mypy","google-cloud","type-checking"],"install":[{"cmd":"pip install googleapis-common-protos-stubs","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"This package provides type stubs for `googleapis-common-protos`, so it is typically used in conjunction with the runtime library.","package":"googleapis-common-protos","optional":false},{"reason":"This package is a dependency for its own internal type checking and stub generation process, providing stubs for the core `protobuf` library.","package":"types-protobuf","optional":false}],"imports":[{"note":"Users import protocol buffer types directly from the `google.protobuf.*` or `google.api.*` modules (provided by `googleapis-common-protos`). This stub package provides the type definitions for static analysis without altering runtime behavior.","symbol":"Timestamp","correct":"from google.protobuf.timestamp_pb2 import Timestamp"},{"note":"Similar to `Timestamp`, `FieldMask` is a common proto type. The stubs ensure type checkers can validate usage of such types.","symbol":"FieldMask","correct":"from google.protobuf.field_mask_pb2 import FieldMask"}],"quickstart":{"code":"import os\nimport subprocess\n\n# A simple Python file using a common proto type\npython_code = '''\nfrom google.protobuf.timestamp_pb2 import Timestamp\nfrom datetime import datetime\n\ndef create_timestamp_message(dt: datetime) -> Timestamp:\n    timestamp = Timestamp()\n    timestamp.FromDatetime(dt)\n    return timestamp\n\ndef get_seconds(ts: Timestamp) -> int:\n    return ts.seconds # type: ignore [attr-defined]\n\n# Example usage (not type-checked for this demo, just for context)\n# now = datetime.now()\n# ts_msg = create_timestamp_message(now)\n# print(f\"Created Timestamp: {ts_msg.seconds}.{ts_msg.nanos}\")\n'''\n\nwith open('my_proto_app.py', 'w') as f:\n    f.write(python_code)\n\n# Run mypy with --namespace-packages to type-check\ntry:\n    # Using `--namespace-packages` is crucial since v2.0.0 of the stubs\n    result = subprocess.run(['mypy', '--namespace-packages', 'my_proto_app.py'], capture_output=True, text=True, check=True)\n    print(\"Mypy successful:\")\n    print(result.stdout)\n    print(\"Note: 'type: ignore' used for demonstration; in real code, you'd fix type errors.\")\nexcept subprocess.CalledProcessError as e:\n    print(f\"Mypy failed with errors:\\n{e.stderr}\")\nfinally:\n    os.remove('my_proto_app.py')\n","lang":"python","description":"To quickly verify `googleapis-common-protos-stubs` is working, create a Python file that imports a common protobuf type (e.g., `Timestamp`). Then, run `mypy` on this file, ensuring you include the `--namespace-packages` flag. This flag is critical for `mypy` to correctly discover types within the namespace package structure used by the stubs since version 2.0.0. The example demonstrates a simple function using `Timestamp` and the `mypy` command to check it."},"warnings":[{"fix":"Run Mypy with the `--namespace-packages` command-line option, or add `namespace_packages = true` to your `mypy.ini` or `pyproject.toml` configuration file.","message":"Version 2.0.0 of `googleapis-common-protos-stubs` introduced the use of namespace packages. This change requires Mypy users to explicitly enable namespace package support for correct type checking.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure `googleapis-common-protos` is installed and import types like `from google.protobuf.timestamp_pb2 import Timestamp`. The `googleapis-common-protos-stubs` package provides the necessary type hints for static analysis.","message":"This package provides *type stubs* (`.pyi` files) for `googleapis-common-protos`, not the runtime Python classes themselves. You should `import` the protobuf types from the `google.protobuf` or `google.api` namespace provided by the `googleapis-common-protos` package, not directly from `googleapis_common_protos_stubs`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your Mypy version is up-to-date. If encountering issues related to missing type information after updating to 2.3.1, verify Mypy is configured correctly for namespace packages as per the v2.0.0 breaking change.","message":"The package removed `__init__.pyi` and `py.typed` files in version 2.3.1. While this is likely a correction for PEP 420 namespace package compliance, older versions of Mypy or specific tooling might expect these files for type stub discovery.","severity":"gotcha","affected_versions":">=2.3.1"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install `googleapis-common-protos-stubs` via `pip install googleapis-common-protos-stubs`. Also ensure `mypy` is run with `--namespace-packages` if using v2.0.0 or later of the stubs.","cause":"Mypy cannot find the type definitions for the `google.protobuf` module. This often means the `googleapis-common-protos-stubs` package is not installed or not discoverable by Mypy.","error":"Mypy error: Cannot find module 'google.protobuf.timestamp_pb2'"},{"fix":"Add `--namespace-packages` to your Mypy command line (e.g., `mypy --namespace-packages your_module.py`) or configure it in your `mypy.ini` or `pyproject.toml` file under `[tool.mypy]` with `namespace_packages = true`.","cause":"After version 2.0.0, `googleapis-common-protos-stubs` uses namespace packages. Mypy requires explicit configuration to correctly resolve imports within namespace packages.","error":"Mypy error: Namespace package 'google' not found without --namespace-packages"},{"fix":"Ensure `googleapis-common-protos` is installed (`pip install googleapis-common-protos`). Double-check the import statement for the protobuf type (e.g., `from google.protobuf.timestamp_pb2 import Timestamp`).","cause":"Even with stubs installed, the runtime `googleapis-common-protos` library might be missing, or the import path for the specific protobuf type is incorrect.","error":"Mypy error: Name 'Timestamp' is not defined (or similar name resolution error for common proto types)"}]}