Python Client

The fraiseql Python package ships a typed async HTTP client for querying FraiseQL servers from Python scripts, Jupyter notebooks, and backend services.

Installation

pip install fraiseql

Basic Usage

import asyncio
from fraiseql.client import FraiseQLClient

async def main() -> None:
    async with FraiseQLClient("http://localhost:8080/graphql") as client:
        result = await client.execute("{ users { id name email } }")
        print(result["data"]["users"])

asyncio.run(main())

Authentication

Pass a JWT bearer token or API key at construction:

# JWT
client = FraiseQLClient(
    "http://localhost:8080/graphql",
    auth_token="eyJ..."
)

# API key
client = FraiseQLClient(
    "http://localhost:8080/graphql",
    api_key="sk-..."
)

Variables

result = await client.execute(
    """
    query GetUser($id: ID!) {
        user(id: $id) { id name email }
    }
    """,
    variables={"id": "user-123"}
)
user = result["data"]["user"]

Error Handling

The client raises typed exceptions:

from fraiseql.client import (
    FraiseQLError,
    FraiseQLAuthError,
    FraiseQLRateLimitError,
    FraiseQLDatabaseError,
)

try:
    result = await client.execute("{ sensitiveData { secret } }")
except FraiseQLAuthError:
    print("Not authorized")
except FraiseQLRateLimitError:
    print("Slow down — rate limit hit")
except FraiseQLDatabaseError as e:
    print(f"Database error: {e}")
except FraiseQLError as e:
    print(f"GraphQL error: {e}")

Schema Introspection

schema = await client.introspect()
types = schema["data"]["__schema"]["types"]

REST Endpoints

FraiseQL also exposes REST endpoints at /rest/v1/<resource> (the default path is /rest/v1; configure with [rest] path). You can query these directly from Python scripts using httpx or requests without the FraiseQLClient:

import httpx

async def fetch_users(token: str) -> list[dict]:
    async with httpx.AsyncClient() as client:
        response = await client.get(
            "http://localhost:8080/rest/v1/users",
            headers={"Authorization": f"Bearer {token}"},
            params={"limit": 20},
        )
        response.raise_for_status()
        return response.json()

REST endpoints follow the same resource naming as GraphQL queries and mutations. Mutations use POST; queries use GET with query string parameters.