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+.

pip install bramble-graphql

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

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:

pip install "bramble-graphql[fastapi]"

Quickstart

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 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 builds the extension in place:

pip install -e ".[dev]"

# 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 or Apache 2.0, at your option.