Registry / http-networking / sgqlc
library18pypypi✓ verified 24d ago

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.

pip install sgqlc
INSTALL
IMPORT
SIG · SGQLC
S
sgqlc
http-networkingpythonv18
Install
1.8s avg
Import
103ms
Disk
19MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v18 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.106s · 20.5MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.8s · import 0.100s · 21MB
19MB installed
● package 19MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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.")
sgqlc-codegen --version
Debug
Known issues
breakingWith 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.
affects: >=18
gotchaWhen 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.
affects: All
gotchaAttempting 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')`.
affects: All
gotchaWhile `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.
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'sgqlc'
The 'sgqlc' library has not been installed in the current Python environment.
fix
pip install sgqlc
sgqlc-codegen: command not found
The 'sgqlc-codegen' executable is not found in the system's PATH, or the Python environment where sgqlc was installed is not active.
fix
Run using `python -m sgqlc.codegen <schema_source> <output_file>` or ensure your environment's 'pip' scripts directory is included in the system PATH.
AttributeError: 'Query' object has no attribute 'user'
The queried field (e.g., 'user') does not exist on the 'Query' type in your GraphQL schema, or the Python types generated by sgqlc-codegen are outdated or incorrect.
fix
Verify your GraphQL schema includes the field on the corresponding type, and regenerate your Python types using `sgqlc-codegen` to match the current schema.
KeyError: 'data'
The response from the GraphQL endpoint did not contain the expected 'data' key, often because the server returned an error or a non-GraphQL JSON structure.
fix
Inspect the full response from the GraphQL endpoint for error messages or unexpected content, ensuring the server is providing a valid GraphQL response.
Upgrade
Version history
18latest on PyPI · released Feb 6, 2026
Audit
Dependencies
graphql-corerequiredRequired for GraphQL type system operations and validation.
Agent activity
15 hits · last 30 days
node
10
OpenAI (training)
1
Resources
sgqlc — pip install sgqlc · libregistry