{"id":720,"library":"types-protobuf","title":"Typing stubs for Protobuf","description":"types-protobuf provides type stub files for the `protobuf` (also known as `google-protobuf`) library. It allows type checkers like Mypy or Pyright to perform static analysis on Python code that uses Protocol Buffers, improving code quality and catching potential type errors. This package is part of the `typeshed` project and aims to provide accurate annotations for `protobuf~=6.32.1`.","status":"active","version":"6.32.1.20260221","language":"python","source_language":"en","source_url":"https://github.com/python/typeshed","tags":["typing","stubs","protobuf","typeshed","type-checking"],"install":[{"cmd":"pip install types-protobuf","lang":"bash","label":"Install types-protobuf"}],"dependencies":[{"reason":"Provides runtime functionality for which these stubs offer type hints. The stubs are designed for `protobuf~=6.32.1`.","package":"protobuf","optional":false}],"imports":[{"note":"Imports are typically from the `google.protobuf` runtime library, not directly from `types-protobuf` itself. `types-protobuf` provides the type hints for these imports.","symbol":"Message","correct":"from google.protobuf import message"},{"note":"For well-known types like Timestamp, you import from their specific `_pb2` modules, which are generated by `protoc`.","symbol":"Timestamp","correct":"from google.protobuf.timestamp_pb2 import Timestamp"}],"quickstart":{"code":"import os\nfrom google.protobuf.timestamp_pb2 import Timestamp # A well-known type\n\n# --- Simulate generated _pb2.py content for a custom message ---\n# In a real scenario, this would come from `my_message_pb2.py`\n# generated by `protoc --python_out=. my_message.proto`\n\n# my_message.proto content:\n# syntax = \"proto3\";\n# package mypackage;\n# message MyMessage {\n# string name = 1;\n# int32 id = 2;\n# repeated string tags = 3;\n# }\n\n# Simplified representation for quickstart (type checkers would use real stubs)\nclass MyMessage:\n name: str\n id: int\n tags: list[str]\n\n def __init__(self, name: str = '', id: int = 0, tags: list[str] | None = None) -> None:\n self.name = name\n self.id = id\n self.tags = tags if tags is not None else []\n\n def SerializeToString(self) -> bytes:\n return b\"\"\n\n @classmethod\n def ParseFromString(cls, serialized_data: bytes) -> 'MyMessage':\n return cls()\n# --- End simulated content ---\n\n\ndef process_message(msg: MyMessage) -> str:\n \"\"\"Processes a custom protobuf message with type hints.\"\"\"\n print(f\"Processing Message: Name={msg.name}, ID={msg.id}\")\n return f\"Message with {len(msg.tags)} tags processed.\"\n\ndef get_current_timestamp() -> Timestamp:\n \"\"\"Gets the current UTC timestamp using google.protobuf.Timestamp.\"\"\"\n ts = Timestamp()\n ts.GetCurrentTime()\n return ts\n\n# Example Usage:\nmy_instance = MyMessage(name=\"ExampleUser\", id=42, tags=[\"dev\", \"python\"])\nresult = process_message(my_instance)\nprint(result)\n\ntimestamp_obj = get_current_timestamp()\nprint(f\"Current UTC Timestamp: {timestamp_obj}\")","lang":"python","description":"This quickstart demonstrates how `types-protobuf` provides static type checking for code interacting with `google.protobuf` messages. It includes a simulated custom message type (which would typically be generated from a `.proto` file) and usage of a well-known type. With `types-protobuf` installed, type checkers can verify argument types, attribute access, and return types."},"warnings":[{"fix":"Use a robust schema evolution strategy (e.g., deprecate fields instead of deleting, avoid renumbering, maintain compatibility across versions). Tools like `buf` can help lint `.proto` files for breaking changes.","message":"Changes in `.proto` schema definitions (e.g., field renumbering, removal, or type alteration) can lead to runtime deserialization failures and will cause type checking errors if not properly managed. This is a fundamental aspect of Protobuf evolution, and `types-protobuf` will reflect these underlying API changes.","severity":"breaking","affected_versions":"All versions of protobuf and types-protobuf"},{"fix":"If you encounter missing annotations, consider contributing to the `typeshed` project where `types-protobuf` stubs are maintained. For immediate local fixes, you can use `type: ignore` or local stub files.","message":"`types-protobuf` is a partial stub package, meaning not all annotations for the `protobuf` library might be present. You might encounter `Missing type annotation` errors for some less common parts of the API.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that `types-protobuf` and `protobuf` versions are compatible. Typeshed recommends pinning stub packages to a known good version (e.g., `types-protobuf==X.Y.Z.build`) or aligning version bounds (e.g., `protobuf>=A.B.C,=A.B.C,