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:
Private generated SDKs
pip
supports .netrc authentication.
To set up your .netrc with your BSR credentials, run buf registry login
.
For more information, check out our authentication docs.
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:
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:
Names and versions
The BSR Python repository has a special syntax for SDK names:
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
As an example:
That represents:
- Plugin version:
25.0.0
- Plugin revision:
3
- Commit timestamp:
20231106214313
- Commit short name:
d8fbf2620c60
If you need a more specific version than the latest, such as needing to install a specific plugin version, you can use the buf registry sdk version
command.
The BSR supports commits on labels. This feature enables you to push unreleased Protobuf file changes and consume generated code without affecting the default label.
Only commits that are on the default label at the time they're pushed to the BSR have populated timestamps.
Timestamps on commits pushed to other labels are set to dev
to easily distinguish them as changes in labels that are still in development.
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 you think should be added, please file an issue.
Related docs
- Try the generated SDKs tutorial to learn how to generate SDKs from the BSR.