Registry /
type-stubs / googleapis-common-protos-stubs
Install & Compatibility
Where this runs
tested against v2.3.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.276s · 42.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.2s · import 0.055s · 41MB
40MB installed
● package 40MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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')
Errors
Common errors & fixes
Mypy error: Cannot find module 'google.protobuf.timestamp_pb2'
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.
fixInstall `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
After version 2.0.0, `googleapis-common-protos-stubs` uses namespace packages. Mypy requires explicit configuration to correctly resolve imports within namespace packages.
fixAdd `--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)
Even with stubs installed, the runtime `googleapis-common-protos` library might be missing, or the import path for the specific protobuf type is incorrect.
fixEnsure `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`).
Upgrade
Version history
2.3.1latest on PyPI · released Jan 28, 2024
Audit
Dependencies
googleapis-common-protosrequiredThis package provides type stubs for `googleapis-common-protos`, so it is typically used in conjunction with the runtime library.
types-protobufrequiredThis package is a dependency for its own internal type checking and stub generation process, providing stubs for the core `protobuf` library.