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 sgqlcVerified import paths — ran on the pinned version, not inferred.
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.
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.
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.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')`.
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.
pip install sgqlc
Run using `python -m sgqlc.codegen <schema_source> <output_file>` or ensure your environment's 'pip' scripts directory is included in the system PATH.
Verify your GraphQL schema includes the field on the corresponding type, and regenerate your Python types using `sgqlc-codegen` to match the current schema.
Inspect the full response from the GraphQL endpoint for error messages or unexpected content, ensuring the server is providing a valid GraphQL response.