Skip to main content

FastProto

Fast, Pythonic Protocol Buffers — messages are plain, readable @dataclass types, with all encoding and decoding handled by a compiled Rust core.

Google's Python protobuf generates opaque classes full of getters/setters and a reflection API you have to learn. FastProto instead generates clean dataclasses you can construct, compare, and repr() like any other — and does the wire work in Rust.

  • Idiomatic messages — generated code is a @dataclass with plain annotations (str, int, list[...], dict[...], | None); autocomplete, type checkers, and repr() all just work.
  • Rust wire codec — encode/decode run in Rust via PyO3, not pure Python.
  • Wire-compatible — bytes interoperate both ways with Google's reference protobuf runtime.
  • Standard toolchain — ships a protoc plugin; just add --fastproto_out.

Install

pip install fastproto            # runtime (Python 3.12+)
pip install "fastproto[plugin]"  # + the protoc code generator

Code generation also needs the protoc compiler itself — install it from your package manager (brew install protobuf, apt install protobuf-compiler) or the official releases.

Quick start

1. Define user.proto:

syntax = "proto3";
package example;

enum Role {
  ROLE_UNSPECIFIED = 0;
  ROLE_ADMIN = 1;
  ROLE_USER = 2;
}

message Address {
  string city = 1;
  string street = 2;
}

message User {
  int64 id = 1;
  string name = 2;
  optional string email = 3;
  Role role = 4;
  repeated string tags = 5;
  Address address = 6;
  map<string, int32> counters = 7;

  oneof contact {
    string phone = 8;
    string telegram = 9;
  }
}

2. Generate with protoc:

protoc --proto_path=. --fastproto_out=. user.proto

This writes user_pb.py — a plain, readable dataclass module:

# @generated by fastproto. DO NOT EDIT.
# source: user.proto
# pyright: reportUnknownVariableType=false
from dataclasses import dataclass, field
from enum import IntEnum

from fastproto import Message, Scalar, message


class Role(IntEnum):
    ROLE_UNSPECIFIED = 0
    ROLE_ADMIN = 1
    ROLE_USER = 2


_ADDRESS_DESCRIPTOR = bytes.fromhex("...")  # @generated (bytes elided)


@message(_ADDRESS_DESCRIPTOR)
@dataclass(slots=True)
class Address(Message):
    city: Scalar.String = ""
    street: Scalar.String = ""


_USER_DESCRIPTOR = bytes.fromhex("...")  # @generated (bytes elided)


@message(_USER_DESCRIPTOR)
@dataclass(slots=True)
class User(Message):
    id: Scalar.Int64 = 0
    name: Scalar.String = ""
    email: Scalar.String | None = None
    role: Role = Role(0)
    tags: list[Scalar.String] = field(default_factory=list)
    address: "Address | None" = None
    counters: dict[Scalar.String, Scalar.Int32] = field(default_factory=dict)
    phone: Scalar.String | None = None
    telegram: Scalar.String | None = None

3. Use it like any dataclass:

from user_pb import Address, Role, User

user = User(
    id=42,
    name="Ada",
    role=Role.ROLE_ADMIN,
    tags=["vip", "beta"],
    address=Address(city="London", street="Baker St"),
    counters={"logins": 7},
)

data = user.to_bytes()               # serialize to protobuf wire bytes
assert User.from_bytes(data) == user  # and back

No SerializeToString() / ParseFromString() ceremony and no reflection — just to_bytes() / from_bytes() on a dataclass you can build, compare, and print.

Type mapping

  • Each proto scalar maps to an alias under fastproto.Scalar. An alias is just the underlying Python type (int, str, ...) tagged with Annotated[...], so it type-checks as the base type while still recording the exact wire type.

    proto Python proto Python
    double Scalar.Double fixed32 Scalar.Fixed32
    float Scalar.Float fixed64 Scalar.Fixed64
    int32 Scalar.Int32 sfixed32 Scalar.SFixed32
    int64 Scalar.Int64 sfixed64 Scalar.SFixed64
    uint32 Scalar.UInt32 bool Scalar.Bool
    uint64 Scalar.UInt64 string Scalar.String
    sint32 Scalar.SInt32 bytes Scalar.Bytes
    sint64 Scalar.SInt64
  • Composite fields: repeated T → list[T], map<K, V> → dict[K, V], enum → IntEnum, and optional / message / oneof fields → T | None.

  • Well-known types map to native objects: google.protobuf.Timestamp → datetime, Duration → timedelta; the rest (Any, Struct, wrappers, ...) are plain dataclasses in fastproto.wellknown.

  • Nested message / enum definitions generate as nested classes at any depth (Outer.Inner, Outer.Color), so the Python structure mirrors the .proto.

  • Multi-file schemas work — import in a .proto becomes an import between the generated modules.

Semantics

  • Presence (proto3): plain scalars use their zero value and are not nullable; optional scalars, message fields, and oneof members are T | None and track explicit presence (a set empty string is distinct from unset). An all-default message encodes to b"".
  • oneof: members are plain optional fields; setting more than one raises ValueError at encode time. msg.which_oneof("group") returns the name of the set member (or None), like google's WhichOneof.
  • Open enums (proto3): an enum value not defined in your schema decodes to a plain int (like google's runtime) and survives re-encoding.
  • Repeated message merge: not performed. If a singular message field appears more than once on the wire, the last occurrence wins (google merges the submessages field-by-field). A wire-compat caveat for concatenated streams.
  • Unknown fields: fields your schema doesn't know are preserved verbatim across decode → encode (forward compatibility). They are invisible to __init__ / repr / ==. Exception: proto2 group wire types can't be skipped, so a message containing one raises ValueError on decode.
  • Strict types at the boundary: field values are taken as-is — bool does not accept int, str and bytes don't interconvert, and a repeated field must be a real list (a bare str/bytes is rejected, not iterated char-by-char). An out-of-range integer raises OverflowError on encode. from_bytes takes bytes (not yet bytearray / memoryview).
  • Nesting limit: messages deeper than 100 levels — or a cyclic object graph on encode — raise ValueError instead of exhausting the stack.
  • Timestamps: decoded datetimes are aware UTC; naive ones encode as UTC. protobuf's sub-microsecond precision (nanos) is truncated to microseconds.
  • References: sibling, self, nested, and enum references resolve lazily on the first to_bytes() / from_bytes() — nothing for you to wire up.
  • Dicts: you can create a message object by using from_dict() method. Also there is a possibility to convert a message to python dict object by using to_dict() method.
empty = User()
assert empty.to_bytes() == b"" and empty.email is None
assert User(phone="1").which_oneof("contact") == "phone"
User(phone="1", telegram="a").to_bytes()  # ValueError: ... oneof ...

Performance

Protobuf runtimes pay the cost of turning bytes into Python objects either at decode time or at access time, so decode-only microbenchmarks tell half the story. Google's default backend (upb) parses into C structs and converts to Python lazily — decoding looks instant, but every field access pays a C-to-Python conversion, every time. FastProto materializes plain Python values once at decode; after that a field read is an ordinary attribute load.

On a mid-size message (509 B: strings, nested messages, maps, repeated fields, enums — Apple M-series, CPython 3.14):

scenario fastproto google protobuf (upb)
decode only 4.3 µs 1.9 µs
decode, then read every field 5.9 µs 8.9 µs
read every field of a decoded message 1.5 µs 6.7 µs
encode 2.4 µs 0.9 µs

So: if you decode messages and barely look inside (relays, routers), upb's lazy model wins the raw numbers. The moment you use what you decoded, the conversion bill comes due on their side — and it comes due again on every re-read — while FastProto's fields are just dataclass attributes. The encode gap is the honest price of that interface: FastProto reads live attributes off a plain Python object, upb serializes C memory it already owns. That price buys messages your editor, type checker, and repr() treat as ordinary dataclasses.

Contributing

See CONTRIBUTING.md for setup, project layout, and the release flow.

License

MIT

Metadata

Release files for fastproto 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fastproto 1.0.0
File Size Uploaded Provenance Actions
fastproto-1.0.0.tar.gz 126.0 kB With provenance Details for fastproto-1.0.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for fastproto 1.0.0
File Actions
fastproto-1.0.0-cp312-abi3-win_amd64.whl CPython 3.12 abi3 Windows x86-64 Details for fastproto-1.0.0-cp312-abi3-win_amd64.whl
fastproto-1.0.0-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.12 abi3 Linux glibc 2.17+ x86-64 Details for fastproto-1.0.0-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
fastproto-1.0.0-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl CPython 3.12 abi3 Linux glibc 2.17+ ARM64 Details for fastproto-1.0.0-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
fastproto-1.0.0-cp312-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl CPython 3.12 abi3 macOS 10.12+ x86-64, macOS 11.0+ ARM64, macOS 10.12+ universal2 (ARM64, x86-64) Details for fastproto-1.0.0-cp312-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl

Total release size: 1.6 MB

Release files / fastproto-1.0.0.tar.gz

Download URL fastproto-1.0.0.tar.gz
Size 126.0 kB
Tags Source
SHA-256 checksum
How to use checksums
39ec32b28434cf743710c5b0c706cd3803d406a45111f63df3ad980b4fc29ee0
BLAKE2b-256 checksum
How to use checksums
74ebb6b0fee14fee91db60c21e434db82e7955d30704c72dc34b7f5fc1847de1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.

Transparency log

Release files / fastproto-1.0.0-cp312-abi3-win_amd64.whl

Download URL fastproto-1.0.0-cp312-abi3-win_amd64.whl
Size 214.4 kB
Tags CPython 3.12 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
9e4bbe3bd0c8cf10a57b9ed060446995cd47a3e4fd06a181b3a1538d57c3248f
BLAKE2b-256 checksum
How to use checksums
2b5fdcbdee7134c31130f2c32eee11687f4c3c8b8b9af4c885570b590989762a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.

Transparency log

Release files / fastproto-1.0.0-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL fastproto-1.0.0-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 333.1 kB
Tags CPython 3.12 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
219eaa95668513c6c6aca9a44832b7a46b93f86f7c3c0ba7d6a0e4191dfd7136
BLAKE2b-256 checksum
How to use checksums
efff6cb258845173e8a3139d31cb4efaff910f30804220e5ec27134e64a56d3e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.

Transparency log

Release files / fastproto-1.0.0-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL fastproto-1.0.0-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 331.3 kB
Tags CPython 3.12 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
6e230e583a065d686618284f67dd0a8e988a945407772288a18aad5271e63da3
BLAKE2b-256 checksum
How to use checksums
58775a5aeda43efa3bde4107ac5e94cf4676b46b20ed68285e6d082ddfb9473b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.

Transparency log

Release files / fastproto-1.0.0-cp312-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl

Download URL fastproto-1.0.0-cp312-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Size 593.5 kB
Tags CPython 3.12 abi3 macOS 10.12+ universal2 (ARM64, x86-64) macOS 10.12+ x86-64 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
c9c9488139daef0d64a1d9c7ac21aaa408dc43d0f16aceb05c6cf9250fa565ea
BLAKE2b-256 checksum
How to use checksums
1b282277e2945247ad2852eaccc9c30ebd6e9fd9aa38e9534d0aadb7c39d9c33
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.

Transparency log

Security for fastproto 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 5 files in this release have been uploaded with provenance metadata.

Select from 5 files

Attestation for fastproto-1.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 2, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page