Skip to content

๐Ÿงฌ GraphQL Client

Clientele provides a specialized GraphQLClient for building GraphQL integrations following the same decorator pattern as the standard APIClient.

Basic Query

from pydantic import BaseModel
from clientele.graphql import GraphQLClient

client = GraphQLClient(base_url="https://api.github.com/graphql")

class Repository(BaseModel):
    name: str
    stargazerCount: int

class RepositoryQueryData(BaseModel):
    repository: Repository

class RepositoryQueryResponse(BaseModel):
    data: RepositoryQueryData

@client.query("""
    query($owner: String!, $name: String!) {
        repository(owner: $owner, name: $name) {
            name
            stargazerCount
        }
    }
""")
def get_repo(result: RepositoryQueryResponse, owner: str, name: str) -> Repository:
    return result.data.repository

repo = get_repo(owner="phalt", name="clientele")
print(repo.name)  # "clientele"
print(repo.stargazerCount)  # 100

How it works:

  • The GraphQL query string is passed to the @client.query() decorator.
  • Function parameters (excluding result and response) become GraphQL variables.
  • The result parameter is auto-hydrated to the specified Pydantic model matching GraphQL's response structure.
  • GraphQL wraps all responses in {"data": {...}}, so your models should reflect this nested structure.

Basic Mutation

from pydantic import BaseModel
from clientele.graphql import GraphQLClient

client = GraphQLClient(base_url="https://api.github.com/graphql")

class Issue(BaseModel):
    id: str
    title: str

class CreateIssueData(BaseModel):
    issue: Issue

class CreateIssueMutationData(BaseModel):
    createIssue: CreateIssueData

class CreateIssueMutationResponse(BaseModel):
    data: CreateIssueMutationData

@client.