{"id":7278,"library":"graphql-query","title":"GraphQL Query DSL for Python","description":"graphql-query is a Python library that provides a complete Domain Specific Language (DSL) for constructing GraphQL queries programmatically. It allows developers to build complex GraphQL queries, mutations, and fragments using Python objects, simplifying the process of generating valid GraphQL syntax. The library is actively maintained with regular updates, currently at version 1.4.0.","status":"active","version":"1.4.0","language":"en","source_language":"en","source_url":"https://github.com/denisart/graphql-query","tags":["GraphQL","query builder","DSL","client","pydantic"],"install":[{"cmd":"pip install graphql-query","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for data modeling and validation, migrated in v1.3.0/v1.2.0. Users must use Pydantic v2 or later.","package":"pydantic>=2","optional":false}],"imports":[{"note":"Main class for building a GraphQL query operation.","symbol":"Query","correct":"from graphql_query import Query"},{"note":"Used to define fields within a GraphQL query or sub-selection.","symbol":"Field","correct":"from graphql_query import Field"},{"note":"Used to define arguments for fields or queries.","symbol":"Argument","correct":"from graphql_query import Argument"}],"quickstart":{"code":"from graphql_query import Query, Field, Argument\n\n# Example 1: Simple Query\nsimple_query = Query(\n    name=\"myQuery\",\n    fields=[\n        Field(name=\"hero\", fields=[Field(name=\"name\")]),\n    ]\n)\nprint(f\"Simple Query: {simple_query.render()}\")\n# Expected output: { myQuery { hero { name } } }\n\n# Example 2: Query with Arguments\nquery_with_args = Query(\n    name=\"character\",\n    arguments=[\n        Argument(name=\"id\", value=\"1000\")\n    ],\n    fields=[\n        Field(name=\"name\"),\n        Field(name=\"appearsIn\")\n    ]\n)\nprint(f\"Query with Arguments: {query_with_args.render()}\")\n# Expected output: query character($id: String = \"1000\") { character(id: $id) { name appearsIn } }","lang":"python","description":"This quickstart demonstrates how to construct basic GraphQL queries using the `Query`, `Field`, and `Argument` classes. The `render()` method converts the Python object structure into a valid GraphQL query string."},"warnings":[{"fix":"Upgrade Pydantic to version 2 or newer (`pip install pydantic>=2`) and ensure your codebase is compatible. If other dependencies still require Pydantic v1, consider isolating the graphql-query environment or using `pydantic.v1` namespace if applicable, though `graphql-query` specifically targets v2.","message":"Migration to Pydantic v2 occurred in graphql-query v1.2.0 and became the default in v1.3.0. Projects using Pydantic v1.x will encounter compatibility issues.","severity":"breaking","affected_versions":">=1.2.0"},{"fix":"Ensure your project runs on Python 3.8 or a later version.","message":"Python 3.7 support was dropped in version 1.3.1. The library now requires Python 3.8 or newer.","severity":"breaking","affected_versions":">=1.3.1"},{"fix":"Review your project's direct `graphql-core` usage. Add `pip install graphql-core` if still needed independently of `graphql-query`.","message":"The `graphql-core` dependency was removed in v1.1.1, simplifying the dependency tree. If your project explicitly relied on `graphql-core` through `graphql-query`'s transitive dependencies, you might need to add it directly if still required for other purposes.","severity":"deprecated","affected_versions":">=1.1.1"},{"fix":"Refer to the `graphql-query` documentation for advanced argument typing and ensure Python values align with expected GraphQL types (e.g., `Int`, `Boolean`, `ID`, `Float`).","message":"When defining query arguments with Python types (e.g., `value='some string'`), the library infers GraphQL types. For complex types or specific GraphQL scalar types, ensure the Python value is compatible or explicitly castable, as mismatches can lead to invalid GraphQL queries.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Verify that the `value` argument in `Argument(name='...', value=...)` or other field properties matches the expected scalar type (e.g., string, int, bool, float) or correct list structure if a list is intended.","cause":"Attempting to pass a list or an incorrectly structured value where a single scalar value is expected for a GraphQL argument or field property in the `graphql-query` DSL.","error":"TypeError: 'list' object cannot be interpreted as an integer"},{"fix":"For any field that returns an object type (not a scalar), ensure you pass a list of `Field` objects to its `fields` argument, e.g., `Field(name='user', fields=[Field(name='id'), Field(name='name')])`.","cause":"A `Field` object was created without specifying nested `fields` for a non-leaf GraphQL field, which is required by GraphQL syntax.","error":"graphql_query.exceptions.InvalidGraphqlQuery: Field 'someField' must have a selection of subfields. Did you mean 'someField { ... }'?"},{"fix":"Ensure `graphql-query` is at version 1.3.0 or higher. If you have other Pydantic-dependent libraries, you may need to update them or use Pydantic V2's compatibility features (like `pydantic.v1`) carefully. The `bump-pydantic` tool can help migrate your codebase.","cause":"Your environment has Pydantic V2 installed, but some part of your application (or an older version of `graphql-query`) is trying to import or use Pydantic V1 components, which are no longer directly available or have changed APIs.","error":"PydanticUserError: Pydantic V1 has been removed from Pydantic V2."}]}