GraphQL Query DSL for Python

Common errors

• TypeError: 'list' object cannot be interpreted as an integer

  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.
  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.

• graphql_query.exceptions.InvalidGraphqlQuery: Field 'someField' must have a selection of subfields. Did you mean 'someField { ... }'?

  cause A `Field` object was created without specifying nested `fields` for a non-leaf GraphQL field, which is required by GraphQL syntax.
  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')])`.

• PydanticUserError: Pydantic V1 has been removed from Pydantic V2.

  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.
  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.

Warnings

• breaking 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.
  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.
• breaking Python 3.7 support was dropped in version 1.3.1. The library now requires Python 3.8 or newer.
  Fix: Ensure your project runs on Python 3.8 or a later version.
• deprecated 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.
  Fix: Review your project's direct `graphql-core` usage. Add `pip install graphql-core` if still needed independently of `graphql-query`.
• gotcha 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.
  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`).

Install

• pip install graphql-query Install latest version

Imports

• Query

  from graphql_query import Query

  Main class for building a GraphQL query operation.
• Field

  from graphql_query import Field

  Used to define fields within a GraphQL query or sub-selection.
• Argument

  from graphql_query import Argument

  Used to define arguments for fields or queries.

Quickstart

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.

from graphql_query import Query, Field, Argument

# Example 1: Simple Query
simple_query = Query(
    name="myQuery",
    fields=[
        Field(name="hero", fields=[Field(name="name")]),
    ]
)
print(f"Simple Query: {simple_query.render()}")
# Expected output: { myQuery { hero { name } } }

# Example 2: Query with Arguments
query_with_args = Query(
    name="character",
    arguments=[
        Argument(name="id", value="1000")
    ],
    fields=[
        Field(name="name"),
        Field(name="appearsIn")
    ]
)
print(f"Query with Arguments: {query_with_args.render()}")
# Expected output: query character($id: String = "1000") { character(id: $id) { name appearsIn } }