graphql-core

GraphQL-core is the foundational GraphQL engine for Python, a faithful port of the official GraphQL.js reference implementation. It provides everything needed to define a GraphQL type system, parse and validate queries against a schema, and execute them, with full support for asyncio-based resolvers.

Rather than being a web framework, it is the low-level library that higher-level tools like Graphene and Strawberry build on. It covers the complete GraphQL specification: lexing and parsing the query language, building and introspecting schemas, validating documents, and executing operations synchronously or asynchronously.

What You Get

• A complete GraphQL type system for defining schemas in code
• A lexer and parser for GraphQL query and schema-definition language
• A spec-compliant validation layer for documents against a schema
• Synchronous and asyncio-based query execution engines
• Schema introspection and utilities for building/printing schemas
• Close parity with the GraphQL.js reference implementation

Common Use Cases

• Building higher-level GraphQL frameworks and libraries on a solid core
• Executing GraphQL queries against a custom schema in a Python service
• Parsing and validating GraphQL documents programmatically
• Introspecting or transforming GraphQL schemas as tooling

Under The Hood

Architecture - GraphQL-core mirrors the module layout of GraphQL.js under src/graphql/: language/ holds the lexer, parser, and AST; type/ defines the schema and type system; validation/ (via utilities/) enforces spec rules; and execution/ runs operations, supporting both sync and asyncio resolvers. The top-level graphql.py exposes the graphql()/graphql_sync() entry points that tie parsing, validation, and execution together.

Tech Stack - Pure Python 3 with no required runtime dependencies, packaged via pyproject.toml, fully type-annotated (ships py.typed), and tested with pytest across a tox matrix. It deliberately tracks the design of graphql-js for cross-language consistency.

Code Quality - This is an exceptionally well-maintained, mature project (health score 90) with a large, thorough tests/ suite ported alongside the implementation, complete type hints, and consistent updates. The one-to-one correspondence with graphql-js makes behavior predictable and auditable.

API Design - The public API centers on graphql()/graphql_sync() plus schema-construction primitives, closely matching graphql-js naming so developers can translate JavaScript examples directly. It is low-level by design, so building a server on it requires more code than a batteries-included framework, but the primitives are clean, well-documented, and composable.