Simple GraphQL Client

18 · active · verified Fri Apr 10

sgqlc is an easy-to-use Python library for interacting with GraphQL APIs. It provides modules for defining GraphQL types in Python, constructing and interpreting GraphQL queries and mutations as native Python objects, and connecting to GraphQL endpoints over HTTP. It also includes a command-line tool, `sgqlc-codegen`, to automatically generate Python type definitions from a GraphQL schema, promoting a schema-first approach. The library is actively maintained, with the current version being 18, released in February 2026.

Warnings

breaking With version 18, `sgqlc` strongly encourages the use of `sgqlc.operation.Operation` to construct and manage GraphQL queries. Directly manipulating dictionary-like structures for queries is discouraged, as `Operation` ensures valid GraphQL syntax and simplifies result interpretation into native Python objects.
Fix: Migrate direct string or dictionary-based query construction to use `sgqlc.operation.Operation` by defining a Python schema and building queries programmatically through object attribute access and method calls. Utilize `sgqlc-codegen` for large or frequently changing schemas.
gotcha When executing an `Operation` object with an endpoint multiple times, `sgqlc` re-serializes the operation to a string on each call, which can be a performance bottleneck for large or frequently executed operations. This is especially true if only variables change between calls.
Fix: For performance-critical scenarios, pre-serialize the `Operation` object to a string (`query = bytes(op).decode('utf-8')`) once. Then pass this string along with a `variables` dictionary to the endpoint for subsequent calls. Use `sgqlc.types.Variable` for dynamic arguments.
gotcha Attempting to select the same GraphQL field multiple times within a single operation without using aliases will result in a `ValueError`. GraphQL queries require unique field names or explicit aliases for multiple selections of the same field.
Fix: If you need to query the same field with different arguments or multiple times for other reasons, use the `__alias__` argument when making the field selection, e.g., `op.my_field(arg='value1', __alias__='alias1')` and `op.my_field(arg='value2', __alias__='alias2')`.
gotcha While `sgqlc` can execute raw GraphQL query strings, it is highly recommended to leverage its object-based query generation and schema definition features, or `sgqlc-codegen`. Hand-writing query strings is error-prone, difficult to maintain, and loses the benefits of Python object-oriented interpretation.
Fix: Define your GraphQL schema as Python classes (`sgqlc.types.Type`) and construct queries using `sgqlc.operation.Operation`. Alternatively, use `sgqlc-codegen` to automatically generate Python schema classes from a GraphQL introspection endpoint or `.json` file, and then build queries against the generated schema.

Install

pip install sgqlc Install sgqlc

Imports

HTTPEndpoint
```
from sgqlc.endpoint.http import HTTPEndpoint
```
The standard HTTP endpoint using `urllib.request.urlopen()`.
RequestsEndpoint
```
from sgqlc.endpoint.requests import RequestsEndpoint
```
An alternative HTTP endpoint that uses the `requests` library, providing its benefits like session management and advanced authentication. Requires `requests` to be installed separately (`pip install requests`).
Operation
```
from sgqlc.operation import Operation
```
Used to construct and serialize GraphQL queries/mutations as Python objects.
Type
```
from sgqlc.types import Type
```
Base class for defining GraphQL types in Python.
Field
```
from sgqlc.types import Field
```
Used to define fields within GraphQL types.
list_of
```
from sgqlc.types import list_of
```
Helper to declare list types in GraphQL schema definitions.

Quickstart

This quickstart demonstrates how to define a minimal GraphQL schema in Python, construct a query using `sgqlc.operation.Operation`, execute it against a public GraphQL endpoint, and interpret the results as native Python objects. It uses the `HTTPEndpoint` for synchronous requests. For more complex schemas, `sgqlc-codegen` can be used to generate Python types automatically.

import os
from sgqlc.endpoint.http import HTTPEndpoint
from sgqlc.operation import Operation
from sgqlc.types import Type, Field, list_of

# Define a simple GraphQL schema in Python
class Character(Type):
    name = Field(str)
    appears_in = Field(list_of(str))

class Query(Type):
    hero = Field(Character, args={'episode': str})
    characters = Field(list_of(Character))

class Schema(Type):
    query = Field(Query)

# Configure the GraphQL endpoint
# Replace with a real GraphQL API endpoint and token if available
url = os.environ.get('GRAPHQL_ENDPOINT', 'https://swapi-graphql.netlify.app/.netlify/functions/index')
headers = {}
# If your API requires authentication, uncomment and set an environment variable
# auth_token = os.environ.get('GRAPHQL_AUTH_TOKEN')
# if auth_token:
#    headers['Authorization'] = f'Bearer {auth_token}'

endpoint = HTTPEndpoint(url, headers)

# Build a query using the defined schema
op = Operation(Schema.query)

# Select the 'hero' field and its subfields
hero_query = op.hero(episode='JEDI')
hero_query.name()
hero_query.appears_in()

# Execute the query
print(f"Executing query to {url}:\n{op}\n")
data = endpoint(op)

# Interpret the results using the operation object
result = op + data

if result.errors:
    print("Errors:", result.errors)
else:
    hero = result.hero
    if hero:
        print(f"Hero: {hero.name}")
        print(f"Appears in: {', '.join(hero.appears_in)}")
    else:
        print("No hero found for episode JEDI.")

view raw JSON →