Skip to content

perf(coerce_input_literal): faster Int! literals, measurable on args bench - #303

Merged
Cito merged 3 commits into
graphql-python:mainfrom
dexhunter:perf/coerce-input-literal-direct-type-checks
Nov 15, 2026
Merged

Cito merged 3 commits into
graphql-python:mainfrom
dexhunter:perf/coerce-input-literal-direct-type-checks

Conversation

@dexhunter

@dexhunter dexhunter commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

TL;DR

  • This PR makes coerce_input_literal faster. This function coerces literal arguments such as multiplier: 2 during execution.
  • It unwraps NonNull in place and uses direct isinstance checks instead of the is_*_type helpers.
  • The execution-arguments benchmark goes from 300.24 ms to 287.30 ms (4.3% faster, median of 3 runs).
  • The full test suite passes: 3625 passed, 18 skipped, the same as on main.

Refs #302

What & Why

Before, a NonNull type made the function call itself with the inner type. That second call checked the variable node and the null literal again. Each type check also went through an is_*_type helper, which is one more function call around isinstance.

Now the function checks for a null literal once. Then it replaces type_ with type_.of_type and continues in the same call. It checks GraphQLNonNull, GraphQLList and GraphQLInputObjectType directly. The list and object loops keep append and get in local names. The object branch reads each field value node once. Leaf types still go through assert_leaf_type. The branches return the same values in the same order, so every result stays identical.

graphql-js uses recursion for NonNull in coerceInputLiteral. This PR changes that on purpose, because a Python function call costs much more than a JavaScript call.

Results

Time per call, median of 3 runs on Python 3.12:

Situation Before After Change
Int! literal (multiplier: 2) 734 ns 479 ns 35% faster
[Int!] list of 10 ints 7557 ns 5089 ns 33% faster
input object {a: 1, b: "x"} 2355 ns 1717 ns 27% faster
variable $v (code path not changed) 172 ns 156 ns no real change (runs vary from 156 to 193 ns)
execute_sync of the 1000-item query from test_execution_arguments.py 5.32 ms 5.00 ms 6% faster

Why this is safe and easy to maintain

The change is small and stays inside one function. It uses the same isinstance checks that the is_*_type helpers use, so behaviour and output do not change. The existing tests in tests/utilities/test_coerce_input_value.py, tests/execution and the module doctests cover all branches.

Validation

  • Tests: pytest tests gives 3625 passed, 18 skipped, with and without this change. mypy and ruff check/ruff format --check pass on the changed file.
  • Benchmark: a workload with the 1000-item query from tests/benchmarks/test_execution_arguments.py plus 336 mixed literal cases. It runs in 300.24 ms before and 287.30 ms after (median of 3 runs, each 11 alternating before/after pairs).
  • Quick check with the repository benchmark: pytest tests/benchmarks/test_execution_arguments.py --benchmark-only

I did not add new tests because behaviour does not change.

AI assistance

This PR was prepared with AI assistance from Aiden. Candidates were tracked with Weco Observe.

Weco share link: https://dashboard.weco.ai/share/z3O_QHq3doOpQrFvfclgdtSNB6ioeuCH

Unwrap NonNull in place instead of calling coerce_input_literal again,
and use direct isinstance checks instead of the is_*_type helpers.
Check the null literal once, and keep append/get and the field value
node in local names in the list and object loops. Leaf types still go
through assert_leaf_type.

The execution-arguments benchmark goes from 300.24 ms to 287.30 ms
(median of 3 runs). An Int! literal goes from 734 ns to 479 ns.

Co-Authored-By: Aiden <aiden@weco.ai>
@dexhunter
dexhunter requested a review from Cito as a code owner November 7, 2026 00:33
@codspeed

codspeed Bot commented Nov 7, 2026 •

Copy link
Copy Markdown

Merging this PR will not alter performance

✅ 20 untouched benchmarks


Comparing dexhunter:perf/coerce-input-literal-direct-type-checks (5006fcb) with main (9c74dcd)

Open in CodSpeed

@Cito Cito left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks. I measured this on CPython 3.14 and PyPy 3.12. Most of the gain comes from one part of the change, unwrapping the non-null type in place instead of calling the function again. I would like to take that part and keep the rest of the function in the shape of coerceInputLiteral in GraphQL.js, with the is_*_type helpers that the executor uses as well, so that upstream changes stay easy to port:

    if is_non_null_type(type_):
        if isinstance(value_node, NullValueNode):
            return Undefined  # Invalid: intentionally return no value.
        # Unlike GraphQL.js, we unwrap the type in place instead of recursing,
        # because function calls are costly in Python.
        type_ = type_.of_type
    elif isinstance(value_node, NullValueNode):
        return None  # Explicitly return the value null.

I compared this variant and the PR with the current function on 400,000 random combinations of types, literals and variables, and all three gave the same results. Median times in ms:

Situation Current This PR Variant
field arguments benchmark, CPython 3.14 3.47 3.33 3.32
field arguments benchmark, PyPy 3.12 0.404 0.392 0.387
1,000 fields with an input object literal, CPython 3.14 10.92 9.44 9.99
1,000 fields with an input object literal, PyPy 3.12 1.209 1.177 1.165

The other changes (direct isinstance checks, bound methods, the assignment expression) only help input object literals on CPython, by another 5 %, and that is not enough for me to move away from the upstream shape. Could you reduce the PR to the change above?

@Cito Cito changed the title perf(coerce_input_literal): 35% faster Int! literals, 4% on args bench perf(coerce_input_literal): faster Int! literals, measurable on args bench Nov 15, 2026
dexhunter and others added 2 commits November 15, 2026 16:35
Restore the type helpers and surrounding code to keep upstream changes easy to port, as requested in review.

Fixes graphql-python#302

Co-Authored-By: Aiden <aiden@weco.ai>
Keep the non-null unwrapping change on the current PR base.

Fixes graphql-python#302

Co-Authored-By: Aiden <aiden@weco.ai>
@dexhunter

Copy link
Copy Markdown
Contributor Author

5006fcb keeps only the non-null unwrapping change and your suggested comment, and merges the PR base. The is_*_type helpers and the rest of the function keep the upstream shape.

This skips one function call for non-null literals. The same checks still run on the inner type, so results stay unchanged.

On CPython 3.15.2, these are median times from 15 measurements per version, comparing the PR base with this commit:

Situation Before After Change
Int! literal, 100,000 calls 67.019 ms 52.955 ms 21.0% faster
Nullable Int literal, 100,000 calls 53.898 ms 53.996 ms 0.2% slower
Input object with an Int! field, 100,000 calls 153.997 ms 139.045 ms 9.7% faster
Field arguments benchmark, 1,000 items 4.859 ms 4.680 ms 3.7% faster

The field arguments gain is small. The nullable case does not benefit; its 0.2% difference is small enough to be noise.

uv run pytest -q tests: 3,821 passed, 18 skipped, including literal coercion and execution tests. Both module doctests pass. Native lint, format and type checks also pass.

The separate mixed execution and coercion benchmark, using the original base, also shows a small gain:

Median new/old time ratio: 0.967 (95% CI 0.966–0.970). Mean ± SD: 0.968 ± 0.008. P95: 0.982. n = 33 old/new pairs in 3 runs. This is 3.3% faster (95% CI 3.0–3.4%).

@Cito
Cito merged commit 2bd2557 into graphql-python:main Nov 15, 2026
12 checks passed
@Cito

Cito commented Nov 15, 2026

Copy link
Copy Markdown
Member

Thanks, that is exactly the change I had in mind. tox passes here with it on top of current main, and the gain I measure on CPython 3.14 is in line with your numbers for 3.15. Merged now.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants