{"id":2766,"library":"sgqlc","title":"Simple GraphQL Client","description":"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.","status":"active","version":"18","language":"en","source_language":"en","source_url":"http://github.com/profusion/sgqlc","tags":["graphql","client","codegen","api"],"install":[{"cmd":"pip install sgqlc","lang":"bash","label":"Install sgqlc"}],"dependencies":[{"reason":"Required for GraphQL type system operations and validation.","package":"graphql-core","optional":false}],"imports":[{"note":"The standard HTTP endpoint using `urllib.request.urlopen()`.","symbol":"HTTPEndpoint","correct":"from sgqlc.endpoint.http import HTTPEndpoint"},{"note":"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`).","symbol":"RequestsEndpoint","correct":"from sgqlc.endpoint.requests import RequestsEndpoint"},{"note":"Used to construct and serialize GraphQL queries/mutations as Python objects.","symbol":"Operation","correct":"from sgqlc.operation import Operation"},{"note":"Base class for defining GraphQL types in Python.","symbol":"Type","correct":"from sgqlc.types import Type"},{"note":"Used to define fields within GraphQL types.","symbol":"Field","correct":"from sgqlc.types import Field"},{"note":"Helper to declare list types in GraphQL schema definitions.","symbol":"list_of","correct":"from sgqlc.types import list_of"}],"quickstart":{"code":"import os\nfrom sgqlc.endpoint.http import HTTPEndpoint\nfrom sgqlc.operation import Operation\nfrom sgqlc.types import Type, Field, list_of\n\n# Define a simple GraphQL schema in Python\nclass Character(Type):\n    name = Field(str)\n    appears_in = Field(list_of(str))\n\nclass Query(Type):\n    hero = Field(Character, args={'episode': str})\n    characters = Field(list_of(Character))\n\nclass Schema(Type):\n    query = Field(Query)\n\n# Configure the GraphQL endpoint\n# Replace with a real GraphQL API endpoint and token if available\nurl = os.environ.get('GRAPHQL_ENDPOINT', 'https://swapi-graphql.netlify.app/.netlify/functions/index')\nheaders = {}\n# If your API requires authentication, uncomment and set an environment variable\n# auth_token = os.environ.get('GRAPHQL_AUTH_TOKEN')\n# if auth_token:\n#    headers['Authorization'] = f'Bearer {auth_token}'\n\nendpoint = HTTPEndpoint(url, headers)\n\n# Build a query using the defined schema\nop = Operation(Schema.query)\n\n# Select the 'hero' field and its subfields\nhero_query = op.hero(episode='JEDI')\nhero_query.name()\nhero_query.appears_in()\n\n# Execute the query\nprint(f\"Executing query to {url}:\\n{op}\\n\")\ndata = endpoint(op)\n\n# Interpret the results using the operation object\nresult = op + data\n\nif result.errors:\n    print(\"Errors:\", result.errors)\nelse:\n    hero = result.hero\n    if hero:\n        print(f\"Hero: {hero.name}\")\n        print(f\"Appears in: {', '.join(hero.appears_in)}\")\n    else:\n        print(\"No hero found for episode JEDI.\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=18"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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')`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}