PyPI NuGet v1.0.0 MIT

GraphQL to Python httpx Client Generator

metaengine-graphql-httpx

Convert GraphQL SDL to an async Python httpx client and Pydantic v2 models with typed queries, mutations & subscriptions (subscriptions surface as an AsyncIterator over a graphql-transport-ws WebSocket), plus bearer/basic auth, retries, timeouts, error handling, fragments, and @oneOf inputs. Delivered as a pip-installable CLI — no .NET required.

GraphQL SDLMetaEngine IRPython · httpx
Install

Pick your registry

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

PyPIPrimarymetaengine-graphql-httpx
$pip install metaengine-graphql-httpx
v1.0.0
NuGetMetaEngine.Python.GraphQL.Httpx
$dotnet add package MetaEngine.Python.GraphQL.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-graphql-httpx <input> <output> [options]

Generates an async Python httpx client and Pydantic v2 models from a GraphQL SDL schema — typed queries, mutations & subscriptions (subscriptions resolve to an AsyncIterator over a graphql-transport-ws WebSocket). <input> accepts a local SDL file path or inline SDL content. The wheel bundles a platform-native runner, so no .NET install is required.

Quick examples
Fragments, docstrings and retries
metaengine-graphql-httpx ./schema.graphql ./generated --fragments --documentation --retries 3
Bearer auth, a request timeout and smart error handling
metaengine-graphql-httpx ./schema.graphql ./generated --bearer-auth API_TOKEN --timeout 30 --error-handling
Sync methods, a custom scalar and camelCase Pydantic aliases
metaengine-graphql-httpx ./schema.graphql ./generated --sync-methods --custom-scalar DateTime=datetime --camel-case-aliases
CLI options
Option
Description
--fragments
Emit reusable named fragments for object-type selections
--one-of-inputs
Generate idiomatic @oneOf input types (tagged-union inputs)
--custom-scalar <S>=<t>
Map a GraphQL custom scalar to a Python type (repeatable). Targets: str, int, float, bool, datetime, Any (e.g. DateTime=datetime)
--bearer-auth <ENV>
Bearer token from env var (e.g. API_TOKEN) — adds an Authorization header to all requests
--basic-auth <USER>=<PASS>
Basic auth from env vars, format <username-env>=<password-env>
--retries <n>
Enable retries with exponential backoff; value sets max attempts
--timeout <s>
Request timeout in seconds for all operations
--error-handling
Enable smart error handling based on HTTP status semantics
--custom-header <H>=<ENV>
Static header from an env var (repeatable), format <header-name>=<env-var-name>
--base-url-env <ENV>
Environment variable name for the base URL (default: API_BASE_URL)
--sync-methods
Generate synchronous service methods alongside the async client
--middleware
Generate httpx transport middleware infrastructure
--documentation
Generate docstring comments from SDL descriptions
--camel-case-aliases
Generate camelCase field aliases for Pydantic models
--options-threshold <n>
Parameter count at which a method switches to an options object (default: 4)
--service-suffix <name>
Service naming suffix (default: Service)
--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 Options

6
  • WithDocumentation()Generate docstring comments on methods and parameters from SDL descriptions
  • WithSyncMethods()Generate synchronous service methods alongside the async httpx client
  • WithCamelCaseAliases()Emit camelCase aliases on Pydantic models (populate_by_name — accepts snake_case and camelCase JSON)
  • WithMiddleware()Generate httpx transport middleware infrastructure (Middleware type + chain helpers)
  • WithMethodNames(Func)Custom method naming rule
  • WithOptionsObjectThreshold(int)Parameter count at which a method switches to an options object (default: 4)

Auth · Headers · Resilience

14
  • WithErrorHandling()Smart error handling based on HTTP status (404 / 403 → None · 400 / 422 → error body · 401 / 5xx → raise). GraphQL operations travel over HTTP POST.
  • WithErrorHandling(errors => errors...)Per-status routing: 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 a custom header name (e.g. X-Api-Key)
  • WithBasicAuth()HTTP Basic auth from default env vars (API_USERNAME / API_PASSWORD)
  • WithBasicAuth(string, string)HTTP Basic auth from username + password env vars
  • WithCustomHeader(string, string)Static header from an env var. Repeatable (e.g. X-Tenant-ID ← TENANT_ID)
  • WithBaseUrlEnvVar(string)Read the base URL from an env var (default API_BASE_URL)
  • WithTimeout(double)Request timeout in seconds for all operations
  • WithTimeout(double?, double?, ...)Granular httpx timeout: connect · read · write · pool
  • WithRetries()Retries with exponential backoff (default status 429, 503)
  • WithRetries(int)Retries with a custom max-attempts count
  • WithRetries(int, double, double, int[])Retries with full custom settings including retryable status codes

GraphQL Options

4
  • WithFragments()Emit reusable named fragments for object-type selections (...TypeFields spreads)
  • WithOneOfInputs()Generate idiomatic @oneOf input types (tagged-union inputs where exactly one field is set)
  • WithCustomScalar(string, Type)Map a GraphQL custom scalar to a Python type (e.g. DateTime → datetime). Unmapped scalars default to str
  • WithTypeFilter(Func)Filter extracted GraphQL types before registration — only types returning true are generated

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.