Python

The Buf Schema Repository (BSR) provides generated SDKs for Python in the form of a PEP 503-compatible repository. You can consume generated SDKs from modules and plugins using dependency management tools like pip. It generates SDKs automatically when you push schema changes, which eliminates the need to manage a Protobuf toolchain or generate code locally.

Setup using `pip`

pip is configured to use the Python Package Index by default. To use Buf's Python repository with pip, you can either specify --extra-index-url https://buf.build/gen/python in all of your pip invocations, or configure pip to include the argument by default:

pip.conf

[global]
extra-index-url = https://buf.build/gen/python

Private generated SDKs

When using SDKs generated from private BSR repositories, you need to authenticate by including a personal API token for local use or a Bot user's API token for CI workflows. See the Authentication page for instructions.

Installing generated SDKs

To install a generated SDK, use pip install and reference the SDK name. For example, to install the connectrpc/eliza Protobuf module using the protocolbuffers/python plugin, you could install the generated SDK like this:

$ pip install connectrpc-eliza-protocolbuffers-python

See the names and versions section for syntax specifics.

Importing from SDKs

In general, Python Protobuf plugins generate code that matches the package structure of their input Protobuf files, so having your import path match the package structure of your Protobuf files should work. For example, to import from the connectrpc-eliza-protocolbuffers-python package generated from the buf.build/connectrpc/eliza module, the path would look like this:

from connectrpc.eliza.v1.eliza_pb2 import SayRequest

Names and versions

The BSR Python repository has a special syntax for SDK names:

{moduleOwner}-{moduleName}-{pluginOwner}-{pluginName}

For example, the SDK name connectrpc-eliza-protocolbuffers-python contains code for the connectrpc/eliza module using the protocolbuffers/python plugin.

Versions

To discover SDK versions for the Python repository, you can browse a repository's generated SDK page, which has installation instructions and an interactive UI for selecting SDK versions.

Full syntax

{pluginVersion}.{pluginRevision}.{commitTimestamp}+{commitShortName}

As an example:

25.0.0.3.20231106214313+d8fbf2620c60

That represents:

Plugin version: 25.0.0
Plugin revision: 3
Commit timestamp: 20231106214313
Commit short name: d8fbf2620c60

For commits on branches, the commit timestamp component of the version is always dev, to easily differentiate SDK versions using commits on branches that aren't main.

Other package managers

Because the BSR Python repository implements PEP 503, you should be able to use it with package management tools outside of pip, such as poetry, pipenv, conda and others.

Available plugins

For a full list of supported plugins, navigate to the BSR plugins page and search for Python.

To learn more about how these plugins are packaged and distributed, go to the bufbuild/plugins repository. If you find a useful plugin that should be added, please file an issue!

Try the generated SDKs tutorial to learn how to generate SDKs from the BSR.