Google API Common Protos Type Stubs

2.3.1 · active · verified Thu Apr 16

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.

Common errors

```
Mypy error: Cannot find module 'google.protobuf.timestamp_pb2'
```
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.

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.
```
Mypy error: Namespace package 'google' not found without --namespace-packages
```
cause After version 2.0.0, `googleapis-common-protos-stubs` uses namespace packages. Mypy requires explicit configuration to correctly resolve imports within namespace packages.

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`.
```
Mypy error: Name 'Timestamp' is not defined (or similar name resolution error for common proto types)
```
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.

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`).

Warnings

breaking 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.
Fix: Run Mypy with the `--namespace-packages` command-line option, or add `namespace_packages = true` to your `mypy.ini` or `pyproject.toml` configuration file.
gotcha 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`.
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.
gotcha 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.
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.

Install

pip install googleapis-common-protos-stubs Install latest version

Imports

Timestamp
```
from google.protobuf.timestamp_pb2 import Timestamp
```
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.
FieldMask
```
from google.protobuf.field_mask_pb2 import FieldMask
```
Similar to `Timestamp`, `FieldMask` is a common proto type. The stubs ensure type checkers can validate usage of such types.

Quickstart

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.

import os
import subprocess

# A simple Python file using a common proto type
python_code = '''
from google.protobuf.timestamp_pb2 import Timestamp
from datetime import datetime

def create_timestamp_message(dt: datetime) -> Timestamp:
    timestamp = Timestamp()
    timestamp.FromDatetime(dt)
    return timestamp

def get_seconds(ts: Timestamp) -> int:
    return ts.seconds # type: ignore [attr-defined]

# Example usage (not type-checked for this demo, just for context)
# now = datetime.now()
# ts_msg = create_timestamp_message(now)
# print(f"Created Timestamp: {ts_msg.seconds}.{ts_msg.nanos}")
'''

with open('my_proto_app.py', 'w') as f:
    f.write(python_code)

# Run mypy with --namespace-packages to type-check
try:
    # Using `--namespace-packages` is crucial since v2.0.0 of the stubs
    result = subprocess.run(['mypy', '--namespace-packages', 'my_proto_app.py'], capture_output=True, text=True, check=True)
    print("Mypy successful:")
    print(result.stdout)
    print("Note: 'type: ignore' used for demonstration; in real code, you'd fix type errors.")
except subprocess.CalledProcessError as e:
    print(f"Mypy failed with errors:\n{e.stderr}")
finally:
    os.remove('my_proto_app.py')

view raw JSON →