Link to third party libraries in json documentation

Documentation
1

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.

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.

A

4 Likes
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

  1. failed due to recursion error ↩︎

  2. delays creation of Python objects until they are accessed ↩︎

1 Like
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.

7 Likes
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.

10 Likes
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?

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

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

9

That’s awesome. I’m sold.