1# Protocol Buffers Python 2 3This directory contains the Protobuf library for Python. 4 5For user documentation about how to use Protobuf Python, see 6https://protobuf.dev/getting-started/pythontutorial/ 7 8# Installation 9 10In most cases you should install the library using `pip` or another package 11manager: 12 13``` 14$ pip install protobuf 15``` 16 17The packages released on https://pypi.org/project/protobuf/#files include both a 18source distribution and binary wheels. 19 20## Building packages from this repo 21 22If for some reason you wish to build the packages directly from this repo, you 23can use the following Bazel commands: 24 25``` 26$ bazel build //python/dist:source_wheel 27$ bazel build //python/dist:binary_wheel 28``` 29 30The binary wheel will build against whatever version of Python is installed on 31your system. The source package is always the same and does not depend on a 32local version of Python. 33 34## Building from `setup.py` 35 36We support building from `setup.py`, but only from a Python source package. 37You cannot build from `setup.py` using the GitHub repo or the GitHub source 38tarball. 39 40To build a source package from this repo, see the instructions in the previous 41section. 42 43# Implementation backends 44 45There are three separate implementations of Python Protobuf. All of them offer 46the same API and are thus functionally the same, though they have very different 47performance characteristics. 48 49The runtime library contains a switching layer that can choose between these 50backends at runtime. Normally it will choose between them automatically, using 51priority-ordered list, and skipping any backends that are not available. However 52you can request a specific backend by setting the 53`PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION` environment variable to one of the 54following values: 55 561. **upb**: Built on the 57 [upb C library](https://github.com/protocolbuffers/protobuf/tree/main/upb), 58 this is a new extension module 59 [released in 4.21.0](https://protobuf.dev/news/2022-05-06/). It offers 60 better performance than any of the previous backends, and it is now the 61 default. It is distributed in our PyPI packages, and requires no special 62 installation. The code for this module lives in this directory. 631. **cpp**: This extension module wraps the C++ protobuf library. It is 64 deprecated and is no longer released in our PyPI packages, however it is 65 still used in some legacy cases where apps want to perform zero-copy message 66 sharing between Python and C++. It must be installed separately before it 67 can be used. The code for this module lives in 68 [google/protobuf/pyext](https://github.com/protocolbuffers/protobuf/tree/main/python/google/protobuf/pyext). 691. **python**: The pure-Python backend, this does not require any extension 70 module to be present on the system. The code for the pure-Python backend 71 lives in [google/protobuf/internal](google/protobuf/internal) 72 73The order given above is the general priority order, with `upb` being preferred 74the most and the `python` backend preferred the least. However this ordering can 75be overridden by the presence of a 76`google.protobuf.internal._api_implementation` module. See the logic in 77[api_implementation.py](https://github.com/protocolbuffers/protobuf/blob/main/python/google/protobuf/internal/api_implementation.py) 78for details. 79 80You can check which backend you are using with the following snippet: 81 82``` 83$ python 84Python 3.10.9 (main, Dec 7 2022, 13:47:07) [GCC 12.2.0] on linux 85Type "help", "copyright", "credits" or "license" for more information. 86>>> from google.protobuf.internal import api_implementation 87>>> print(api_implementation.Type()) 88upb 89``` 90 91This is not an officially-supported or stable API, but it is useful for ad hoc 92diagnostics. 93 94More information about sharing messages between Python and C++ is available 95here: https://protobuf.dev/reference/python/python-generated/#sharing-messages 96 97# Code generator 98 99The code for the Protobuf Python code generator lives in 100[//src/google/protobuf/compiler/python](https://github.com/protocolbuffers/protobuf/tree/main/src/google/protobuf/compiler/python). 101The code generator can output two different files for each proto `foo.proto`: 102 103* **foo_pb2.py**: The module you import to actually use the protos. 104* **foo_pb2.pyi**: A stub file that describes the interface of the protos. 105 106The `foo_pb2.pyi` file is useful for IDEs or for users who want to read the 107output file. The `foo_pb2.py` file is optimized for fast loading and is not 108readable at all. 109 110Note that the pyi file is only generated if you pass the `pyi_out` option to 111`protoc`: 112 113``` 114$ protoc --python_out=pyi_out:output_dir 115``` 116