This directory contains the Protobuf library for Python.
In most cases you should install the library using
pip or another package manager:
$ pip install protobuf
The packages released on https://pypi.org/project/protobuf/#files include both a source distribution and binary wheels.
For user documentation about how to use Protobuf Python, see https://protobuf.dev/getting-started/pythontutorial/
If for some reason you wish to build the packages directly from this repo, you can use the following Bazel commands:
$ bazel build @upb//python/dist:source_wheel $ bazel build @upb//python/dist:binary_wheel
The binary wheel will build against whatever version of Python is installed on your system. The source package is always the same and does not depend on a local version of Python.
There are three separate implementations of Python Protobuf. All of them offer the same API and are thus functionally the same, though they have very different performance characteristics.
The runtime library contains a switching layer that can choose between these backends at runtime. Normally it will choose between them automatically, using priority-ordered list, and skipping any backends that are not available. However you can request a specific backend by setting the
PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION environment variable to one of the following values:
The order given above is the general priority order, with
upb being preferred the most and the
python backend preferred the least. However this ordering can be overridden by the presence of a
google.protobuf.internal._api_implementation module. See the logic in api_implementation.py for details.
You can check which backend you are using with the following snippet:
$ python Python 3.10.9 (main, Dec 7 2022, 13:47:07) [GCC 12.2.0] on linux Type "help", "copyright", "credits" or "license" for more information. >>> from google.protobuf.internal import api_implementation >>> print(api_implementation.Type()) upb
This is not an officially-supported or stable API, but it is useful for ad hoc diagnostics.
More information about sharing messages between Python and C++ is available here: https://protobuf.dev/reference/python/python-generated/#sharing-messages
The code for the Protobuf Python code generator lives in //src/google/protobuf/compiler/python. The code generator can output two different files for each proto
foo_pb2.pyi file is useful for IDEs or for users who want to read the output file. The
foo_pb2.py file is optimized for fast loading and is not readable at all.
Note that the pyi file is only generated if you pass the
pyi_out option to
$ protoc --python_out=pyi_out:output_dir