PyPI NuGet v1.0.0 MIT

metaengine-graphql-httpx

GraphQL SDL → 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

5
  • 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
  • WithSubscriptionUrl(string)Path appended to baseUrl for the GraphQL WebSocket subscription endpoint (default: /graphql). The client upgrades http→ws / https→wss; subscriptions surface as an AsyncIterator over the graphql-transport-ws subprotocol
  • 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

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.