Registry / serialization / graphql-query

graphql-query

library1.4.0pypypi✓ verified 84d ago

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.

serialization http-networking

pip install graphql-query

github ↗package ↗docs ↗

INSTALL

IMPORT

SIG · GRAPHQL-QUERY

graphql-query

serializationpythonv1.4.0

Install

3.4s avg

Import

674ms

Disk

27MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.4.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.703s · 29.1MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 3.4s · import 0.645s · 29MB

27MB installed

● package 27MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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

Debug

Known issues

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

affects: >=1.2.0

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

affects: >=1.3.1

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

affects: >=1.1.1

gotchaWhen 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`).

affects: All

Errors

Common errors & fixes

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

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 { ... }'?

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.

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.

Upgrade

Version history

1.4.0latest on PyPI · released Jul 31, 2024

Audit

Dependencies

pydantic>=2requiredCore dependency for data modeling and validation, migrated in v1.3.0/v1.2.0. Users must use Pydantic v2 or later.

Agent activity

10 hits · last 30 days

node

Resources

githubhttps://github.com/denisart/graphql-query ↗

packagehttps://pypi.org/project/graphql-query/ ↗

docshttps://denisart.github.io/graphql-query/ ↗