Wrapping Guide

This guide explains how to build safe, idiomatic Python wrappers out of the low-level protobuf message bindings generated by protobuf/gRPC, along with the repository conventions that keep those wrappers coherent. Callers work with stable Python types. The conversion functions keep generated protobuf details inside the versioned packages that need them.

Use this guide when you add a wrapper or change an existing one. It starts with package structure, then covers enums, data types, validity, and conversion functions. It ends with the tests that keep those choices working. The User Guide explains how callers use the wrapper types, and the Client Developer Guide explains how client libraries call conversion functions and return the wrappers.

Sections

• Organizing a wrapper package — Explains where public wrapper types and version-specific conversion functions belong. Use it to keep generated protobuf imports out of public type modules.
• Enums — Shows when a protobuf enum should become a boolean, a class hierarchy, or a public Python enum. It also shows how to keep unrecognized values.
• Data types — Covers immutable wrapper objects, typed identifiers, and numeric annotations that match Python's runtime behavior.
• Validity in the type — Explains how to represent valid, invalid, missing, and unknown values without dropping received data.
• Conversion functions — Explains how to write the *_from_proto and *_to_proto functions that translate protobuf messages to wrapper types.
• Deprecation and compatibility — Describes how to replace public functions and tighten validation without surprising callers.
• Testing — Shows how to place tests, check enum parity, and make documentation examples and warnings part of the test suite.