Skip to content

fastgrpc

FastAPI-style gRPC for Python. Define services with type-annotated Python; get the protobuf schema, generated stubs, and a running server automatically.

from dataclasses import dataclass
from fastgrpc import rpc, service

@dataclass
class User:
    id: int
    name: str

@service
class UserService:
    @rpc
    async def get_user(self, user_id: int) -> User:
        return User(id=user_id, name="Ashesh")

fastgrpc dev main.py

Call it from any gRPC client. Reflection is enabled in dev mode, so grpcurl works out of the box:

grpcurl -plaintext -d '{"user_id": 42}' \
  127.0.0.1:50051 fastgrpc.UserService/GetUser
# {"id": "42", "name": "Ashesh"}

Why fastgrpc

Writing gRPC services in Python today means writing .proto files by hand, running protoc, importing the generated stubs, subclassing the generated servicer, wiring methods together, and managing the build pipeline yourself. fastgrpc collapses all of that into one decorator.

Without fastgrpc With fastgrpc
Hand-write .proto files Inferred from Python types
Run protoc manually Automatic on every reload
Subclass *Servicer, override methods @service + @rpc
Convert dataclass↔proto by hand Recursive auto-conversion
No hot reload Watchfiles-backed reload, including transitive imports
Choose sync or async server upfront Auto-detected from handler signatures

Features

  • Zero-boilerplate service definition — @service on a class, @rpc on methods.
  • Automatic protobuf generation from Python type hints, including nested dataclasses, Optional, list[T], dict[str, T], and AsyncIterator[T].
  • Wire compatibility guarantees via a committed .fastgrpc.lock file that pins protobuf field numbers across releases.
  • Sync and async servers, auto-selected from your handler signatures.
  • All four streaming modes (unary-unary, unary-stream, stream-unary, stream-stream).
  • Hot reload that follows transitive imports, powered by a Rust file watcher.
  • gRPC server reflection enabled in dev mode — grpcurl and Postman just work.

Next steps

  • Quickstart — build and run your first service in under five minutes.
  • Guides — deep-dives into watch mode, streaming, async/sync selection, the lock file, and multi-file projects.
  • CLI reference — every command, every flag.
  • API reference — decorators, App configuration, exception types.

Status

Alpha. The core pipeline (codegen, lock-file management, sync/async runtimes, hot reload, multi-file projects) is implemented and covered by tests. TLS, OpenTelemetry tracing, and HTTP/JSON transcoding are on the roadmap.