Skip to content

perf(assert_name): skip per-char generator - faster schema build - #305

Merged
Cito merged 3 commits into
graphql-python:mainfrom
dexhunter:perf/assert-name-isidentifier
Nov 15, 2026
Merged

Cito merged 3 commits into
graphql-python:mainfrom
dexhunter:perf/assert-name-isidentifier

Conversation

@dexhunter

@dexhunter dexhunter commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

TL;DR

  • Make assert_name() faster, which runs for every name during schema construction.
  • Valid names now return after two C-level string checks instead of one Python call per character.
  • build_ast_schema benchmark on the GitHub SDL, median of best times: 14.40 ms -> 10.79 ms, 25.0% faster.
  • PYTHONPATH=src python -m pytest tests -q: 3625 passed, 18 skipped.

Refs #304

What & Why

Before, assert_name() checked the name tail with a generator.
It called is_name_continue() once for each character, so long names cost many Python calls.

Now it first checks isinstance(name, str) and name.isascii() and name.isidentifier().
For ASCII text, a Python identifier is exactly a GraphQL name: [_a-zA-Z][_a-zA-Z0-9]*.
Valid names return at once.

Invalid names keep the same checks in the same order, so each error type and message stays the same.
The tail check now uses name[1:].replace("_", "") with isascii() and isalnum().
If the tail is valid but the name is not, only the first character can be wrong.
The code then raises the "must start with" error.

Results

Situation Before After Change
build_ast_schema on the GitHub SDL (assume_valid=True) 14.40 ms 10.79 ms 25.0% less time
build_client_schema on the GitHub introspection result 13.97 ms 10.43 ms 25.3% less time
assert_name on 10,000 valid names 6.94 ms 0.69 ms 90.0% less time
assert_name on 10,000 invalid names 13.32 ms 8.62 ms 35.3% less time
parse on the large query (does not call assert_name) 38.43 ms 37.90 ms No change (within noise)

Each value is the best of 15 runs, then the median of 7 alternating processes per version.
CPython 3.12.13, Linux x86-64, AMD EPYC 9R14, one dedicated CPU core.

Why this is safe and easy to maintain

The change touches one function and adds no new helpers or dependencies.
Valid names give the same return value, and invalid names give the same exception class and message.
tests/type/test_assert_name.py, the schema build tests and the doctests in the module cover these cases.

Validation

  • PYTHONPATH=src python -m pytest tests -q: 3625 passed, 18 skipped.
  • PYTHONPATH=src python -m pytest --doctest-modules src/graphql/type/assert_name.py: 2 passed.
  • Benchmark: pytest tests/benchmarks/test_build_ast_schema.py tests/benchmarks/test_build_client_schema.py --benchmark-only.

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/nBw9xQ9xWsK2u9f9hqyIJaqqBFFOsN7L

assert_name() checked the name tail with a generator that called
is_name_continue() once per character. For ASCII text, str.isidentifier()
is true exactly for [_a-zA-Z][_a-zA-Z0-9]*, so valid names now return
after isascii() and isidentifier(). Invalid names keep the same checks
in the same order, so error classes and messages are unchanged.

build_ast_schema on the GitHub SDL: 14.40 ms -> 10.79 ms (25% less time).

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

codspeed Bot commented Nov 7, 2026 •

Copy link
Copy Markdown

Merging this PR will improve performance by 46.43%

1 warning

⚠️ 2 benchmarks with a significant change ran on different hardware

Their base and head results were measured on machines with a different CPU, core count or memory, so the changes might not come from the code. Run base and head on the same runner type.

Learn more about Macro Runners

See affected benchmarks

⚡ 2 improved benchmarks
✅ 18 untouched benchmarks

Performance Changes

Benchmark BASE HEAD Efficiency
⚡ test_build_schema_from_ast 225.5 ms 152.1 ms +48.29%
⚡ test_build_schema_from_introspection 237.9 ms 164.5 ms +44.6%

Tip

Curious why performance improved? Comment @codspeedbot explain why performance improved on this PR, or directly use the CodSpeed MCP with your agent.


Comparing dexhunter:perf/assert-name-isidentifier (c054419) with main (c56d337)

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, the fast path is a nice gain. I would like to keep only that part, though. The rewritten tail check for invalid names brings no measurable gain for schema building, and I prefer to keep the error path in the same shape as assertName in GraphQL.js, so that future upstream changes stay easy to port.

Could you reduce the change to the shortcut, placed after the type checks, like this?

    if not name:
        msg = "Expected name to be a non-empty string."
        raise GraphQLError(msg)
    if name.isascii() and name.isidentifier():
        return name  # an ASCII identifier is exactly a GraphQL name
    if not all(is_name_continue(char) for char in name[1:]):

The rest of the function and the imports stay as they are.

I compared it with the current function on 536,875 names (random strings, plus every character up to U+2FFF alone, before and after a letter). The result and the error message were the same in every case. Best times in ms:

Situation Current This PR Variant
build_ast_schema, GitHub SDL, CPython 3.14 6.95 5.46 5.49
build_client_schema, GitHub introspection, CPython 3.14 7.23 5.53 5.55
build_ast_schema, GitHub SDL, PyPy 3.12 2.20 1.94 1.91
build_client_schema, GitHub introspection, PyPy 3.12 2.19 1.78 1.66

Keep the ASCII identifier shortcut after the type and empty-name checks. Restore the original imports and invalid-name checks to ease GraphQL.js updates.

Fixes graphql-python#304

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

Copy link
Copy Markdown
Contributor Author

Updated in de48748. The shortcut now follows the type and empty-name checks, exactly as suggested. The original imports and error checks are restored.

PYTHONPATH=src python -m pytest tests -q: 3,625 passed, 18 skipped. Both module doctests passed. The src and tests lint and format checks passed.

With the shortcut, an ordinary valid name never reaches the final return.
A str subclass that does not take the shortcut does, which keeps the
coverage at 100 % and checks that both paths accept the same names.
@Cito
Cito merged commit 75ce051 into graphql-python:main Nov 15, 2026
12 checks passed
@Cito Cito changed the title perf(assert_name): skip per-char generator -- 25% faster schema build perf(assert_name): skip per-char generator - faster schema build Nov 15, 2026
@Cito

Cito commented Nov 15, 2026

Copy link
Copy Markdown
Member

Thanks, that is exactly the change I had in mind. The failing check on Python 3.14 is my fault, not yours: with the shortcut every valid name returns early, so the final return name can no longer be reached, and that job requires full coverage. I have pushed a commit to your branch that adds a test for that line (a str subclass that does not take the shortcut), so the function itself stays as you have it. 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