sgqlc

sgqlc (Simple GraphQL Client) is a Python library for working with GraphQL APIs in a typed, programmatic way. You declare GraphQL schemas as Python classes, use them to build and validate queries and mutations in code rather than raw strings, and interpret responses back into typed objects. It ships an HTTP endpoint helper for calling any GraphQL server over urllib.

Modules cover type declaration (including datetime and Relay bindings), operation building, and endpoint access, and a code generator can convert a server’s introspection schema into ready-to-use Python types.

What You Get

• A type system (sgqlc.types) for declaring GraphQL schemas in Python, with datetime and Relay helpers
• An operation builder (sgqlc.operation) for composing typed queries and mutations programmatically
• An HTTP endpoint (sgqlc.endpoint.http) for calling any GraphQL server over urllib
• A code generator that turns an introspection schema into Python type definitions
• Automatic interpretation of JSON responses into typed Python objects

Common Use Cases

• Calling third-party GraphQL APIs such as GitHub’s v4 API from Python
• Generating typed Python bindings from a GraphQL schema for safer queries
• Building queries and mutations programmatically instead of maintaining query strings

Under The Hood

Architecture

sgqlc separates concerns across three core modules: sgqlc.types declares schemas via metaclass-driven Python classes (with submodules for datetime and Relay Node/Connection patterns); sgqlc.operation uses those types to build an operation tree that serializes to a GraphQL query and, on response, selects values back into typed instances; and sgqlc.endpoint provides transport, notably HTTPEndpoint over urllib.request. A codegen utility introspects a live schema and emits matching Python type definitions.

Tech Stack

Pure Python packaged with Poetry (pyproject.toml, poetry.lock). The core has minimal dependencies, using the standard-library urllib for its HTTP endpoint, with optional extras for alternative transports (such as requests or websockets for subscriptions). Tests live under tests/, examples under examples/, and documentation is authored in the doc/ directory.

Code Quality

A well-established library (hundreds of stars, ISC-licensed) with a dedicated test suite covering types, operation building, endpoints, and codegen. The design leans on Python metaclasses to provide a declarative schema DSL, which is powerful and consistent, and the project maintains examples and documentation, though the metaclass-heavy approach adds some conceptual depth for newcomers.

API Design

The developer experience is strong once the type model clicks: declaring types and building operations gives editor completion and validation that raw GraphQL strings lack. Codegen removes the tedium of writing schema types by hand, and the HTTP endpoint is a one-liner. The main learning curve is understanding the typed operation-building pattern, which the examples and docs address well.