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.1

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.1
File Size Uploaded Provenance Actions
fastproto-1.0.1.tar.gz 136.9 kB With provenance Details for fastproto-1.0.1.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for fastproto 1.0.1
File Actions
fastproto-1.0.1-cp312-abi3-win_amd64.whl CPython 3.12 abi3 Windows x86-64 Details for fastproto-1.0.1-cp312-abi3-win_amd64.whl
fastproto-1.0.1-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.1-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
fastproto-1.0.1-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl CPython 3.12 abi3 Linux glibc 2.17+ ARM64 Details for fastproto-1.0.1-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
fastproto-1.0.1-cp312-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl CPython 3.12 abi3 macOS 10.12+ universal2 (ARM64, x86-64), macOS 10.12+ x86-64, macOS 11.0+ ARM64 Details for fastproto-1.0.1-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.1.tar.gz

Download URL fastproto-1.0.1.tar.gz
Size 136.9 kB
Tags Source
SHA-256 checksum
How to use checksums
fbabc4be963d5d9cded29f421e4e76de113f57fee6e6e240d859a8b0d054c901
BLAKE2b-256 checksum
How to use checksums
2803c5931073d29a86b27f3acf13389e18f3a71df078c097271936c5bc03246e
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.1-cp312-abi3-win_amd64.whl

Download URL fastproto-1.0.1-cp312-abi3-win_amd64.whl
Size 211.0 kB
Tags CPython 3.12 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
a6e5838e10d070db76430d9730c57d9fea634d66211d94564837a15a6f5eeaf0
BLAKE2b-256 checksum
How to use checksums
ba503101177b309d4dc6c76abe5d19e537422db47491293a72d06fd5ab591ed6
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.1-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL fastproto-1.0.1-cp312-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 333.0 kB
Tags CPython 3.12 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
564bb58b0f2cd9bd39a77aaea1b23863843406ab9d1229d9399933a7ef64c3a5
BLAKE2b-256 checksum
How to use checksums
25439eeacf25726bb74aaac8cc58f4e183f79731db4facd6efe37cbf3f6f08a0
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.1-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL fastproto-1.0.1-cp312-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 331.6 kB
Tags CPython 3.12 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
f632a6951413b9a29ea2bc180c897308679e35e79a6d3bd979943290fd62e71c
BLAKE2b-256 checksum
How to use checksums
df7fd6cf943d06512c50c61bfe5c080f40015243d69f491a2a995bb93043695b
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.1-cp312-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl

Download URL fastproto-1.0.1-cp312-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
Size 590.1 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
7fef59fa068b579286c313ca64cf7a56a6fb766ac8dedddd32c0013e15648ea7
BLAKE2b-256 checksum
How to use checksums
1d3bef9679484691299b1b2ca4e10256bac393d9cbe554b0905cf6dd698fa46f
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.1

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.1.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