Metadata-Version: 2.4
Name: bramble-graphql
Version: 0.3.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Rust
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: python-multipart>=0.0.32 ; extra == 'asgi'
Requires-Dist: click>=8.1 ; extra == 'cli'
Requires-Dist: uvicorn>=0.30 ; extra == 'cli'
Requires-Dist: bramble-graphql[starlette] ; extra == 'cli'
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: ruff ; extra == 'dev'
Requires-Dist: bramble-graphql[cli,asgi,starlette,fastapi,flask,django] ; extra == 'dev'
Requires-Dist: httpx>=0.28.1 ; extra == 'dev'
Requires-Dist: httpx2>=2.9.1 ; extra == 'dev'
Requires-Dist: channels[daphne]>=4.0 ; extra == 'dev'
Requires-Dist: django>=4.2 ; extra == 'django'
Requires-Dist: channels>=4.0 ; extra == 'django'
Requires-Dist: python-multipart>=0.0.32 ; extra == 'django'
Requires-Dist: fastapi>=0.100 ; extra == 'fastapi'
Requires-Dist: python-multipart>=0.0.32 ; extra == 'fastapi'
Requires-Dist: flask>=2.0 ; extra == 'flask'
Requires-Dist: asgiref>=3.7 ; extra == 'flask'
Requires-Dist: python-multipart>=0.0.32 ; extra == 'flask'
Requires-Dist: starlette>=0.37 ; extra == 'starlette'
Requires-Dist: python-multipart>=0.0.32 ; extra == 'starlette'
Provides-Extra: asgi
Provides-Extra: cli
Provides-Extra: dev
Provides-Extra: django
Provides-Extra: fastapi
Provides-Extra: flask
Provides-Extra: starlette
License-File: LICENSE-MIT
License-File: LICENSE-APACHE
Summary: A GraphQL library for Python with a Rust-based parser/validator
Keywords: graphql,api,async,rust,schema
Author: Mario Ritzerfeld
License-Expression: MIT OR Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/jaldisdev/bramble
Project-URL: Issues, https://github.com/jaldisdev/bramble/issues
Project-URL: Repository, https://github.com/jaldisdev/bramble

# Bramble GraphQL

A GraphQL library for Python, with parsing, validation, and query lowering
implemented in Rust and exposed through a thin PyO3 extension. The
schema-declaration API (decorators, type resolution, directives) is pure
Python and dataclass-based.

## Features

- Decorator-based schema definition: `@bramble.type`, `@bramble.interface`,
  `@bramble.input`, `@bramble.union`, `@bramble.scalar`
- Real dataclasses under the hood — `@bramble.type`-decorated classes are
  ordinary dataclasses, not a parallel object model
- Custom scalars, schema directives, and operation directives (`@skip`,
  `@include`, and user-defined directives), each with location validation
- Async and sync execution (`Schema.execute` / `Schema.execute_async`), with
  spec-correct null bubbling, fragment/field merging, and concurrent field
  and list-item resolution (mutations execute their root fields serially,
  per spec)
- SDL rendering (`Schema.to_sdl()`) and Automatic Persisted Queries
- Rust-based parsing and validation for performance and spec conformance

## Installation

Requires Python 3.10+.

```bash
pip install bramble-graphql
```

The distribution is named `bramble-graphql` on PyPI; the import package is
`bramble`:

```python
import bramble
```

Prebuilt wheels are published for Linux (x86_64, aarch64), macOS (Apple
silicon), and Windows (x64). Other platforms fall back to the sdist, which
needs a Rust toolchain to build.

To pull in an HTTP framework's dependencies alongside Bramble, install the
matching extra — `asgi`, `starlette`, `fastapi`, `flask`, `django`, or `cli`:

```bash
pip install "bramble-graphql[fastapi]"
```

## Quickstart

```python
import bramble

@bramble.type
class Query:
    @bramble.field
    def hello(name: str = "world") -> str:
        return f"Hello, {name}!"

schema = bramble.Schema(query=Query)

result = schema.execute("{ hello }")
# {'data': {'hello': 'Hello, world!'}}

print(schema.to_sdl())
# schema {
#   query: Query
# }
#
# type Query {
#   hello(name: String! = "world"): String!
# }
```

See [`examples/blog`](examples/blog/schema.py) for a fuller schema covering
interfaces, unions, custom scalars, schema/operation directives, mutations,
and async resolvers.

## Development

Working on Bramble itself needs a Rust toolchain.
[maturin](https://www.maturin.rs/) builds the extension in place:

```bash
pip install -e ".[dev]"
```

```bash
# Rust
cargo test --workspace
cargo clippy --workspace --all-targets

# Python (rebuild the extension after any Rust change)
maturin develop
pytest
```

## Project layout

- `crates/bramble-core` — pure Rust: parsing, validation, lowering, SDL
  rendering, error types. No Python dependency.
- `crates/bramble-py` — PyO3 bindings exposing `bramble-core` to Python.
- `bramble/` — the Python package: schema-declaration decorators, execution
  engine, and the public API.
- `tests/` — Python test suite.
- `examples/` — example schemas.

## License

Dual-licensed under [MIT](LICENSE-MIT) or [Apache 2.0](LICENSE-APACHE), at
your option.

