PyPI NuGet v1.0.0 MIT

Protobuf to Python httpx Client Generator

metaengine-protobuf-httpx

Convert Protobuf 3 to an async Python httpx client and Pydantic v2 message models over gRPC-Connect on HTTP, with typed Connect-protocol errors, optional docstrings, and dependency-free @dataclass models. Delivered as a pip-installable CLI — no .NET required.

Protobuf 3.xMetaEngine IRPython · httpx
Install

Pick your registry

The same generator, published to every ecosystem we support. Install however your project expects.

PyPIPrimarymetaengine-protobuf-httpx
$pip install metaengine-protobuf-httpx
v1.0.0
NuGetMetaEngine.Python.Protobuf.Httpx
$dotnet add package MetaEngine.Python.Protobuf.Httpx
v1.0.0
Usage

Drive it from the CLI or programmatically

PyPI ships a zero-config CLI. NuGet ships the same generator as a C# fluent API — same options, same output.

PyPI · pip · CI-friendly

After install, point the CLI at your schema. It writes the generated tree to your chosen output directory.

Basic syntax
terminal
metaengine-protobuf-httpx <input> <output> [options]

Generates an async httpx gRPC-Connect client and Pydantic v2 message models from Protobuf 3 .proto files. The wheel bundles a platform-native runner, so no .NET install is required.

Quick examples
Generate from a .proto file
metaengine-protobuf-httpx ./service.proto ./generated
With docstrings
metaengine-protobuf-httpx ./service.proto ./generated --documentation
Dependency-free @dataclass models
metaengine-protobuf-httpx ./service.proto ./generated --dataclass --verbose
CLI options
Option
Description
--documentation
Generate docstring comments
--dataclass
Generate @dataclass models instead of Pydantic v2 models
--verbose
Enable verbose logging
Options reference

Every knob, documented

Every option is available on the C# fluent API as a method, and most are also exposed as CLI flags. Cross-cutting auth, headers, retries and timeouts apply across frameworks.

Python Client Options

6
  • WithDocumentation()Generate docstring comments on models and service methods
  • WithSyncMethods()Generate synchronous methods (httpx.Client) instead of async (httpx.AsyncClient)
  • WithMiddleware()Emit request / response middleware hooks in the generated client
  • WithCamelCaseAliases()Field(alias=...) camelCase aliases on models (always-on for protobuf — proto3 JSON wire format is lowerCamelCase)
  • WithMethodNames(Func)Custom method naming rule
  • WithOptionsObjectThreshold(int)Parameter count before an options object is used (default: 4)

Auth · Headers · Resilience

11
  • WithBearerAuth()Bearer token from env var (default API_TOKEN) — adds Authorization header
  • WithBearerAuth(string)Bearer token from a specific env var name
  • WithBearerAuth(string, string)Bearer token with custom header name (e.g. X-Api-Key)
  • WithBasicAuth(string, string)HTTP Basic auth from username + password env vars
  • WithCustomHeader(string, string)Static header from env var. Repeatable (e.g. X-Tenant-ID ← TENANT_ID)
  • WithBaseUrlEnvVar(string)Environment variable name for the base URL (default: API_BASE_URL)
  • WithTimeout(double)Request timeout in seconds for all operations
  • WithTimeout(double?, double?, double?, double?)Granular httpx timeout: connect · read · write · pool
  • WithRetries()Retries with exponential backoff (default status 429, 503)
  • WithRetries(int)Retries with custom max attempts
  • WithRetries(int, double, double, int[])Retries with max attempts, base delay, max delay, and custom status codes

Protobuf Options

3
  • WithDataclass()Emit @dataclass(slots=True) models instead of Pydantic v2 BaseModel — zero runtime deps, stdlib dataclasses only
  • WithTypeFilter(Func)Filter extracted proto types before registration — only types returning true are generated
  • WithTypeMapping(string, Type)Override the Python mapping for a protobuf well-known type by fully-qualified name (e.g. google.protobuf.Timestamp → str)

Naming Transformations

3
  • Types(Func)Transform type names
  • Paths(Func)Transform output paths
  • FileNames(Func)Transform file names

File Management

5
  • CleanDestination()Clean output directory before generation
  • AlwaysOverwrite()Always overwrite existing files
  • OnlyWhenModelChanged()Update only when model changes
  • OnlyWhenNew()Write only new files, preserve existing
  • CleanDirectories(...)Clean specific subdirectories

Diagnostics

2
  • Verbose()Enable verbose logging
  • WithLogger(Action<string>)Route generation log output to a custom sink
Features

Why this package is different

Pydantic v2 or dataclass
Models as Pydantic v2 classes, or dependency-free @dataclass with slots=True when you would rather not take the dependency.
Async-first httpx
Async httpx clients with full PEP 604 type hints. Synchronous methods are opt-in.
pip-installable CLI
Ships as a pip-installable CLI — no .NET runtime required to generate.
Deterministic output
Same spec + same options produce byte-identical files. Safe to commit, safe to diff in review, safe to cache in CI.
Flexible naming
Case conventions are configurable per role — types, properties, operations, enums. Idiomatic in the target by default.
Semver-honest
Spec diff drives the version bump. Additive changes = minor, removed operations = major. Never a surprise in your lockfile.