Convert _json to Argument Clinic

@hnnynh

Proposal:

As discussed in #137630 (comment), for @hnnynh at the PyCon Korea sprints

cc @corona10

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

Links to previous discussion of this feature:

No response

Linked PRs

@hnnynh

@hnnynh plan to take a look at this issue :)

Thank you for all your support @AA-Turner !

@serhiy-storchaka

What about performance? AC induces a slight overhead so we should be careful about it. cc @serhiy-storchaka

Yep, I would expect the PR to run the JSON benchmarks.

We also need macro benchmarks

Yoonho Hann, please consider writing a benchmark script using pyperf or timeit. But please write a draft PR first :)

Plan to directly mentor her for this issue.

@corona10

Sorry for the delay in sharing. It took me a little while to understand what needed to be done.
I received guidance from @corona10 on how to start the work (two commit links below) and was able to plan my tasks.

corona10@fe54046
corona10@d4ca8d3

I'll aim to submit a PR by next week.

@hnnynh

Just for the record, I synced up with @hnnynh about the current progress and shared some advice on next steps.”

gh-137821: Convert _json module to use Argument Clinic (gh-140778)

pythongh-137821: Improve Argument Clinic definitions in the _json module

pythongh-137821: Fix wrongly tested json.decoder.scanstring

[3.14] pythongh-137821: Fix wrongly tested json.decoder.scanstring

gh-137821: Improve Argument Clinic definitions in the ``_json`` module (

[3.13] gh-137821: Fix wrongly tested json.decoder.scanstring (gh-140781)

[3.14] gh-137821: Fix wrongly tested json.decoder.scanstring (gh-140782)

@hnnynh

Thanks @hnnynh for adding a microbenchmark also!
With the latest changes related to this issue, overall performance has improved noticeably also!

performance

encode_basestring_ascii_medium: Mean +- std dev: [base] 2.47 us +- 0.04 us -> [ac] 2.42 us +- 0.02 us: 1.02x faster
encode_basestring_medium: Mean +- std dev: [base] 2.74 us +- 0.01 us -> [ac] 2.73 us +- 0.01 us: 1.01x faster
encode_basestring_medium_escapes: Mean +- std dev: [base] 21.5 us +- 0.6 us -> [ac] 21.3 us +- 0.1 us: 1.01x faster
scanstring_medium: Mean +- std dev: [base] 230 ns +- 4 ns -> [ac] 177 ns +- 3 ns: 1.29x faster

Benchmark hidden because not significant (3): encode_basestring_ascii_medium_escapes, encode_basestring_ascii_medium_unicode, encode_basestring_medium_unicode

Geometric mean: 1.04x faster

script

import pyperf
import _json

# Test data - medium objects (typical API responses)
medium_string = "The quick brown fox jumps over the lazy dog. " * 20  # ~900 chars
medium_string_with_escapes = '''Line 1: "status": "success"
Line 2: Response received at 2024-01-15T10:30:00Z
\tError code: null
\tMessage: "Operation completed successfully"
''' * 50
medium_unicode = "User: 김철수 | Email: user@example.com | Status: ✓ Active | Location: 東京都 | Rating: ★★★★☆ | " * 30
medium_json_string = '"' + '{"id": 12345, "name": "John Doe", "email": "john@example.com"}' * 20 + '"'


def bench_encode_basestring_ascii(s):
    return _json.encode_basestring_ascii(s)


def bench_encode_basestring(s):
    return _json.encode_basestring(s)


def bench_scanstring(s):
    # scanstring takes (string, end, strict=True)
    # end is the index after the opening quote
    return _json.scanstring(s, 1, True)


runner = pyperf.Runner()

# encode_basestring_ascii benchmarks
runner.bench_func("encode_basestring_ascii_medium", bench_encode_basestring_ascii, medium_string)
runner.bench_func("encode_basestring_ascii_medium_escapes", bench_encode_basestring_ascii, medium_string_with_escapes)
runner.bench_func("encode_basestring_ascii_medium_unicode", bench_encode_basestring_ascii, medium_unicode)
# encode_basestring benchmarks
runner.bench_func("encode_basestring_medium", bench_encode_basestring, medium_string)
runner.bench_func("encode_basestring_medium_escapes", bench_encode_basestring, medium_string_with_escapes)
runner.bench_func("encode_basestring_medium_unicode", bench_encode_basestring, medium_unicode)

# scanstring benchmarks
runner.bench_func("scanstring_medium", bench_scanstring, medium_json_string)

pythongh-137821: Convert _json module to use Argument Clinic (pythong…

pythongh-137821: Improve Argument Clinic definitions in the ``_json``…

Navigation Menu

Repository navigation

Convert `_json` to Argument Clinic #137821

Proposal:

Has this already been discussed elsewhere?

Links to previous discussion of this feature:

Linked PRs

performance

script

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Convert _json to Argument Clinic #137821

Description

Proposal:

Has this already been discussed elsewhere?

Links to previous discussion of this feature:

Linked PRs

Activity

corona10 commented on Aug 15, 2025

picnixz commented on Aug 15, 2025

AA-Turner commented on Aug 15, 2025

picnixz commented on Aug 15, 2025

corona10 commented on Aug 15, 2025

corona10 commented on Aug 23, 2025

hnnynh commented on Sep 1, 2025

corona10 commented on Sep 26, 2025

corona10 commented on Oct 30, 2025

performance

script

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

Convert `_json` to Argument Clinic #137821