Link to third party libraries in json documentation (original) (raw)

In the re docs, we have this note:

See also
The third-party regex module, which has an API compatible with the standard library re module, but offers additional functionality and a more thorough Unicode support.

Could we add a similar note for simplejson (or even my own library jsonyx) in the json documentation?

simplejson offers more customisation and is available for a wider range of Python versions.
jsonyx offers low level control of the (de)serialisation, better error messages and has all recent enhancements from the standard library. Migration is harder because it’s configured differently.

I don’t think we should link to ultra fast libraries, because they don’t offer the same features as the standard library.

AA-Turner (Adam Turner) April 23, 2025, 8:50pm 2

A feature those libraries do offer though is better performance, as an intentional trade-off. Whilst the json module documentation is not the right place for an exhaustive list of third-party implementations, I would expect to see at least one of the performance-focussed libraries on such a list, if it were added.

Nineteendo (Nice Zombies) April 24, 2025, 5:03am 3

If we had to pick one, it would have to be orjson:

encode	json	jsonyx	msgspec	orjson	fastest time
List of 256 booleans	4.58x	4.13x	1.05x	1.00x	1.84 μs
List of 256 ASCII strings	14.00x	11.60x	1.57x	1.00x	3.92 μs
List of 256 floats	24.93x	25.59x	1.34x	1.00x	8.28 μs
List of 256 dicts with 1 int	11.58x	12.28x	1.38x	1.00x	7.84 μs
Medium complex object	10.12x	10.40x	1.16x	1.00x	13.87 μs
List of 256 strings	19.70x	14.69x	1.73x	1.00x	18.10 μs
Complex object	7.68x	7.55x	1.00x	DNF[1]	211.43 μs
Dict with 256 lists of 256 dicts with 1 int	4.52x	5.43x	3.20x	1.00x	5082.41 μs

decode	json	jsonyx	msgspec	orjson	simdjson[2]	fastest time
List of 256 booleans	5.62x	5.07x	3.59x	1.48x	1.00x	1.50 μs
List of 256 ASCII strings	7.01x	6.08x	3.69x	3.37x	1.00x	4.07 μs
List of 256 floats	10.84x	11.22x	2.25x	1.73x	1.00x	6.11 μs
List of 256 dicts with 1 int	12.94x	11.52x	7.11x	5.16x	1.00x	6.12 μs
Medium complex object	13.06x	12.24x	5.27x	4.47x	1.00x	7.83 μs
List of 256 strings	6.80x	3.69x	9.48x	7.88x	1.00x	16.98 μs
Complex object	9.89x	7.84x	9.01x	8.00x	1.00x	130.54 μs
Dict with 256 lists of 256 dicts with 1 int	18.73x	15.92x	11.58x	9.65x	1.00x	1624.49 μs

failed due to recursion error ↩︎
delays creation of Python objects until they are accessed ↩︎

pitrou (Antoine Pitrou) April 24, 2025, 7:49am 4

The reason the re docs link to the regex library is that it’s the single well-known widely-used third-party alternative to re, with arguably superior features. If there are multiple third-party JSON libraries, then it’s a good reason not to choose and list any one of them explicitly. We could instead add a generic note such as:

The standard json module provides a complete, compliant implementation of the JSON specification and should be sufficient for most use cases. However, in the case that more functionality is required than json offers, third-party alternatives can be found on PyPI.

Rosuav (Chris Angelico) April 24, 2025, 7:52am 5

I’m not convinced even that is necessary. The stdlib json module is fine for the vast majority of use cases, and if you need something else, you should already know that PyPI exists. Having the note will just send people off onto a completely unnecessary tangent, researching options that most likely won’t make a difference.

JamesParrott (James Parrott) April 24, 2025, 8:25am 6

Do any of them let you map a JSON array to a set (or dict with None values to preserve order) without first making it into a list?

Nineteendo (Nice Zombies) April 24, 2025, 9:02am 7

>>> jsonyx.loads("[1, 2, 1]", hooks={"array": set})
{1, 2}
>>> jsonyx.loads("[1, 2, 1]", hooks={"array": dict.fromkeys})
{1: None, 2: None}

Nineteendo (Nice Zombies) April 24, 2025, 9:05am 8

OK, that makes sense. I don’t think it’s worth pursuing this further then.

JamesParrott (James Parrott) April 24, 2025, 10:56am 9

That’s awesome. I’m sold.