https://github.com/meta-engine/graphql-httpx
Generate idiomatic Python (Pydantic v2 + httpx) clients and models from GraphQL schemas. Self-contained — no .NET install required.
https://github.com/meta-engine/graphql-httpx
api-client codegen graphql-codegen httpx metaengine pydantic python
Last synced: about 15 hours ago
JSON representation
Generate idiomatic Python (Pydantic v2 + httpx) clients and models from GraphQL schemas. Self-contained — no .NET install required.
- Host: GitHub
- URL: https://github.com/meta-engine/graphql-httpx
- Owner: meta-engine
- License: mit
- Created: 2026-06-16T18:23:55.000Z (22 days ago)
- Default Branch: main
- Last Pushed: 2026-06-16T18:23:59.000Z (22 days ago)
- Last Synced: 2026-06-18T12:15:55.570Z (21 days ago)
- Topics: api-client, codegen, graphql-codegen, httpx, metaengine, pydantic, python
- Homepage: https://www.metaengine.eu/packages/graphql-httpx
- Size: 4.88 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# MetaEngine GraphQL Python httpx
[](https://pypi.org/project/metaengine-graphql-httpx/)
[](https://pypi.org/project/metaengine-graphql-httpx/)
[](https://opensource.org/licenses/MIT)
**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](https://pypi.org/project/metaengine-graphql-httpx/)
- **NuGet Package**: [MetaEngine.Python.GraphQL.Httpx](https://www.nuget.org/packages/MetaEngine.Python.GraphQL.Httpx)
- **Website**: [metaengine.eu](https://www.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
```bash
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
```bash
metaengine-graphql-httpx [options]
```
### Recommended Setup
```bash
metaengine-graphql-httpx schema.graphql ./generated \
--fragments \
--documentation
```
### More Examples
```bash
# 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 =` | Map a GraphQL custom scalar to a Python type (repeatable). Targets: `str`, `int`, `float`, `bool`, `datetime`, `Any` | - |
| `--bearer-auth ` | Bearer token from env var (e.g. `API_TOKEN`) | - |
| `--basic-auth =` | Basic auth from env vars | - |
| `--retries ` | Enable retries with exponential backoff; value sets max attempts | - |
| `--timeout ` | Request timeout in seconds for all operations | - |
| `--error-handling` | Smart error handling based on HTTP status semantics | `false` |
| `--custom-header =` | Static header from env var (repeatable) | - |
| `--base-url-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 ` | Parameter count at which a method switches to an options object | `4` |
| `--service-suffix ` | 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`:
```python
class User(BaseModel):
model_config = ConfigDict(populate_by_name=True)
id: str
display_name: str = Field(alias='displayName')
```
---
## Support
- **Issues**: [GitHub Issues](https://github.com/meta-engine/graphql-httpx/issues)
- **Email**: info@metaengine.eu
- **Website**: [metaengine.eu](https://www.metaengine.eu)
---
## License
MIT License - see [LICENSE](./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](https://pypi.org/project/metaengine-graphql-httpx/).
Source code is proprietary, but the package is free to use under the MIT license.