Muffin-GRPC
Muffin-GRPC is a plugin for the Muffin framework that brings gRPC support to your application. It compiles .proto files, registers generated services on a grpc.aio server and hands out client channels.
Features
📦 Compiles .proto files to Python, including imported dependencies
⚙️ Simplified gRPC server and client integration
🔁 CLI commands to build protos and run the server
🧩 Fixes generated imports so compiled modules are importable as a package
🧪 Built for asyncio and modern Python standards
Requirements
Python >= 3.11
muffin
grpcio
grpcio-tools — used at runtime: the plugin calls grpc_tools.protoc to compile protos
proto-schema-parser — used to read import/package declarations from protos
All of them are installed with pip install muffin-grpc.
Installation
pip install muffin-grpc
# or
uv add muffin-grpc
Quick start
Set up the plugin and attach it to your Muffin application:
from muffin import Application
from muffin_grpc import Plugin as GRPC
app = Application("example")
grpc = GRPC(app, server_listen="[::]:50051")
grpc.add_proto("project_name/proto/helloworld.proto")
Create project_name/proto/helloworld.proto:
syntax = "proto3";
package helloworld;
service Greeter {
rpc SayHello (HelloRequest) returns (HelloReply);
}
message HelloRequest {
string name = 1;
}
message HelloReply {
string message = 1;
}
Compile the proto files (add_proto already did it if autobuild is enabled, see below):
muffin project_name grpc-build
This generates:
helloworld_pb2.py — messages
helloworld_pb2_grpc.py — client stubs and server servicers
helloworld.py — aggregator module, imports from both files above
__init__.py — so the build directory is importable as a package
Implement the Greeter service:
from grpc.aio import ServicerContext
from .proto.helloworld import GreeterServicer, HelloReply, HelloRequest
@grpc.add_to_server
class Greeter(GreeterServicer):
async def SayHello(self, request: HelloRequest, context: ServicerContext) -> HelloReply:
return HelloReply(message=f"Hello, {request.name}!")
Run the gRPC server:
muffin project_name grpc-server
And call it from a Muffin view (or any asyncio code):
from grpc.aio import AioRpcError
from .proto.helloworld import GreeterStub, HelloRequest
@app.route("/")
async def index(request):
name = request.url.query.get("name", "anonymous")
try:
async with grpc.get_channel() as channel:
stub = GreeterStub(channel)
response = await stub.SayHello(HelloRequest(name=name), timeout=10)
return response.message
except AioRpcError as exc:
return exc.details()
A complete runnable application (server, web client and templates) lives in the example/ directory of the repository. It needs the example dependency group (muffin-jinja2 and uvicorn):
uv sync --group example
make build # compile example/proto/src/helloworld.proto
make example # web UI on http://localhost:5000
make example-grpc # gRPC server on [::]:50051
Proto compilation
Registering a proto
add_proto(path, build_dir=None, **params) registers a .proto file and, when autobuild is enabled (the default), compiles it immediately:
path is resolved to an absolute path and stored in plugin.proto_files;
build_dir defaults to the plugin option build_dir and then to the directory of the .proto file itself;
**params are passed to build_proto — in practice build_package, include and targets (see below); they are remembered and reused by the grpc-build command;
the return value is the list of generated files: the *_pb2.py module, the *_pb2_grpc.py module when the proto declares a service, and the *_pb2.py files of imported protos. With autobuild=False nothing is written and only the expected <name>_pb2.py path is returned.
build_proto(path, build_dir=None, *, build_package=None, targets=None, include=None) does the actual work and returns [] when the file does not exist.
Generated files
Everything is written to build_dir (flat, next to each other):
<name>_pb2.py — messages;
<name>_pb2_grpc.py — stubs and servicers, only for protos with a service;
__init__.py — created only when something was rebuilt, contains a generated header comment;
<package>.py — an aggregator with from .<name>_pb2 import * lines for every generated module. Its name is build_package if given, otherwise the last package declaration of the proto. Use build_package=False to skip it, and note that a proto without a package and without an explicit build_package produces no aggregator.
Incremental builds
build_proto compares the change time (ctime) of the proto with the ctime of the target file (_is_newer). Targets that are newer are not regenerated, and when every target is up to date nothing is written at all — not even __init__.py or the aggregator. So generated files are only rewritten when the proto itself changed. Note that ctime is the metadata change time, so e.g. a chmod on the proto also triggers a rebuild, while a copied file with preserved timestamps still gets a fresh ctime.
Proto dependencies
Imports are read with proto-schema-parser: every import "..." is compiled first (recursively, depth-first) into the same build_dir (or build_dir/<subdir> for imports that carry a directory in their name), then the importing proto is compiled. Because of that the order of add_proto calls does not matter for dependencies — but services still have to be registered before the server is started.
Imports are looked up in the directory of the importing proto, in the grpc_tools well-known types (google/protobuf/*.proto) and in the extra roots passed as include=[path, ...]. Protos that live in a different directory than the importer therefore need an explicit include:
from pathlib import Path
grpc.add_proto("protos/api/service.proto", include=[Path("protos")])
Import fixing
grpc_tools.protoc generates absolute imports (import helloworld_pb2 as ...), which break as soon as the generated files live in a package. After a successful compile the plugin rewrites, in every generated file, lines matching ^import <name>_pb2 into from . import <name>_pb2. That is why from .proto.helloworld import GreeterStub works and why the build directory must stay importable as a regular Python package.
Only top-level imports are rewritten. An import "sub/base.proto" becomes from sub import base_pb2 and stays absolute — keep proto files, or at least their import paths, flat unless you put the build directory on sys.path.
If protoc fails, the plugin raises PluginError with the command it tried to run.
Autobuild
autobuild (default True) controls whether add_proto compiles the proto right away. It runs where the plugin is configured — typically at module import time, i.e. when the application module is loaded:
grpc = GRPC(app, build_dir=...) # no proto yet
grpc.add_proto("protos/api.proto") # compiles here when autobuild is True
Nothing is compiled in startup(): that method only opens the default channel (see Plugin API). So with autobuild=True a stale or missing build is refreshed on every process start, including production, which costs the compile time and needs a writable build directory.
For production it is better to compile once, before deploying, and to disable the runtime build:
from pathlib import Path
grpc = GRPC(app, build_dir=Path("build/proto"), autobuild=False)
grpc.add_proto("protos/api.proto")
muffin project_name grpc-build # in CI or during deployment
Configuration
You can configure the plugin either via setup() or using GRPC_ prefixed settings in the Muffin app config.
Available options:
Name |
Default value |
Description |
|---|---|---|
autobuild |
True |
Compile protos when they are registered |
build_dir |
None |
Directory for compiled files, None = next to the proto |
server_listen |
“[::]:50051” |
gRPC server address |
ssl_server |
False |
Enable SSL for the server |
ssl_server_params |
None |
Tuple of credentials for the SSL server |
ssl_client |
False |
Enable SSL for the client |
ssl_client_params |
None |
Tuple of credentials for the SSL client |
default_channel |
“localhost:50051” |
Default gRPC client target |
default_channel_options |
{} |
Additional gRPC channel options |
Via setup():
grpc.setup(app, server_listen="localhost:40000")
Or from config:
GRPC_SERVER_LISTEN = "localhost:40000"
Plugin API
- server (property)
A cached grpc.aio.Server with all registered services. The first access registers services and binds server_listen — a secure port when ssl_server is enabled (credentials are unpacked from ssl_server_params), an insecure one otherwise. Register services before the first access, later additions are not picked up.
- add_proto(path, build_dir=None, **params)
Register (and by default compile) a proto, see Proto compilation.
- add_to_server(service_cls)
Register a servicer class on the server. The class must inherit from a generated *Servicer; the plugin finds the generated add_<Service>_to_server function through the class MRO. It is meant to be used as a decorator and returns None — the decorated name is replaced by None in the module namespace, so call grpc.add_to_server(Greeter) instead if you need to keep the class around.
- get_channel(address=None, **options)
Open a channel to address or to default_channel; raise PluginError when neither is set. Uses secure_channel with ssl_channel_credentials(*ssl_client_params) when ssl_client is enabled and insecure_channel otherwise. The options are passed to gRPC as is; when they are empty, default_channel_options is used. Note that the two sets are not merged: any passed option replaces the configured defaults.
- build_proto(path, build_dir=None, *, build_package=None, targets=None, include=None)
Compile one proto (and its imports), return the generated targets. targets is an existing list of paths to extend (used internally for recursion), include adds --proto_path roots.
- startup() / shutdown()
On application startup the plugin opens the default channel and remembers it (a PluginError — e.g. default_channel = None — is ignored, the channel stays None). On shutdown the channel is closed. At the moment there is no proto build here, that is what autobuild does at registration time.
CLI Commands
All commands are registered by the plugin (Muffin converts underscores to dashes, so the functions grpc_build and grpc_server become grpc-build and grpc-server). Neither takes arguments.
Build registered proto files:
muffin project_name grpc-build
Start the gRPC server:
muffin project_name grpc-server
grpc-server starts the cached server (with the services and the SSL configuration above), waits for SIGINT/SIGTERM and then stops it with a 2 second grace period. Since services are registered on the plugin before the server is started, the command must run in the same process that imported your application module.
Limitations
asyncio only. Trio and Curio are not supported (see Requirements).
One server and one default channel per plugin instance; the server is built once and cached.
Only top-level generated imports are fixed (see Import fixing), keep proto paths flat.
get_channel options replace default_channel_options instead of merging with them.
Bug Tracker
Found a bug or have a suggestion? Submit an issue here: https://github.com/klen/muffin-grpc/issues
Contributing
Want to contribute? Pull requests are welcome! Development happens at: https://github.com/klen/muffin-grpc
make # uv sync + install pre-commit hooks
make test # uv run pytest
make lint # pyrefly + ruff
License
Licensed under the MIT license.
Metadata
Release files for muffin-grpc 0.10.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| muffin_grpc-0.10.0.tar.gz | 10.1 kB | Without provenance | Details for muffin_grpc-0.10.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| muffin_grpc-0.10.0-py3-none-any.whl | Python 3 | none | any | Details for muffin_grpc-0.10.0-py3-none-any.whl |
Total release size: 20.0 kB
Release files / muffin_grpc-0.10.0.tar.gz
| Download URL | muffin_grpc-0.10.0.tar.gz |
|---|---|
| Size | 10.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d81555fefb6888f8a9dfaf7508d3c5fb64bc0e4fbfd0a99d9f61b47e08dca12c
|
|
BLAKE2b-256 checksum How to use checksums |
d4840f5cf2a96b8125287e174cbcd2abde1f847d0d2818217bc453fcbd762f8a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / muffin_grpc-0.10.0-py3-none-any.whl
| Download URL | muffin_grpc-0.10.0-py3-none-any.whl |
|---|---|
| Size | 9.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
97ccf9851c2412883fcbd61c2605ec2e6f7c6aeb01b69eebd822ccce2f0c6c4e
|
|
BLAKE2b-256 checksum How to use checksums |
9ddbead87e805e9729a42269cb2ca637b111a267b179ab2e377d96ae825ac838
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for muffin-grpc 0.10.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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.