MetaEngine GraphQL Python httpx

Generate idiomatic Python clients and models from a GraphQL schema (SDL).

Pydantic v2 models and an async httpx client — typed, with bearer/basic auth, retries, timeouts, error handling, custom headers, fragments, @oneOf inputs, and optional docstrings.

No .NET required. Unlike most MetaEngine wrappers, each wheel bundles a self-contained, platform-native binary — pip install and run. There is nothing else to install.

---

Quick Links

• PyPI Package: metaengine-graphql-httpx
• NuGet Package: MetaEngine.Python.GraphQL.Httpx
• Website: metaengine.eu

---

Features

• ✅ Self-contained - Bundled native binary per platform; no .NET runtime to install
• ✅ Pydantic v2 models - BaseModel with ConfigDict, typed fields, required vs optional
• ✅ Async httpx client - typed service methods, model_validate on responses
• ✅ Fragments - Reusable named fragments for object-type selections
• ✅ @oneOf inputs - Idiomatic tagged-union input types
• ✅ Custom scalars - Map GraphQL custom scalars to Python types (str, int, float, bool, datetime, Any)
• ✅ Auth & resilience - Bearer/basic auth, retries with backoff, timeouts, smart error handling, custom headers
• ✅ camelCase aliases - snake_case Python properties mapped to camelCase wire names via Field(alias=...)
• ✅ Docstrings - Optional doc-comment generation from SDL descriptions

---

Installation

pip install metaengine-graphql-httpx

Pre-built wheels are published for Linux (x86_64, aarch64), macOS (Apple Silicon + Intel), and Windows (x64).

---

Requirements

• Python 3.8 or later
• No .NET runtime - the wheel ships a self-contained native binary for your platform

---

Quick Start

metaengine-graphql-httpx <input> <output> [options]

Recommended Setup

metaengine-graphql-httpx schema.graphql ./generated \
  --fragments \
  --documentation

More Examples

# Bearer auth + retries
metaengine-graphql-httpx schema.graphql ./generated --bearer-auth API_TOKEN --retries 3

# Map a custom scalar + emit @oneOf input types
metaengine-graphql-httpx schema.graphql ./generated --custom-scalar DateTime=datetime --one-of-inputs

# Timeout, error handling, and a static header from an env var
metaengine-graphql-httpx schema.graphql ./generated --timeout 30 --error-handling --custom-header X-Tenant-ID=TENANT_ID

---

CLI Options

Argument / Option	Description	Default
input (required)	GraphQL schema file path (SDL) or inline SDL content	-
output (required)	Output directory for generated Python files	-
--fragments	Emit reusable named fragments for object-type selections	false
--one-of-inputs	Generate idiomatic @oneOf input types (tagged-union inputs)	false
--custom-scalar <Scalar>=<target>	Map a GraphQL custom scalar to a Python type (repeatable). Targets: str, int, float, bool, datetime, Any	-
--bearer-auth <ENV>	Bearer token from env var (e.g. API_TOKEN)	-
--basic-auth <USER_ENV>=<PASS_ENV>	Basic auth from env vars	-
--retries <n>	Enable retries with exponential backoff; value sets max attempts	-
--timeout <s>	Request timeout in seconds for all operations	-
--error-handling	Smart error handling based on HTTP status semantics	false
--custom-header <Header>=<ENV>	Static header from env var (repeatable)	-
--base-url-env <ENV>	Environment variable name for base URL	API_BASE_URL
--sync-methods	Generate synchronous service methods alongside the async client	false
--middleware	Generate httpx transport middleware infrastructure	false
--documentation	Generate docstring comments from SDL descriptions	false
--camel-case-aliases	Generate camelCase field aliases for Pydantic models	false
--options-threshold <n>	Parameter count at which a method switches to an options object	4
--service-suffix <name>	Service class naming suffix	Service
--verbose	Enable verbose logging	false

---

Generated Code Structure

output/
  ├── models/                    # One file per GraphQL type (Pydantic v2)
  │   ├── post.py                # class Post(BaseModel): ...
  │   ├── user.py                # class User(BaseModel): ...
  │   └── ...
  ├── services/                  # Async httpx client + base transport
  │   ├── query_service.py       # class QueryService with the root operations
  │   ├── base_http_service.py   # shared transport (auth, retries, error handling)
  │   └── ...
  └── fragments.py               # reusable named fragments (with --fragments)

Models use Pydantic v2 (BaseModel + ConfigDict); with --camel-case-aliases, snake_case properties carry a Field(alias=...) mapping to the wire name and populate_by_name=True:

class User(BaseModel):
    model_config = ConfigDict(populate_by_name=True)
    id: str
    display_name: str = Field(alias='displayName')

---

Support

• Issues: GitHub Issues
• Email: info@metaengine.eu
• Website: metaengine.eu

---

License

MIT License - see LICENSE file for details.

---

About This Repository

This is the documentation and issue tracking repository for MetaEngine GraphQL Python httpx. The package is published to PyPI.

Source code is proprietary, but the package is free to use under the MIT license.