PyPI NuGet v1.0.0 MIT

metaengine-protobuf-httpx

Protobuf 3 → an async Python httpx client and Pydantic v2 message models over gRPC-Connect on HTTP, with HTTP-status error handling, 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

13
  • WithErrorHandling()Smart error handling based on HTTP status semantics (Connect maps gRPC errors onto HTTP status codes)
  • WithErrorHandling(errors => errors...)Per-status routing on the Connect transport: ReturnNullFor(404, 403) · ReturnErrorFor(400, 422) · ThrowFor(401, 500)
  • 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

1
  • EnableVerboseLogging()Enable detailed logging
Features

Why this package is different

Deterministic output
Same spec + same options produce byte-identical files. Safe to commit, safe to diff in review, safe to cache in CI.
Tree-shakeable
One file per tag (or per operation) means bundlers drop unused code at build time. No runtime dispatch table.
Zero runtime
Validation and clients opt in. The default emit is pure types with no dependency surface beyond your HTTP lib.
Flexible naming
Case conventions configurable per role — types, properties, operations, enums. Idiomatic in the target by default.
Type resolution
Discriminated unions for oneOf, proper nullability, bigint when the spec mandates it, refs flattened only when safe.
Semver-honest
Spec diff drives the version bump. Additive changes = minor, removed ops = major. Never a surprise in your lockfile.