---
id: graphql-query
version: "1.4.0"
license: unclear
license_treatment: permissive
maintenance: dormant
---

# graphql-query — Complete Domain Specific Language (DSL) for GraphQL query in Python.

License: permissive · Maintenance: dormant · Downloads: 277.6K/mo

## What it is and what it does

graphql-query is a Python DSL for constructing GraphQL query strings from Python code. Instead of writing raw GraphQL strings, you build queries using Python classes like Query, Field, Argument, Variable, Fragment, and Directive, then call render() to produce the final GraphQL string. It depends on jinja2 for templating and pydantic for data validation, and supports modern Python versions from 3.8 onward.

The package is designed for scenarios where you want to programmatically assemble queries, reuse common arguments and variables across multiple queries, or generate query classes from pydantic models. It handles simple field selection, complex arguments with variables, inline fragments, and directives like @include and @skip.

Use it for:

- Build GraphQL queries dynamically in client applications without concatenating strings or managing raw query text.
- Share and reuse common Arguments, Variables, and Fragments across multiple queries in a codebase.
- Generate GraphQL query classes from existing pydantic data models to keep query structure in sync with your Python types.
- Construct queries with conditional fields and directives (e.g., @include, @skip) based on runtime logic.
- Test GraphQL APIs by programmatically generating test queries with varying arguments and field selections.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Builds GraphQL query strings programmatically in Python using a domain-specific language, letting you construct queries from Python classes instead of writing raw GraphQL strings.

Yes, if you need to generate GraphQL queries programmatically and want type-safe, reusable query construction. The low install friction, permissive MIT license, and support for modern Python versions make it straightforward to adopt. The dormant maintenance status is a minor concern—no active vulnerabilities and the last commit is recent—but verify compatibility with your pydantic and jinja2 versions before relying on it for production systems.

## Install

pip install graphql-query
uv add graphql-query
poetry add graphql-query

## Installing graphql-query

Before you install: Low friction install with only jinja2 and pydantic as runtime dependencies. Maintenance is dormant—last commit was 2024-11-26 and no releases in the past 744 days—but the repository remains active and unarchived.

License in practice: MIT license (permissive) means you can use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.

Quickstart:

pip install graphql-query

from graphql_query import Operation, Query

hero = Query(name="hero", fields=["name"])
operation = Operation(type="query", queries=[hero])
print(operation.render())

Verify before relying:

- Whether the dormant maintenance status (no releases in 744 days) affects compatibility with recent GraphQL schema changes or breaking updates in jinja2/pydantic.
- Real-world performance or scalability limits when generating very large or deeply nested GraphQL queries.
- Whether generated queries are validated against a GraphQL schema or only syntactically correct.

## Package facts

- License: not declared (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: dormant
- Downloads: 277.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

graphql query builder python, generate graphql queries programmatically, graphql dsl python, python graphql query generator, graphql query construction library, graphql arguments variables python, pydantic graphql codegen, graphql, code-generation, query-builder

[View on SkillFed](https://skillfed.io/packages/graphql-query) · [View on PyPI](https://pypi.org/project/graphql-query/)