# orjson
orjson is a fast, correct JSON library for Python. It
[benchmarks](https://github.com/ijl/orjson?tab=readme-ov-file#performance) as the fastest Python
library for JSON and is more correct than the standard json library or other
third-party libraries. It serializes
[dataclass](https://github.com/ijl/orjson?tab=readme-ov-file#dataclass),
[datetime](https://github.com/ijl/orjson?tab=readme-ov-file#datetime),
[numpy](https://github.com/ijl/orjson?tab=readme-ov-file#numpy), and
[UUID](https://github.com/ijl/orjson?tab=readme-ov-file#uuid) instances natively.
Its features and drawbacks compared to other Python JSON libraries:
* serializes `dataclass` instances 40-50x as fast as other libraries
* serializes `datetime`, `date`, and `time` instances to RFC 3339 format,
e.g., "1970-01-01T00:00:00+00:00"
* serializes `numpy.ndarray` instances 4-12x as fast with 0.3x the memory
usage of other libraries
* pretty prints 10x to 20x as fast as the standard library
* serializes to `bytes` rather than `str`, i.e., is not a drop-in replacement
* serializes `str` without escaping unicode to ASCII, e.g., "好" rather than
"\\\u597d"
* serializes `float` 10x as fast and deserializes twice as fast as other
libraries
* serializes subclasses of `str`, `int`, `list`, and `dict` natively,
requiring `default` to specify how to serialize others
* serializes arbitrary types using a `default` hook
* has strict UTF-8 conformance, more correct than the standard library
* has strict JSON conformance in not supporting Nan/Infinity/-Infinity
* has an option for strict JSON conformance on 53-bit integers with default
support for 64-bit
* does not provide `load()` or `dump()` functions for reading from/writing to
file-like objects
orjson supports CPython 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, and 3.14.
It distributes amd64/x86_64, aarch64/armv8, arm7, POWER/ppc64le, and s390x
wheels for Linux, amd64 and aarch64 wheels for macOS, and amd64
and i686/x86 wheels for Windows.
orjson does not and will not support PyPy, embedded Python builds for
Android/iOS, or PEP 554 subinterpreters.
Releases follow semantic versioning and serializing a new object type
without an opt-in flag is considered a breaking change.
orjson is licensed under both the Apache 2.0 and MIT licenses. The
repository and issue tracker is
[github.com/ijl/orjson](https://github.com/ijl/orjson), and patches may be
submitted there. There is a
[CHANGELOG](https://github.com/ijl/orjson/blob/master/CHANGELOG.md)
available in the repository.
1. [Usage](https://github.com/ijl/orjson?tab=readme-ov-file#usage)
1. [Install](https://github.com/ijl/orjson?tab=readme-ov-file#install)
2. [Quickstart](https://github.com/ijl/orjson?tab=readme-ov-file#quickstart)
3. [Migrating](https://github.com/ijl/orjson?tab=readme-ov-file#migrating)
4. [Serialize](https://github.com/ijl/orjson?tab=readme-ov-file#serialize)
1. [default](https://github.com/ijl/orjson?tab=readme-ov-file#default)
2. [option](https://github.com/ijl/orjson?tab=readme-ov-file#option)
3. [Fragment](https://github.com/ijl/orjson?tab=readme-ov-file#fragment)
5. [Deserialize](https://github.com/ijl/orjson?tab=readme-ov-file#deserialize)
2. [Types](https://github.com/ijl/orjson?tab=readme-ov-file#types)
1. [dataclass](https://github.com/ijl/orjson?tab=readme-ov-file#dataclass)
2. [datetime](https://github.com/ijl/orjson?tab=readme-ov-file#datetime)
3. [enum](https://github.com/ijl/orjson?tab=readme-ov-file#enum)
4. [float](https://github.com/ijl/orjson?tab=readme-ov-file#float)
5. [int](https://github.com/ijl/orjson?tab=readme-ov-file#int)
6. [numpy](https://github.com/ijl/orjson?tab=readme-ov-file#numpy)
7. [str](https://github.com/ijl/orjson?tab=readme-ov-file#str)
8. [uuid](https://github.com/ijl/orjson?tab=readme-ov-file#uuid)
3. [Testing](https://github.com/ijl/orjson?tab=readme-ov-file#testing)
4. [Performance](https://github.com/ijl/orjson?tab=readme-ov-file#performance)
1. [Latency](https://github.com/ijl/orjson?tab=readme-ov-file#latency)
2. [Memory](https://github.com/ijl/orjson?tab=readme-ov-file#memory)
3. [Reproducing](https://github.com/ijl/orjson?tab=readme-ov-file#reproducing)
5. [Questions](https://github.com/ijl/orjson?tab=readme-ov-file#questions)
6. [Packaging](https://github.com/ijl/orjson?tab=readme-ov-file#packaging)
7. [License](https://github.com/ijl/orjson?tab=readme-ov-file#license)
## Usage
### Install
To install a wheel from PyPI, install the `orjson` package.
In `requirements.in` or `requirements.txt` format, specify:
```txt
orjson>=3.10,<4
```
In Poetry, specify:
```toml
orjson = "^3"
```
To build a wheel, see [packaging](https://github.com/ijl/orjson?tab=readme-ov-file#packaging).
### Quickstart
This is an example of serializing, with options specified, and deserializing:
```python
>>> import orjson, datetime, numpy
>>> data = {
"type": "job",
"created_at": datetime.datetime(1970, 1, 1),
"status": "🆗",
"payload": numpy.array([[1, 2], [3, 4]]),
}
>>> orjson.dumps(data, option=orjson.OPT_NAIVE_UTC | orjson.OPT_SERIALIZE_NUMPY)
b'{"type":"job","created_at":"1970-01-01T00:00:00+00:00","status":"\xf0\x9f\x86\x97","payload":[[1,2],[3,4]]}'
>>> orjson.loads(_)
{'type': 'job', 'created_at': '1970-01-01T00:00:00+00:00', 'status': '🆗', 'payload': [[1, 2], [3, 4]]}
```
### Migrating
orjson version 3 serializes more types than version 2. Subclasses of `str`,
`int`, `dict`, and `list` are now serialized. This is faster and more similar
to the standard library. It can be disabled with
`orjson.OPT_PASSTHROUGH_SUBCLASS`.`dataclasses.dataclass` instances
are now serialized by default and cannot be customized in a
`default` function unless `option=orjson.OPT_PASSTHROUGH_DATACLASS` is
specified. `uuid.UUID` instances are serialized by default.
For any type that is now serialized,
implementations in a `default` function and options enabling them can be
removed but do not need to be. There was no change in deserialization.
To migrate from the standard library, the largest difference is that
`orjson.dumps` returns `bytes` and `json.dumps` returns a `str`. Users with
`dict` objects using non-`str` keys should specify
`option=orjson.OPT_NON_STR_KEYS`. `sort_keys` is replaced by
`option=orjson.OPT_SORT_KEYS`. `indent` is replaced by
`option=orjson.OPT_INDENT_2` and other levels of indentation are not
supported.
### Serialize
```python
def dumps(
__obj: Any,
default: Optional[Callable[[Any], Any]] = ...,
option: Optional[int] = ...,
) -> bytes: ...
```
`dumps()` serializes Python objects to JSON.
It natively serializes
`str`, `dict`, `list`, `tuple`, `int`, `float`, `bool`, `None`,
`dataclasses.dataclass`, `typing.TypedDict`, `datetime.datetime`,
`datetime.date`, `datetime.time`, `uuid.UUID`, `numpy.ndarray`, and
`orjson.Fragment` instances. It supports arbitrary types through `default`. It
serializes subclasses of `str`, `int`, `dict`, `list`,
`dataclasses.dataclass`, and `enum.Enum`. It does not serialize subclasses
of `tuple` to avoid serializing `namedtuple` objects as arrays. To avoid
serializing subclasses, specify the option `orjson.OPT_PASSTHROUGH_SUBCLASS`.
The output is a `bytes` object containing UTF-8.
The global interpreter lock (GIL) is held for the duration of the call.
It raises `JSONEncodeError` on an unsupported type. This exception message
describes the invalid object with the error message
`Type is not JSON serializable: ...`. To fix this, specify
[default](https://github.com/ijl/orjson?tab=readme-ov-file#default).
It raises `JSONEncodeError` on a `str` that contains invalid UTF-8.
It raises `JSONEncodeError` on an integer that exceeds 64 bits by default or,
with `OPT_STRICT_INTEGER`, 53 bits.
It raises `JSONEncodeError` if a `dict` has a key of a type other than `str`,
unless `OPT_NON_STR_KEYS` is specified.
It raises `JSONEncodeError` if the output of `default` recurses to handling by
`default` more than 254 levels deep.
It raises `JSONEncodeError` on circular references.
It raises `JSONEncodeError` if a `tzinfo` on a datetime object is
unsupported.
`JSONEncodeError` is a subclass of `TypeError`. This is for compatibility
with the standard library.
If the failure was caused by an exception in `default` then
`JSONEncodeError` chains the original exception as `__cause__`.
#### default
To serialize a subclass or arbitrary types, specify `default` as a
callable that returns a supported type. `default` may be a function,
lambda, or callable class instance. To specify that a type was not
handled by `default`, raise an exception such as `TypeError`.
```python
>>> import orjson, decimal
>>>
def default(obj):
if isinstance(obj, decimal.Decimal):
return str(obj)
raise TypeError
>>> orjson.dumps(decimal.Decimal("0.0842389659712649442845"))
JSONEncodeError: Type is not JSON serializable: decimal.Decimal
>>> orjson.dumps(decimal.Decimal("0.0842389659712649442845"), default=default)
b'"0.0842389659712649442845"'
>>> orjson.dumps({1, 2}, default=default)
orjson.JSONEncodeError: Type is not JSON serializable: set
```
The `default` callable may return an object that itself
must be handled by `default` up to 254 times before an exception
is raised.
It is important that `default` raise an exception if a type cannot be handled.
Python otherwise implicitly returns `None`, which appears to the caller
like a legitimate value and is serialized:
```python
>>> import orjson, json, rapidjson
>>>
def default(obj):
if isinstance(obj, decimal.Decimal):
return str(obj)
>>> orjson.dumps({"set":{1, 2}}, default=default)
b'{"set":null}'
>>> json.dumps({"set":{1, 2}}, default=default)
'{"set":null}'
>>> rapidjson.dumps({"set":{1, 2}}, default=default)
'{"set":null}'
```
#### option
To modify how data is serialized, specify `option`. Each `option` is an integer
constant in `orjson`. To specify multiple options, mask them together, e.g.,
`option=orjson.OPT_STRICT_INTEGER | orjson.OPT_NAIVE_UTC`.
##### OPT_APPEND_NEWLINE
Append `\n` to the output. This is a convenience and optimization for the
pattern of `dumps(...) + "\n"`. `bytes` objects are immutable and this
pattern copies the original contents.
```python
>>> import orjson
>>> orjson.dumps([])
b"[]"
>>> orjson.dumps([], option=orjson.OPT_APPEND_NEWLINE)
b"[]\n"
```
##### OPT_INDENT_2
Pretty-print output with an indent of two spaces. This is equivalent to
`indent=2` in the standard library. Pretty printing is slower and the output
larger. orjson is the fastest compared library at pretty printing and has
much less of a slowdown to pretty print than the standard library does. This
option is compatible with all other options.
```python
>>> import orjson
>>> orjson.dumps({"a": "b", "c": {"d": True}, "e": [1, 2]})
b'{"a":"b","c":{"d":true},"e":[1,2]}'
>>> orjson.dumps(
{"a": "b", "c": {"d": True}, "e": [1, 2]},
option=orjson.OPT_INDENT_2
)
b'{\n "a": "b",\n "c": {\n "d": true\n },\n "e": [\n 1,\n 2\n ]\n}'
```
If displayed, the indentation and linebreaks appear like this:
```json
{
"a": "b",
"c": {
"d": true
},
"e": [
1,
2
]
}
```
This measures serializing the github.json fixture as compact (52KiB) or
pretty (64KiB):
| Library | compact (ms) | pretty (ms) | vs. orjson |
|------------|----------------|---------------|--------------|
| orjson | 0.03 | 0.04 | 1 |
| ujson | 0.18 | 0.19 | 4.6 |
| rapidjson | 0.1 | 0.12 | 2.9 |
| simplejson | 0.25 | 0.89 | 21.4 |
| json | 0.18 | 0.71 | 17 |
This measures serializing the citm_catalog.json fixture, more of a worst
case due to the amount of nesting and newlines, as compact (489KiB) or
pretty (1.1MiB):
| Library | compact (ms) | pretty (ms) | vs. orjson |
|------------|----------------|---------------|--------------|
| orjson | 0.59 | 0.71 | 1 |
| ujson | 2.9 | 3.59 | 5 |
| rapidjson | 1.81 | 2.8 | 3.9 |
| simplejson | 10.43 | 42.13 | 59.1 |
| json | 4.16 | 33.42 | 46.9 |
This can be reproduced using the `pyindent` script.
##### OPT_NAIVE_UTC
Serialize `datetime.datetime` objects without a `tzinfo` as UTC. This
has no effect on `datetime.datetime` objects that have `tzinfo` set.
```python
>>> import orjson, datetime
>>> orjson.dumps(
datetime.datetime(1970, 1, 1, 0, 0, 0),
)
b'"1970-01-01T00:00:00"'
>>> orjson.dumps(
datetime.datetime(1970, 1, 1, 0, 0, 0),
option=orjson.OPT_NAIVE_UTC,
)
b'"1970-01-01T00:00:00+00:00"'
```
##### OPT_NON_STR_KEYS
Serialize `dict` keys of type other than `str`. This allows `dict` keys
to be one of `str`, `int`, `float`, `bool`, `None`, `datetime.datetime`,
`datetime.date`, `datetime.time`, `enum.Enum`, and `uuid.UUID`. For comparison,
the standard library serializes `str`, `int`, `float`, `bool` or `None` by
default. orjson benchmarks as being faster at serializing non-`str` keys
than other libraries. This option is slower for `str` keys than the default.
```python
>>> import orjson, datetime, uuid
>>> orjson.dumps(
{uuid.UUID("7202d115-7ff3-4c81-a7c1-2a1f067b1ece"): [1, 2, 3]},
option=orjson.OPT_NON_STR_KEYS,
)
b'{"7202d115-7ff3-4c81-a7c1-2a1f067b1ece":[1,2,3]}'
>>> orjson.dumps(
{datetime.datetime(1970, 1, 1, 0, 0, 0): [1, 2, 3]},
option=orjson.OPT_NON_STR_KEYS | orjson.OPT_NAIVE_UTC,
)
b'{"1970-01-01T00:00:00+00:00":[1,2,3]}'
```
These types are generally serialized how they would be as
values, e.g., `datetime.datetime` is still an RFC 3339 string and respects
options affecting it. The exception is that `int` serialization does not
respect `OPT_STRICT_INTEGER`.
This option has the risk of creating duplicate keys. This is because non-`str`
objects may serialize to the same `str` as an existing key, e.g.,
`{"1": true, 1: false}`. The last key to be inserted to the `dict` will be
serialized last and a JSON deserializer will presumably take the last
occurrence of a key (in the above, `false`). The first value will be lost.
This option is compatible with `orjson.OPT_SORT_KEYS`. If sorting is used,
note the sort is unstable and will be unpredictable for duplicate keys.
```python
>>> import orjson, datetime
>>> orjson.dumps(
{"other": 1, datetime.date(1970, 1, 5): 2, datetime.date(1970, 1, 3): 3},
option=orjson.OPT_NON_STR_KEYS | orjson.OPT_SORT_KEYS
)
b'{"1970-01-03":3,"1970-01-05":2,"other":1}'
```
This measures serializing 589KiB of JSON comprising a `list` of 100 `dict`
in which each `dict` has both 365 randomly-sorted `int` keys representing epoch
timestamps as well as one `str` key and the value for each key is a
single integer. In "str keys", the keys were converted to `str` before
serialization, and orjson still specifes `option=orjson.OPT_NON_STR_KEYS`
(which is always somewhat slower).
| Library | str keys (ms) | int keys (ms) | int keys sorted (ms) |
|------------|-----------------|-----------------|------------------------|
| orjson | 1.53 | 2.16 | 4.29 |
| ujson | 3.07 | 5.65 | |
| rapidjson | 4.29 | | |
| simplejson | 11.24 | 14.50 | 21.86 |
| json | 7.17 | 8.49 | |
ujson is blank for sorting because it segfaults. json is blank because it
raises `TypeError` on attempting to sort before converting all keys to `str`.
rapidjson is blank because it does not support non-`str` keys. This can
be reproduced using the `pynonstr` script.
##### OPT_OMIT_MICROSECONDS
Do not serialize the `microsecond` field on `datetime.datetime` and
`datetime.time` instances.
```python
>>> import orjson, datetime
>>> orjson.dumps(
datetime.datetime(1970, 1, 1, 0, 0, 0, 1),
)
b'"1970-01-01T00:00:00.000001"'
>>> orjson.dumps(
datetime.datetime(1970, 1, 1, 0, 0, 0, 1),
option=orjson.OPT_OMIT_MICROSECONDS,
)
b'"1970-01-01T00:00:00"'
```
##### OPT_PASSTHROUGH_DATACLASS
Passthrough `dataclasses.dataclass` instances to `default`. This allows
customizing their output but is much slower.
```python
>>> import orjson, dataclasses
>>>
@dataclasses.dataclass
class User:
id: str
name: str
password: str
def default(obj):
if isinstance(obj, User):
return {"id": obj.id, "name": obj.name}
raise TypeError
>>> orjson.dumps(User("3b1", "asd", "zxc"))
b'{"id":"3b1","name":"asd","password":"zxc"}'
>>> orjson.dumps(User("3b1", "asd", "zxc"), option=orjson.OPT_PASSTHROUGH_DATACLASS)
TypeError: Type is not JSON serializable: User
>>> orjson.dumps(
User("3b1", "asd", "zxc"),
option=orjson.OPT_PASSTHROUGH_DATACLASS,
default=default,
)
b'{"id":"3b1","name":"asd"}'
```
##### OPT_PASSTHROUGH_DATETIME
Passthrough `datetime.datetime`, `datetime.date`, and `datetime.time` instances
to `default`. This allows serializing datetimes to a custom format, e.g.,
HTTP dates:
```python
>>> import orjson, datetime
>>>
def default(obj):
if isinstance(obj, datetime.datetime):
return obj.strftime("%a, %d %b %Y %H:%M:%S GMT")
raise TypeError
>>> orjson.dumps({"created_at": datetime.datetime(1970, 1, 1)})
b'{"created_at":"1970-01-01T00:00:00"}'
>>> orjson.dumps({"created_at": datetime.datetime(1970, 1, 1)}, option=orjson.OPT_PASSTHROUGH_DATETIME)
TypeError: Type is not JSON serializable: datetime.datetime
>>> orjson.dumps(
{"created_at": datetime.datetime(1970, 1, 1)},
option=orjson.OPT_PASSTHROUGH_DATETIME,
default=default,
)
b'{"created_at":"Thu, 01 Jan 1970 00:00:00 GMT"}'
```
This does not affect datetimes in `dict` keys if using OPT_NON_STR_KEYS.
##### OPT_PASSTHROUGH_SUBCLASS
Passthrough subclasses of builtin types to `default`.
```python
>>> import orjson
>>>
class Secret(str):
pass
def default(obj):
if isinstance(obj, Secret):
return "******"
raise TypeError
>>> orjson.dumps(Secret("zxc"))
b'"zxc"'
>>> orjson.dumps(Secret("zxc"), option=orjson.OPT_PASSTHROUGH_SUBCLASS)
TypeError: Type is not JSON serializable: Secret
>>> orjson.dumps(Secret("zxc"), option=orjson.OPT_PASSTHROUGH_SUBCLASS, default=default)
b'"******"'
```
This does not affect serializing subclasses as `dict` keys if using
OPT_NON_STR_KEYS.
##### OPT_SERIALIZE_DATACLASS
This is deprecated and has no effect in version 3. In version 2 this was
required to serialize `dataclasses.dataclass` instances. For more, see
[dataclass](https://github.com/ijl/orjson?tab=readme-ov-file#dataclass).
##### OPT_SERIALIZE_NUMPY
Serialize `numpy.ndarray` instances. For more, see
[numpy](https://github.com/ijl/orjson?tab=readme-ov-file#numpy).
##### OPT_SERIALIZE_UUID
This is deprecated and has no effect in version 3. In version 2 this was
required to serialize `uuid.UUID` instances. For more, see
[UUID](https://github.com/ijl/orjson?tab=readme-ov-file#UUID).
##### OPT_SORT_KEYS
Serialize `dict` keys in sorted order. The default is to serialize in an
unspecified order. This is equivalent to `sort_keys=True` in the standard
library.
This can be used to ensure the order is deterministic for hashing or tests.
It has a substantial performance penalty and is not recommended in general.
```python
>>> import orjson
>>> orjson.dumps({"b": 1, "c": 2, "a": 3})
b'{"b":1,"c":2,"a":3}'
>>> orjson.dumps({"b": 1, "c": 2, "a": 3}, option=orjson.OPT_SORT_KEYS)
b'{"a":3,"b":1,"c":2}'
```
This measures serializing the twitter.json fixture unsorted and sorted:
| Library | unsorted (ms) | sorted (ms) | vs. orjson |
|------------|-----------------|---------------|--------------|
| orjson | 0.32 | 0.54 | 1 |
| ujson | 1.6 | 2.07 | 3.8 |
| rapidjson | 1.12 | 1.65 | 3.1 |
| simplejson | 2.25 | 3.13 | 5.8 |
| json | 1.78 | 2.32 | 4.3 |
The benchmark can be reproduced using the `pysort` script.
The sorting is not collation/locale-aware:
```python
>>> import orjson
>>> orjson.dumps({"a": 1, "ä": 2, "A": 3}, option=orjson.OPT_SORT_KEYS)
b'{"A":3,"a":1,"\xc3\xa4":2}'
```
This is the same sorting behavior as the standard library, rapidjson,
simplejson, and ujson.
`dataclass` also serialize as maps but this has no effect on them.
##### OPT_STRICT_INTEGER
Enforce 53-bit limit on integers. The limit is otherwise 64 bits, the same as
the Python standard library. For more, see [int](https://github.com/ijl/orjson?tab=readme-ov-file#int).
##### OPT_UTC_Z
Serialize a UTC timezone on `datetime.datetime` instances as `Z` instead
of `+00:00`.
```python
>>> import orjson, datetime, zoneinfo
>>> orjson.dumps(
datetime.datetime(1970, 1, 1, 0, 0, 0, tzinfo=zoneinfo.ZoneInfo("UTC")),
)
b'"1970-01-01T00:00:00+00:00"'
>>> orjson.dumps(
datetime.datetime(1970, 1, 1, 0, 0, 0, tzinfo=zoneinfo.ZoneInfo("UTC")),
option=orjson.OPT_UTC_Z
)
b'"1970-01-01T00:00:00Z"'
```
#### Fragment
`orjson.Fragment` includes already-serialized JSON in a document. This is an
efficient way to include JSON blobs from a cache, JSONB field, or separately
serialized object without first deserializing to Python objects via `loads()`.
```python
>>> import orjson
>>> orjson.dumps({"key": "zxc", "data": orjson.Fragment(b'{"a": "b", "c": 1}')})
b'{"key":"zxc","data":{"a": "b", "c": 1}}'
```
It does no reformatting: `orjson.OPT_INDENT_2` will not affect a
compact blob nor will a pretty-printed JSON blob be rewritten as compact.
The input must be `bytes` or `str` and given as a positional argument.
This raises `orjson.JSONEncodeError` if a `str` is given and the input is
not valid UTF-8. It otherwise does no validation and it is possible to
write invalid JSON. This does not escape characters. The implementation is
tested to not crash if given invalid strings or invalid JSON.
This is similar to `RawJSON` in rapidjson.
### Deserialize
```python
def loads(__obj: Union[bytes, bytearray, memoryview, str]) -> Any: ...
```
`loads()` deserializes JSON to Python objects. It deserializes to `dict`,
`list`, `int`, `float`, `str`, `bool`, and `None` objects.
`bytes`, `bytearray`, `memoryview`, and `str` input are accepted. If the input
exists as a `memoryview`, `bytearray`, or `bytes` object, it is recommended to
pass these directly rather than creating an unnecessary `str` object. That is,
`orjson.loads(b"{}")` instead of `orjson.loads(b"{}".decode("utf-8"))`. This
has lower memory usage and lower latency.
The input must be valid UTF-8.
orjson maintains a cache of map keys for the duration of the process. This
causes a net reduction in memory usage by avoiding duplicate strings. The
keys must be at most 64 bytes to be cached and 2048 entries are stored.
The global interpreter lock (GIL) is held for the duration of the call.
It raises `JSONDecodeError` if given an invalid type or invalid
JSON. This includes if the input contains `NaN`, `Infinity`, or `-Infinity`,
which the standard library allows, but is not valid JSON.
It raises `JSONDecodeError` if a combination of array or object recurses
1024 levels deep.
`JSONDecodeError` is a subclass of `json.JSONDecodeError` and `ValueError`.
This is for compatibility with the standard library.
## Types
### dataclass
orjson serializes instances of `dataclasses.dataclass` natively. It serializes
instances 40-50x as fast as other libraries and avoids a severe slowdown seen
in other libraries compared to serializing `dict`.
It is supported to pass all variants of dataclasses, including dataclasses
using `__slots__`, frozen dataclasses, those with optional or default
attributes, and subclasses. There is a performance benefit to not
using `__slots__`.
| Library | dict (ms) | dataclass (ms) | vs. orjson |
|------------|-------------|------------------|--------------|
| orjson | 1.40 | 1.60 | 1 |
| ujson | | | |
| rapidjson | 3.64 | 68.48 | 42 |
| simplejson | 14.21 | 92.18 | 57 |
| json | 13.28 | 94.90 | 59 |
This measures serializing 555KiB of JSON, orjson natively and other libraries
using `default` to serialize the output of `dataclasses.asdict()`. This can be
reproduced using the `pydataclass` script.
Dataclasses are serialized as maps, with every attribute serialized and in
the order given on class definition:
```python
>>> import dataclasses, orjson, typing
@dataclasses.dataclass
class Member:
id: int
active: bool = dataclasses.field(default=False)
@dataclasses.dataclass
class Object:
id: int
name: str
members: typing.List[Member]
>>> orjson.dumps(Object(1, "a", [Member(1, True), Member(2)]))
b'{"id":1,"name":"a","members":[{"id":1,"active":true},{"id":2,"active":false}]}'
```
### datetime
orjson serializes `datetime.datetime` objects to
[RFC 3339](https://tools.ietf.org/html/rfc3339) format,
e.g., "1970-01-01T00:00:00+00:00". This is a subset of ISO 8601 and is
compatible with `isoformat()` in the standard library.
```python
>>> import orjson, datetime, zoneinfo
>>> orjson.dumps(
datetime.datetime(2018, 12, 1, 2, 3, 4, 9, tzinfo=zoneinfo.ZoneInfo("Australia/Adelaide"))
)
b'"2018-12-01T02:03:04.000009+10:30"'
>>> orjson.dumps(
datetime.datetime(2100, 9, 1, 21, 55, 2).replace(tzinfo=zoneinfo.ZoneInfo("UTC"))
)
b'"2100-09-01T21:55:02+00:00"'
>>> orjson.dumps(
datetime.datetime(2100, 9, 1, 21, 55, 2)
)
b'"2100-09-01T21:55:02"'
```
`datetime.datetime` supports instances with a `tzinfo` that is `None`,
`datetime.timezone.utc`, a timezone instance from the python3.9+ `zoneinfo`
module, or a timezone instance from the third-party `pendulum`, `pytz`, or
`dateutil`/`arrow` libraries.
It is fastest to use the standard library's `zoneinfo.ZoneInfo` for timezones.
`datetime.time` objects must not have a `tzinfo`.
```python
>>> import orjson, datetime
>>> orjson.dumps(datetime.time(12, 0, 15, 290))
b'"12:00:15.000290"'
```
`datetime.date` objects will always serialize.
```python
>>> import orjson, datetime
>>> orjson.dumps(datetime.date(1900, 1, 2))
b'"1900-01-02"'
```
Errors with `tzinfo` result in `JSONEncodeError` being raised.
To disable serialization of `datetime` objects specify the option
`orjson.OPT_PASSTHROUGH_DATETIME`.
To use "Z" suffix instead of "+00:00" to indicate UTC ("Zulu") time, use the option
`orjson.OPT_UTC_Z`.
To assume datetimes without timezone are UTC, use the option `orjson.OPT_NAIVE_UTC`.
### enum
orjson serializes enums natively. Options apply to their values.
```python
>>> import enum, datetime, orjson
>>>
class DatetimeEnum(enum.Enum):
EPOCH = datetime.datetime(1970, 1, 1, 0, 0, 0)
>>> orjson.dumps(DatetimeEnum.EPOCH)
b'"1970-01-01T00:00:00"'
>>> orjson.dumps(DatetimeEnum.EPOCH, option=orjson.OPT_NAIVE_UTC)
b'"1970-01-01T00:00:00+00:00"'
```
Enums with members that are not supported types can be serialized using
`default`:
```python
>>> import enum, orjson
>>>
class Custom:
def __init__(self, val):
self.val = val
def default(obj):
if isinstance(obj, Custom):
return obj.val
raise TypeError
class CustomEnum(enum.Enum):
ONE = Custom(1)
>>> orjson.dumps(CustomEnum.ONE, default=default)
b'1'
```
### float
orjson serializes and deserializes double precision floats with no loss of
precision and consistent rounding.
`orjson.dumps()` serializes Nan, Infinity, and -Infinity, which are not
compliant JSON, as `null`:
```python
>>> import orjson, ujson, rapidjson, json
>>> orjson.dumps([float("NaN"), float("Infinity"), float("-Infinity")])
b'[null,null,null]'
>>> ujson.dumps([float("NaN"), float("Infinity"), float("-Infinity")])
OverflowError: Invalid Inf value when encoding double
>>> rapidjson.dumps([float("NaN"), float("Infinity"), float("-Infinity")])
'[NaN,Infinity,-Infinity]'
>>> json.dumps([float("NaN"), float("Infinity"), float("-Infinity")])
'[NaN, Infinity, -Infinity]'
```
### int
orjson serializes and deserializes 64-bit integers by default. The range
supported is a signed 64-bit integer's minimum (-9223372036854775807) to
an unsigned 64-bit integer's maximum (18446744073709551615). This
is widely compatible, but there are implementations
that only support 53-bits for integers, e.g.,
web browsers. For those implementations, `dumps()` can be configured to
raise a `JSONEncodeError` on values exceeding the 53-bit range.
```python
>>> import orjson
>>> orjson.dumps(9007199254740992)
b'9007199254740992'
>>> orjson.dumps(9007199254740992, option=orjson.OPT_STRICT_INTEGER)
JSONEncodeError: Integer exceeds 53-bit range
>>> orjson.dumps(-9007199254740992, option=orjson.OPT_STRICT_INTEGER)
JSONEncodeError: Integer exceeds 53-bit range
```
### numpy
orjson natively serializes `numpy.ndarray` and individual
`numpy.float64`, `numpy.float32`, `numpy.float16` (`numpy.half`),
`numpy.int64`, `numpy.int32`, `numpy.int16`, `numpy.int8`,
`numpy.uint64`, `numpy.uint32`, `numpy.uint16`, `numpy.uint8`,
`numpy.uintp`, `numpy.intp`, `numpy.datetime64`, and `numpy.bool`
instances.
orjson is compatible with both numpy v1 and v2.
orjson is faster than all compared libraries at serializing
numpy instances. Serializing numpy data requires specifying
`option=orjson.OPT_SERIALIZE_NUMPY`.
```python
>>> import orjson, numpy
>>> orjson.dumps(
numpy.array([[1, 2, 3], [4, 5, 6]]),
option=orjson.OPT_SERIALIZE_NUMPY,
)
b'[[1,2,3],[4,5,6]]'
```
The array must be a contiguous C array (`C_CONTIGUOUS`) and one of the
supported datatypes.
Note a difference between serializing `numpy.float32` using `ndarray.tolist()`
or `orjson.dumps(..., option=orjson.OPT_SERIALIZE_NUMPY)`: `tolist()` converts
to a `double` before serializing and orjson's native path does not. This
can result in different rounding.
`numpy.datetime64` instances are serialized as RFC 3339 strings and
datetime options affect them.
```python
>>> import orjson, numpy
>>> orjson.dumps(
numpy.datetime64("2021-01-01T00:00:00.172"),
option=orjson.OPT_SERIALIZE_NUMPY,
)
b'"2021-01-01T00:00:00.172000"'
>>> orjson.dumps(
numpy.datetime64("2021-01-01T00:00:00.172"),
option=(
orjson.OPT_SERIALIZE_NUMPY |
orjson.OPT_NAIVE_UTC |
orjson.OPT_OMIT_MICROSECONDS
),
)
b'"2021-01-01T00:00:00+00:00"'
```
If an array is not a contiguous C array, contains an unsupported datatype,
or contains a `numpy.datetime64` using an unsupported representation
(e.g., picoseconds), orjson falls through to `default`. In `default`,
`obj.tolist()` can be specified.
If an array is not in the native endianness, e.g., an array of big-endian values
on a little-endian system, `orjson.JSONEncodeError` is raised.
If an array is malformed, `orjson.JSONEncodeError` is raised.
This measures serializing 92MiB of JSON from an `numpy.ndarray` with
dimensions of `(50000, 100)` and `numpy.float64` values:
| Library | Latency (ms) | RSS diff (MiB) | vs. orjson |
|------------|----------------|------------------|--------------|
| orjson | 194 | 99 | 1.0 |
| ujson | | | |
| rapidjson | 3,048 | 309 | 15.7 |
| simplejson | 3,023 | 297 | 15.6 |
| json | 3,133 | 297 | 16.1 |
This measures serializing 100MiB of JSON from an `numpy.ndarray` with
dimensions of `(100000, 100)` and `numpy.int32` values:
| Library | Latency (ms) | RSS diff (MiB) | vs. orjson |
|------------|----------------|------------------|--------------|
| orjson | 178 | 115 | 1.0 |
| ujson | | | |
| rapidjson | 1,512 | 551 | 8.5 |
| simplejson | 1,606 | 504 | 9.0 |
| json | 1,506 | 503 | 8.4 |
This measures serializing 105MiB of JSON from an `numpy.ndarray` with
dimensions of `(100000, 200)` and `numpy.bool` values:
| Library | Latency (ms) | RSS diff (MiB) | vs. orjson |
|------------|----------------|------------------|--------------|
| orjson | 157 | 120 | 1.0 |
| ujson | | | |
| rapidjson | 710 | 327 | 4.5 |
| simplejson | 931 | 398 | 5.9 |
| json | 996 | 400 | 6.3 |
In these benchmarks, orjson serializes natively, ujson is blank because it
does not support a `default` parameter, and the other libraries serialize
`ndarray.tolist()` via `default`. The RSS column measures peak memory
usage during serialization. This can be reproduced using the `pynumpy` script.
orjson does not have an installation or compilation dependency on numpy. The
implementation is independent, reading `numpy.ndarray` using
`PyArrayInterface`.
### str
orjson is strict about UTF-8 conformance. This is stricter than the standard
library's json module, which will serialize and deserialize UTF-16 surrogates,
e.g., "\ud800", that are invalid UTF-8.
If `orjson.dumps()` is given a `str` that does not contain valid UTF-8,
`orjson.JSONEncodeError` is raised. If `loads()` receives invalid UTF-8,
`orjson.JSONDecodeError` is raised.
orjson and rapidjson are the only compared JSON libraries to consistently
error on bad input.
```python
>>> import orjson, ujson, rapidjson, json
>>> orjson.dumps('\ud800')
JSONEncodeError: str is not valid UTF-8: surrogates not allowed
>>> ujson.dumps('\ud800')
UnicodeEncodeError: 'utf-8' codec ...
>>> rapidjson.dumps('\ud800')
UnicodeEncodeError: 'utf-8' codec ...
>>> json.dumps('\ud800')
'"\\ud800"'
>>> orjson.loads('"\\ud800"')
JSONDecodeError: unexpected end of hex escape at line 1 column 8: line 1 column 1 (char 0)
>>> ujson.loads('"\\ud800"')
''
>>> rapidjson.loads('"\\ud800"')
ValueError: Parse error at offset 1: The surrogate pair in string is invalid.
>>> json.loads('"\\ud800"')
'\ud800'
```
To make a best effort at deserializing bad input, first decode `bytes` using
the `replace` or `lossy` argument for `errors`:
```python
>>> import orjson
>>> orjson.loads(b'"\xed\xa0\x80"')
JSONDecodeError: str is not valid UTF-8: surrogates not allowed
>>> orjson.loads(b'"\xed\xa0\x80"'.decode("utf-8", "replace"))
'���'
```
### uuid
orjson serializes `uuid.UUID` instances to
[RFC 4122](https://tools.ietf.org/html/rfc4122) format, e.g.,
"f81d4fae-7dec-11d0-a765-00a0c91e6bf6".
``` python
>>> import orjson, uuid
>>> orjson.dumps(uuid.UUID('f81d4fae-7dec-11d0-a765-00a0c91e6bf6'))
b'"f81d4fae-7dec-11d0-a765-00a0c91e6bf6"'
>>> orjson.dumps(uuid.uuid5(uuid.NAMESPACE_DNS, "python.org"))
b'"886313e1-3b8a-5372-9b90-0c9aee199e5d"'
```
## Testing
The library has comprehensive tests. There are tests against fixtures in the
[JSONTestSuite](https://github.com/nst/JSONTestSuite) and
[nativejson-benchmark](https://github.com/miloyip/nativejson-benchmark)
repositories. It is tested to not crash against the
[Big List of Naughty Strings](https://github.com/minimaxir/big-list-of-naughty-strings).
It is tested to not leak memory. It is tested to not crash
against and not accept invalid UTF-8. There are integration tests
exercising the library's use in web servers (gunicorn using multiprocess/forked
workers) and when
multithreaded. It also uses some tests from the ultrajson library.
orjson is the most correct of the compared libraries. This graph shows how each
library handles a combined 342 JSON fixtures from the
[JSONTestSuite](https://github.com/nst/JSONTestSuite) and
[nativejson-benchmark](https://github.com/miloyip/nativejson-benchmark) tests:
| Library | Invalid JSON documents not rejected | Valid JSON documents not deserialized |
|------------|---------------------------------------|-----------------------------------------|
| orjson | 0 | 0 |
| ujson | 31 | 0 |
| rapidjson | 6 | 0 |
| simplejson | 10 | 0 |
| json | 17 | 0 |
This shows that all libraries deserialize valid JSON but only orjson
correctly rejects the given invalid JSON fixtures. Errors are largely due to
accepting invalid strings and numbers.
The graph above can be reproduced using the `pycorrectness` script.
## Performance
Serialization and deserialization performance of orjson is better than
ultrajson, rapidjson, simplejson, or json. The benchmarks are done on
fixtures of real data:
* twitter.json, 631.5KiB, results of a search on Twitter for "一", containing
CJK strings, dictionaries of strings and arrays of dictionaries, indented.
* github.json, 55.8KiB, a GitHub activity feed, containing dictionaries of
strings and arrays of dictionaries, not indented.
* citm_catalog.json, 1.7MiB, concert data, containing nested dictionaries of
strings and arrays of integers, indented.
* canada.json, 2.2MiB, coordinates of the Canadian border in GeoJSON
format, containing floats and arrays, indented.
### Latency
#### twitter.json serialization
| Library | Median latency (milliseconds) | Operations per second | Relative (latency) |
|------------|---------------------------------|-------------------------|----------------------|
| orjson | 0.1 | 8377 | 1 |
| ujson | 0.9 | 1088 | 7.3 |
| rapidjson | 0.8 | 1228 | 6.8 |
| simplejson | 1.9 | 531 | 15.6 |
| json | 1.4 | 744 | 11.3 |
#### twitter.json deserialization
| Library | Median latency (milliseconds) | Operations per second | Relative (latency) |
|------------|---------------------------------|-------------------------|----------------------|
| orjson | 0.6 | 1811 | 1 |
| ujson | 1.2 | 814 | 2.1 |
| rapidjson | 2.1 | 476 | 3.8 |
| simplejson | 1.6 | 626 | 3 |
| json | 1.8 | 557 | 3.3 |
#### github.json serialization
| Library | Median latency (milliseconds) | Operations per second | Relative (latency) |
|------------|---------------------------------|-------------------------|----------------------|
| orjson | 0.01 | 104424 | 1 |
| ujson | 0.09 | 10594 | 9.8 |
| rapidjson | 0.07 | 13667 | 7.6 |
| simplejson | 0.2 | 5051 | 20.6 |
| json | 0.14 | 7133 | 14.6 |
#### github.json deserialization
| Library | Median latency (milliseconds) | Operations per second | Relative (latency) |
|------------|---------------------------------|-------------------------|----------------------|
| orjson | 0.05 | 20069 | 1 |
| ujson | 0.11 | 8913 | 2.3 |
| rapidjson | 0.13 | 8077 | 2.6 |
| simplejson | 0.11 | 9342 | 2.1 |
| json | 0.11 | 9291 | 2.2 |
#### citm_catalog.json serialization
| Library | Median latency (milliseconds) | Operations per second | Relative (latency) |
|------------|---------------------------------|-------------------------|----------------------|
| orjson | 0.3 | 3757 | 1 |
| ujson | 1.7 | 598 | 6.3 |
| rapidjson | 1.3 | 768 | 4.9 |
| simplejson | 8.3 | 120 | 31.1 |
| json | 3 | 331 | 11.3 |
#### citm_catalog.json deserialization
| Library | Median latency (milliseconds) | Operations per second | Relative (latency) |
|------------|---------------------------------|-------------------------|----------------------|
| orjson | 1.4 | 730 | 1 |
| ujson | 2.6 | 384 | 1.9 |
| rapidjson | 4 | 246 | 3 |
| simplejson | 3.7 | 271 | 2.7 |
| json | 3.7 | 267 | 2.7 |
#### canada.json serialization
| Library | Median latency (milliseconds) | Operations per second | Relative (latency) |
|------------|---------------------------------|-------------------------|----------------------|
| orjson | 2.4 | 410 | 1 |
| ujson | 9.6 | 104 | 3.9 |
| rapidjson | 28.7 | 34 | 11.8 |
| simplejson | 49.3 | 20 | 20.3 |
| json | 30.6 | 32 | 12.6 |
#### canada.json deserialization
| Library | Median latency (milliseconds) | Operations per second | Relative (latency) |
|------------|---------------------------------|-------------------------|----------------------|
| orjson | 3 | 336 | 1 |
| ujson | 7.1 | 141 | 2.4 |
| rapidjson | 20.1 | 49 | 6.7 |
| simplejson | 16.8 | 59 | 5.6 |
| json | 18.2 | 55 | 6.1 |
### Memory
orjson as of 3.7.0 has higher baseline memory usage than other libraries
due to a persistent buffer used for parsing. Incremental memory usage when
deserializing is similar to the standard library and other third-party
libraries.
This measures, in the first column, RSS after importing a library and reading
the fixture, and in the second column, increases in RSS after repeatedly
calling `loads()` on the fixture.
#### twitter.json
| Library | import, read() RSS (MiB) | loads() increase in RSS (MiB) |
|------------|----------------------------|---------------------------------|
| orjson | 15.7 | 3.4 |
| ujson | 16.4 | 3.4 |
| rapidjson | 16.6 | 4.4 |
| simplejson | 14.5 | 1.8 |
| json | 13.9 | 1.8 |
#### github.json
| Library | import, read() RSS (MiB) | loads() increase in RSS (MiB) |
|------------|----------------------------|---------------------------------|
| orjson | 15.2 | 0.4 |
| ujson | 15.4 | 0.4 |
| rapidjson | 15.7 | 0.5 |
| simplejson | 13.7 | 0.2 |
| json | 13.3 | 0.1 |
#### citm_catalog.json
| Library | import, read() RSS (MiB) | loads() increase in RSS (MiB) |
|------------|----------------------------|---------------------------------|
| orjson | 16.8 | 10.1 |
| ujson | 17.3 | 10.2 |
| rapidjson | 17.6 | 28.7 |
| simplejson | 15.8 | 30.1 |
| json | 14.8 | 20.5 |
#### canada.json
| Library | import, read() RSS (MiB) | loads() increase in RSS (MiB) |
|------------|----------------------------|---------------------------------|
| orjson | 17.2 | 22.1 |
| ujson | 17.4 | 18.3 |
| rapidjson | 18 | 23.5 |
| simplejson | 15.7 | 21.4 |
| json | 15.4 | 20.4 |
### Reproducing
The above was measured using Python 3.11.9 on Linux (amd64) with
orjson 3.10.6, ujson 5.10.0, python-rapidson 1.18, and simplejson 3.19.2.
The latency results can be reproduced using the `pybench` and `graph`
scripts. The memory results can be reproduced using the `pymem` script.
## Questions
### Why can't I install it from PyPI?
Probably `pip` needs to be upgraded to version 20.3 or later to support
the latest manylinux_x_y or universal2 wheel formats.
### "Cargo, the Rust package manager, is not installed or is not on PATH."
This happens when there are no binary wheels (like manylinux) for your
platform on PyPI. You can install [Rust](https://www.rust-lang.org/) through
`rustup` or a package manager and then it will compile.
### Will it deserialize to dataclasses, UUIDs, decimals, etc or support object_hook?
No. This requires a schema specifying what types are expected and how to
handle errors etc. This is addressed by data validation libraries a
level above this.
### Will it serialize to `str`?
No. `bytes` is the correct type for a serialized blob.
### Will it support NDJSON or JSONL?
No. [orjsonl](https://github.com/umarbutler/orjsonl) may be appropriate.
### Will it support JSON5 or RJSON?
No, it supports RFC 8259.
## Packaging
To package orjson requires at least [Rust](https://www.rust-lang.org/) 1.72
and the [maturin](https://github.com/PyO3/maturin) build tool. The recommended
build command is:
```sh
maturin build --release --strip
```
It benefits from also having a C build environment to compile a faster
deserialization backend. See this project's `manylinux_2_28` builds for an
example using clang and LTO.
The project's own CI tests against `nightly-2024-09-25` and stable 1.72. It
is prudent to pin the nightly version because that channel can introduce
breaking changes.
orjson is tested for amd64 on Linux and cross-compiles for aarch64, arm7,
ppc64le, and s390x. It is tested for either aarch64 or amd64 on macOS and
cross-compiles for the other, depending on version. For Windows it is
tested on amd64 and i686.
There are no runtime dependencies other than libc.
The source distribution on PyPI contains all dependencies' source and can be
built without network access. The file can be downloaded from
`https://files.pythonhosted.org/packages/source/o/orjson/orjson-${version}.tar.gz`.
orjson's tests are included in the source distribution on PyPI. The
requirements to run the tests are specified in `test/requirements.txt`. The
tests should be run as part of the build. It can be run with
`pytest -q test`.
## License
orjson was written by ijl <<ijl@mailbox.org>>, copyright 2018 - 2024, available
to you under either the Apache 2 license or MIT license at your choice.
Raw data
{
"_id": null,
"home_page": "https://github.com/ijl/orjson",
"name": "orjson",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "fast, json, dataclass, dataclasses, datetime, rfc, 8259, 3339",
"author": "ijl <ijl@mailbox.org>",
"author_email": "ijl <ijl@mailbox.org>",
"download_url": null,
"platform": null,
"description": "# orjson\r\n\r\norjson is a fast, correct JSON library for Python. It\r\n[benchmarks](https://github.com/ijl/orjson?tab=readme-ov-file#performance) as the fastest Python\r\nlibrary for JSON and is more correct than the standard json library or other\r\nthird-party libraries. It serializes\r\n[dataclass](https://github.com/ijl/orjson?tab=readme-ov-file#dataclass),\r\n[datetime](https://github.com/ijl/orjson?tab=readme-ov-file#datetime),\r\n[numpy](https://github.com/ijl/orjson?tab=readme-ov-file#numpy), and\r\n[UUID](https://github.com/ijl/orjson?tab=readme-ov-file#uuid) instances natively.\r\n\r\nIts features and drawbacks compared to other Python JSON libraries:\r\n\r\n* serializes `dataclass` instances 40-50x as fast as other libraries\r\n* serializes `datetime`, `date`, and `time` instances to RFC 3339 format,\r\ne.g., \"1970-01-01T00:00:00+00:00\"\r\n* serializes `numpy.ndarray` instances 4-12x as fast with 0.3x the memory\r\nusage of other libraries\r\n* pretty prints 10x to 20x as fast as the standard library\r\n* serializes to `bytes` rather than `str`, i.e., is not a drop-in replacement\r\n* serializes `str` without escaping unicode to ASCII, e.g., \"\u597d\" rather than\r\n\"\\\\\\u597d\"\r\n* serializes `float` 10x as fast and deserializes twice as fast as other\r\nlibraries\r\n* serializes subclasses of `str`, `int`, `list`, and `dict` natively,\r\nrequiring `default` to specify how to serialize others\r\n* serializes arbitrary types using a `default` hook\r\n* has strict UTF-8 conformance, more correct than the standard library\r\n* has strict JSON conformance in not supporting Nan/Infinity/-Infinity\r\n* has an option for strict JSON conformance on 53-bit integers with default\r\nsupport for 64-bit\r\n* does not provide `load()` or `dump()` functions for reading from/writing to\r\nfile-like objects\r\n\r\norjson supports CPython 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, and 3.14.\r\n\r\nIt distributes amd64/x86_64, aarch64/armv8, arm7, POWER/ppc64le, and s390x\r\nwheels for Linux, amd64 and aarch64 wheels for macOS, and amd64\r\nand i686/x86 wheels for Windows.\r\n\r\norjson does not and will not support PyPy, embedded Python builds for\r\nAndroid/iOS, or PEP 554 subinterpreters.\r\n\r\nReleases follow semantic versioning and serializing a new object type\r\nwithout an opt-in flag is considered a breaking change.\r\n\r\norjson is licensed under both the Apache 2.0 and MIT licenses. The\r\nrepository and issue tracker is\r\n[github.com/ijl/orjson](https://github.com/ijl/orjson), and patches may be\r\nsubmitted there. There is a\r\n[CHANGELOG](https://github.com/ijl/orjson/blob/master/CHANGELOG.md)\r\navailable in the repository.\r\n\r\n1. [Usage](https://github.com/ijl/orjson?tab=readme-ov-file#usage)\r\n 1. [Install](https://github.com/ijl/orjson?tab=readme-ov-file#install)\r\n 2. [Quickstart](https://github.com/ijl/orjson?tab=readme-ov-file#quickstart)\r\n 3. [Migrating](https://github.com/ijl/orjson?tab=readme-ov-file#migrating)\r\n 4. [Serialize](https://github.com/ijl/orjson?tab=readme-ov-file#serialize)\r\n 1. [default](https://github.com/ijl/orjson?tab=readme-ov-file#default)\r\n 2. [option](https://github.com/ijl/orjson?tab=readme-ov-file#option)\r\n 3. [Fragment](https://github.com/ijl/orjson?tab=readme-ov-file#fragment)\r\n 5. [Deserialize](https://github.com/ijl/orjson?tab=readme-ov-file#deserialize)\r\n2. [Types](https://github.com/ijl/orjson?tab=readme-ov-file#types)\r\n 1. [dataclass](https://github.com/ijl/orjson?tab=readme-ov-file#dataclass)\r\n 2. [datetime](https://github.com/ijl/orjson?tab=readme-ov-file#datetime)\r\n 3. [enum](https://github.com/ijl/orjson?tab=readme-ov-file#enum)\r\n 4. [float](https://github.com/ijl/orjson?tab=readme-ov-file#float)\r\n 5. [int](https://github.com/ijl/orjson?tab=readme-ov-file#int)\r\n 6. [numpy](https://github.com/ijl/orjson?tab=readme-ov-file#numpy)\r\n 7. [str](https://github.com/ijl/orjson?tab=readme-ov-file#str)\r\n 8. [uuid](https://github.com/ijl/orjson?tab=readme-ov-file#uuid)\r\n3. [Testing](https://github.com/ijl/orjson?tab=readme-ov-file#testing)\r\n4. [Performance](https://github.com/ijl/orjson?tab=readme-ov-file#performance)\r\n 1. [Latency](https://github.com/ijl/orjson?tab=readme-ov-file#latency)\r\n 2. [Memory](https://github.com/ijl/orjson?tab=readme-ov-file#memory)\r\n 3. [Reproducing](https://github.com/ijl/orjson?tab=readme-ov-file#reproducing)\r\n5. [Questions](https://github.com/ijl/orjson?tab=readme-ov-file#questions)\r\n6. [Packaging](https://github.com/ijl/orjson?tab=readme-ov-file#packaging)\r\n7. [License](https://github.com/ijl/orjson?tab=readme-ov-file#license)\r\n\r\n## Usage\r\n\r\n### Install\r\n\r\nTo install a wheel from PyPI, install the `orjson` package.\r\n\r\nIn `requirements.in` or `requirements.txt` format, specify:\r\n\r\n```txt\r\norjson>=3.10,<4\r\n```\r\n\r\nIn Poetry, specify:\r\n\r\n```toml\r\norjson = \"^3\"\r\n```\r\n\r\nTo build a wheel, see [packaging](https://github.com/ijl/orjson?tab=readme-ov-file#packaging).\r\n\r\n### Quickstart\r\n\r\nThis is an example of serializing, with options specified, and deserializing:\r\n\r\n```python\r\n>>> import orjson, datetime, numpy\r\n>>> data = {\r\n \"type\": \"job\",\r\n \"created_at\": datetime.datetime(1970, 1, 1),\r\n \"status\": \"\ud83c\udd97\",\r\n \"payload\": numpy.array([[1, 2], [3, 4]]),\r\n}\r\n>>> orjson.dumps(data, option=orjson.OPT_NAIVE_UTC | orjson.OPT_SERIALIZE_NUMPY)\r\nb'{\"type\":\"job\",\"created_at\":\"1970-01-01T00:00:00+00:00\",\"status\":\"\\xf0\\x9f\\x86\\x97\",\"payload\":[[1,2],[3,4]]}'\r\n>>> orjson.loads(_)\r\n{'type': 'job', 'created_at': '1970-01-01T00:00:00+00:00', 'status': '\ud83c\udd97', 'payload': [[1, 2], [3, 4]]}\r\n```\r\n\r\n### Migrating\r\n\r\norjson version 3 serializes more types than version 2. Subclasses of `str`,\r\n`int`, `dict`, and `list` are now serialized. This is faster and more similar\r\nto the standard library. It can be disabled with\r\n`orjson.OPT_PASSTHROUGH_SUBCLASS`.`dataclasses.dataclass` instances\r\nare now serialized by default and cannot be customized in a\r\n`default` function unless `option=orjson.OPT_PASSTHROUGH_DATACLASS` is\r\nspecified. `uuid.UUID` instances are serialized by default.\r\nFor any type that is now serialized,\r\nimplementations in a `default` function and options enabling them can be\r\nremoved but do not need to be. There was no change in deserialization.\r\n\r\nTo migrate from the standard library, the largest difference is that\r\n`orjson.dumps` returns `bytes` and `json.dumps` returns a `str`. Users with\r\n`dict` objects using non-`str` keys should specify\r\n`option=orjson.OPT_NON_STR_KEYS`. `sort_keys` is replaced by\r\n`option=orjson.OPT_SORT_KEYS`. `indent` is replaced by\r\n`option=orjson.OPT_INDENT_2` and other levels of indentation are not\r\nsupported.\r\n\r\n### Serialize\r\n\r\n```python\r\ndef dumps(\r\n __obj: Any,\r\n default: Optional[Callable[[Any], Any]] = ...,\r\n option: Optional[int] = ...,\r\n) -> bytes: ...\r\n```\r\n\r\n`dumps()` serializes Python objects to JSON.\r\n\r\nIt natively serializes\r\n`str`, `dict`, `list`, `tuple`, `int`, `float`, `bool`, `None`,\r\n`dataclasses.dataclass`, `typing.TypedDict`, `datetime.datetime`,\r\n`datetime.date`, `datetime.time`, `uuid.UUID`, `numpy.ndarray`, and\r\n`orjson.Fragment` instances. It supports arbitrary types through `default`. It\r\nserializes subclasses of `str`, `int`, `dict`, `list`,\r\n`dataclasses.dataclass`, and `enum.Enum`. It does not serialize subclasses\r\nof `tuple` to avoid serializing `namedtuple` objects as arrays. To avoid\r\nserializing subclasses, specify the option `orjson.OPT_PASSTHROUGH_SUBCLASS`.\r\n\r\nThe output is a `bytes` object containing UTF-8.\r\n\r\nThe global interpreter lock (GIL) is held for the duration of the call.\r\n\r\nIt raises `JSONEncodeError` on an unsupported type. This exception message\r\ndescribes the invalid object with the error message\r\n`Type is not JSON serializable: ...`. To fix this, specify\r\n[default](https://github.com/ijl/orjson?tab=readme-ov-file#default).\r\n\r\nIt raises `JSONEncodeError` on a `str` that contains invalid UTF-8.\r\n\r\nIt raises `JSONEncodeError` on an integer that exceeds 64 bits by default or,\r\nwith `OPT_STRICT_INTEGER`, 53 bits.\r\n\r\nIt raises `JSONEncodeError` if a `dict` has a key of a type other than `str`,\r\nunless `OPT_NON_STR_KEYS` is specified.\r\n\r\nIt raises `JSONEncodeError` if the output of `default` recurses to handling by\r\n`default` more than 254 levels deep.\r\n\r\nIt raises `JSONEncodeError` on circular references.\r\n\r\nIt raises `JSONEncodeError` if a `tzinfo` on a datetime object is\r\nunsupported.\r\n\r\n`JSONEncodeError` is a subclass of `TypeError`. This is for compatibility\r\nwith the standard library.\r\n\r\nIf the failure was caused by an exception in `default` then\r\n`JSONEncodeError` chains the original exception as `__cause__`.\r\n\r\n#### default\r\n\r\nTo serialize a subclass or arbitrary types, specify `default` as a\r\ncallable that returns a supported type. `default` may be a function,\r\nlambda, or callable class instance. To specify that a type was not\r\nhandled by `default`, raise an exception such as `TypeError`.\r\n\r\n```python\r\n>>> import orjson, decimal\r\n>>>\r\ndef default(obj):\r\n if isinstance(obj, decimal.Decimal):\r\n return str(obj)\r\n raise TypeError\r\n\r\n>>> orjson.dumps(decimal.Decimal(\"0.0842389659712649442845\"))\r\nJSONEncodeError: Type is not JSON serializable: decimal.Decimal\r\n>>> orjson.dumps(decimal.Decimal(\"0.0842389659712649442845\"), default=default)\r\nb'\"0.0842389659712649442845\"'\r\n>>> orjson.dumps({1, 2}, default=default)\r\norjson.JSONEncodeError: Type is not JSON serializable: set\r\n```\r\n\r\nThe `default` callable may return an object that itself\r\nmust be handled by `default` up to 254 times before an exception\r\nis raised.\r\n\r\nIt is important that `default` raise an exception if a type cannot be handled.\r\nPython otherwise implicitly returns `None`, which appears to the caller\r\nlike a legitimate value and is serialized:\r\n\r\n```python\r\n>>> import orjson, json, rapidjson\r\n>>>\r\ndef default(obj):\r\n if isinstance(obj, decimal.Decimal):\r\n return str(obj)\r\n\r\n>>> orjson.dumps({\"set\":{1, 2}}, default=default)\r\nb'{\"set\":null}'\r\n>>> json.dumps({\"set\":{1, 2}}, default=default)\r\n'{\"set\":null}'\r\n>>> rapidjson.dumps({\"set\":{1, 2}}, default=default)\r\n'{\"set\":null}'\r\n```\r\n\r\n#### option\r\n\r\nTo modify how data is serialized, specify `option`. Each `option` is an integer\r\nconstant in `orjson`. To specify multiple options, mask them together, e.g.,\r\n`option=orjson.OPT_STRICT_INTEGER | orjson.OPT_NAIVE_UTC`.\r\n\r\n##### OPT_APPEND_NEWLINE\r\n\r\nAppend `\\n` to the output. This is a convenience and optimization for the\r\npattern of `dumps(...) + \"\\n\"`. `bytes` objects are immutable and this\r\npattern copies the original contents.\r\n\r\n```python\r\n>>> import orjson\r\n>>> orjson.dumps([])\r\nb\"[]\"\r\n>>> orjson.dumps([], option=orjson.OPT_APPEND_NEWLINE)\r\nb\"[]\\n\"\r\n```\r\n\r\n##### OPT_INDENT_2\r\n\r\nPretty-print output with an indent of two spaces. This is equivalent to\r\n`indent=2` in the standard library. Pretty printing is slower and the output\r\nlarger. orjson is the fastest compared library at pretty printing and has\r\nmuch less of a slowdown to pretty print than the standard library does. This\r\noption is compatible with all other options.\r\n\r\n```python\r\n>>> import orjson\r\n>>> orjson.dumps({\"a\": \"b\", \"c\": {\"d\": True}, \"e\": [1, 2]})\r\nb'{\"a\":\"b\",\"c\":{\"d\":true},\"e\":[1,2]}'\r\n>>> orjson.dumps(\r\n {\"a\": \"b\", \"c\": {\"d\": True}, \"e\": [1, 2]},\r\n option=orjson.OPT_INDENT_2\r\n)\r\nb'{\\n \"a\": \"b\",\\n \"c\": {\\n \"d\": true\\n },\\n \"e\": [\\n 1,\\n 2\\n ]\\n}'\r\n```\r\n\r\nIf displayed, the indentation and linebreaks appear like this:\r\n\r\n```json\r\n{\r\n \"a\": \"b\",\r\n \"c\": {\r\n \"d\": true\r\n },\r\n \"e\": [\r\n 1,\r\n 2\r\n ]\r\n}\r\n```\r\n\r\nThis measures serializing the github.json fixture as compact (52KiB) or\r\npretty (64KiB):\r\n\r\n| Library | compact (ms) | pretty (ms) | vs. orjson |\r\n|------------|----------------|---------------|--------------|\r\n| orjson | 0.03 | 0.04 | 1 |\r\n| ujson | 0.18 | 0.19 | 4.6 |\r\n| rapidjson | 0.1 | 0.12 | 2.9 |\r\n| simplejson | 0.25 | 0.89 | 21.4 |\r\n| json | 0.18 | 0.71 | 17 |\r\n\r\nThis measures serializing the citm_catalog.json fixture, more of a worst\r\ncase due to the amount of nesting and newlines, as compact (489KiB) or\r\npretty (1.1MiB):\r\n\r\n| Library | compact (ms) | pretty (ms) | vs. orjson |\r\n|------------|----------------|---------------|--------------|\r\n| orjson | 0.59 | 0.71 | 1 |\r\n| ujson | 2.9 | 3.59 | 5 |\r\n| rapidjson | 1.81 | 2.8 | 3.9 |\r\n| simplejson | 10.43 | 42.13 | 59.1 |\r\n| json | 4.16 | 33.42 | 46.9 |\r\n\r\nThis can be reproduced using the `pyindent` script.\r\n\r\n##### OPT_NAIVE_UTC\r\n\r\nSerialize `datetime.datetime` objects without a `tzinfo` as UTC. This\r\nhas no effect on `datetime.datetime` objects that have `tzinfo` set.\r\n\r\n```python\r\n>>> import orjson, datetime\r\n>>> orjson.dumps(\r\n datetime.datetime(1970, 1, 1, 0, 0, 0),\r\n )\r\nb'\"1970-01-01T00:00:00\"'\r\n>>> orjson.dumps(\r\n datetime.datetime(1970, 1, 1, 0, 0, 0),\r\n option=orjson.OPT_NAIVE_UTC,\r\n )\r\nb'\"1970-01-01T00:00:00+00:00\"'\r\n```\r\n\r\n##### OPT_NON_STR_KEYS\r\n\r\nSerialize `dict` keys of type other than `str`. This allows `dict` keys\r\nto be one of `str`, `int`, `float`, `bool`, `None`, `datetime.datetime`,\r\n`datetime.date`, `datetime.time`, `enum.Enum`, and `uuid.UUID`. For comparison,\r\nthe standard library serializes `str`, `int`, `float`, `bool` or `None` by\r\ndefault. orjson benchmarks as being faster at serializing non-`str` keys\r\nthan other libraries. This option is slower for `str` keys than the default.\r\n\r\n```python\r\n>>> import orjson, datetime, uuid\r\n>>> orjson.dumps(\r\n {uuid.UUID(\"7202d115-7ff3-4c81-a7c1-2a1f067b1ece\"): [1, 2, 3]},\r\n option=orjson.OPT_NON_STR_KEYS,\r\n )\r\nb'{\"7202d115-7ff3-4c81-a7c1-2a1f067b1ece\":[1,2,3]}'\r\n>>> orjson.dumps(\r\n {datetime.datetime(1970, 1, 1, 0, 0, 0): [1, 2, 3]},\r\n option=orjson.OPT_NON_STR_KEYS | orjson.OPT_NAIVE_UTC,\r\n )\r\nb'{\"1970-01-01T00:00:00+00:00\":[1,2,3]}'\r\n```\r\n\r\nThese types are generally serialized how they would be as\r\nvalues, e.g., `datetime.datetime` is still an RFC 3339 string and respects\r\noptions affecting it. The exception is that `int` serialization does not\r\nrespect `OPT_STRICT_INTEGER`.\r\n\r\nThis option has the risk of creating duplicate keys. This is because non-`str`\r\nobjects may serialize to the same `str` as an existing key, e.g.,\r\n`{\"1\": true, 1: false}`. The last key to be inserted to the `dict` will be\r\nserialized last and a JSON deserializer will presumably take the last\r\noccurrence of a key (in the above, `false`). The first value will be lost.\r\n\r\nThis option is compatible with `orjson.OPT_SORT_KEYS`. If sorting is used,\r\nnote the sort is unstable and will be unpredictable for duplicate keys.\r\n\r\n```python\r\n>>> import orjson, datetime\r\n>>> orjson.dumps(\r\n {\"other\": 1, datetime.date(1970, 1, 5): 2, datetime.date(1970, 1, 3): 3},\r\n option=orjson.OPT_NON_STR_KEYS | orjson.OPT_SORT_KEYS\r\n)\r\nb'{\"1970-01-03\":3,\"1970-01-05\":2,\"other\":1}'\r\n```\r\n\r\nThis measures serializing 589KiB of JSON comprising a `list` of 100 `dict`\r\nin which each `dict` has both 365 randomly-sorted `int` keys representing epoch\r\ntimestamps as well as one `str` key and the value for each key is a\r\nsingle integer. In \"str keys\", the keys were converted to `str` before\r\nserialization, and orjson still specifes `option=orjson.OPT_NON_STR_KEYS`\r\n(which is always somewhat slower).\r\n\r\n| Library | str keys (ms) | int keys (ms) | int keys sorted (ms) |\r\n|------------|-----------------|-----------------|------------------------|\r\n| orjson | 1.53 | 2.16 | 4.29 |\r\n| ujson | 3.07 | 5.65 | |\r\n| rapidjson | 4.29 | | |\r\n| simplejson | 11.24 | 14.50 | 21.86 |\r\n| json | 7.17 | 8.49 | |\r\n\r\nujson is blank for sorting because it segfaults. json is blank because it\r\nraises `TypeError` on attempting to sort before converting all keys to `str`.\r\nrapidjson is blank because it does not support non-`str` keys. This can\r\nbe reproduced using the `pynonstr` script.\r\n\r\n##### OPT_OMIT_MICROSECONDS\r\n\r\nDo not serialize the `microsecond` field on `datetime.datetime` and\r\n`datetime.time` instances.\r\n\r\n```python\r\n>>> import orjson, datetime\r\n>>> orjson.dumps(\r\n datetime.datetime(1970, 1, 1, 0, 0, 0, 1),\r\n )\r\nb'\"1970-01-01T00:00:00.000001\"'\r\n>>> orjson.dumps(\r\n datetime.datetime(1970, 1, 1, 0, 0, 0, 1),\r\n option=orjson.OPT_OMIT_MICROSECONDS,\r\n )\r\nb'\"1970-01-01T00:00:00\"'\r\n```\r\n\r\n##### OPT_PASSTHROUGH_DATACLASS\r\n\r\nPassthrough `dataclasses.dataclass` instances to `default`. This allows\r\ncustomizing their output but is much slower.\r\n\r\n\r\n```python\r\n>>> import orjson, dataclasses\r\n>>>\r\n@dataclasses.dataclass\r\nclass User:\r\n id: str\r\n name: str\r\n password: str\r\n\r\ndef default(obj):\r\n if isinstance(obj, User):\r\n return {\"id\": obj.id, \"name\": obj.name}\r\n raise TypeError\r\n\r\n>>> orjson.dumps(User(\"3b1\", \"asd\", \"zxc\"))\r\nb'{\"id\":\"3b1\",\"name\":\"asd\",\"password\":\"zxc\"}'\r\n>>> orjson.dumps(User(\"3b1\", \"asd\", \"zxc\"), option=orjson.OPT_PASSTHROUGH_DATACLASS)\r\nTypeError: Type is not JSON serializable: User\r\n>>> orjson.dumps(\r\n User(\"3b1\", \"asd\", \"zxc\"),\r\n option=orjson.OPT_PASSTHROUGH_DATACLASS,\r\n default=default,\r\n )\r\nb'{\"id\":\"3b1\",\"name\":\"asd\"}'\r\n```\r\n\r\n##### OPT_PASSTHROUGH_DATETIME\r\n\r\nPassthrough `datetime.datetime`, `datetime.date`, and `datetime.time` instances\r\nto `default`. This allows serializing datetimes to a custom format, e.g.,\r\nHTTP dates:\r\n\r\n```python\r\n>>> import orjson, datetime\r\n>>>\r\ndef default(obj):\r\n if isinstance(obj, datetime.datetime):\r\n return obj.strftime(\"%a, %d %b %Y %H:%M:%S GMT\")\r\n raise TypeError\r\n\r\n>>> orjson.dumps({\"created_at\": datetime.datetime(1970, 1, 1)})\r\nb'{\"created_at\":\"1970-01-01T00:00:00\"}'\r\n>>> orjson.dumps({\"created_at\": datetime.datetime(1970, 1, 1)}, option=orjson.OPT_PASSTHROUGH_DATETIME)\r\nTypeError: Type is not JSON serializable: datetime.datetime\r\n>>> orjson.dumps(\r\n {\"created_at\": datetime.datetime(1970, 1, 1)},\r\n option=orjson.OPT_PASSTHROUGH_DATETIME,\r\n default=default,\r\n )\r\nb'{\"created_at\":\"Thu, 01 Jan 1970 00:00:00 GMT\"}'\r\n```\r\n\r\nThis does not affect datetimes in `dict` keys if using OPT_NON_STR_KEYS.\r\n\r\n##### OPT_PASSTHROUGH_SUBCLASS\r\n\r\nPassthrough subclasses of builtin types to `default`.\r\n\r\n```python\r\n>>> import orjson\r\n>>>\r\nclass Secret(str):\r\n pass\r\n\r\ndef default(obj):\r\n if isinstance(obj, Secret):\r\n return \"******\"\r\n raise TypeError\r\n\r\n>>> orjson.dumps(Secret(\"zxc\"))\r\nb'\"zxc\"'\r\n>>> orjson.dumps(Secret(\"zxc\"), option=orjson.OPT_PASSTHROUGH_SUBCLASS)\r\nTypeError: Type is not JSON serializable: Secret\r\n>>> orjson.dumps(Secret(\"zxc\"), option=orjson.OPT_PASSTHROUGH_SUBCLASS, default=default)\r\nb'\"******\"'\r\n```\r\n\r\nThis does not affect serializing subclasses as `dict` keys if using\r\nOPT_NON_STR_KEYS.\r\n\r\n##### OPT_SERIALIZE_DATACLASS\r\n\r\nThis is deprecated and has no effect in version 3. In version 2 this was\r\nrequired to serialize `dataclasses.dataclass` instances. For more, see\r\n[dataclass](https://github.com/ijl/orjson?tab=readme-ov-file#dataclass).\r\n\r\n##### OPT_SERIALIZE_NUMPY\r\n\r\nSerialize `numpy.ndarray` instances. For more, see\r\n[numpy](https://github.com/ijl/orjson?tab=readme-ov-file#numpy).\r\n\r\n##### OPT_SERIALIZE_UUID\r\n\r\nThis is deprecated and has no effect in version 3. In version 2 this was\r\nrequired to serialize `uuid.UUID` instances. For more, see\r\n[UUID](https://github.com/ijl/orjson?tab=readme-ov-file#UUID).\r\n\r\n##### OPT_SORT_KEYS\r\n\r\nSerialize `dict` keys in sorted order. The default is to serialize in an\r\nunspecified order. This is equivalent to `sort_keys=True` in the standard\r\nlibrary.\r\n\r\nThis can be used to ensure the order is deterministic for hashing or tests.\r\nIt has a substantial performance penalty and is not recommended in general.\r\n\r\n```python\r\n>>> import orjson\r\n>>> orjson.dumps({\"b\": 1, \"c\": 2, \"a\": 3})\r\nb'{\"b\":1,\"c\":2,\"a\":3}'\r\n>>> orjson.dumps({\"b\": 1, \"c\": 2, \"a\": 3}, option=orjson.OPT_SORT_KEYS)\r\nb'{\"a\":3,\"b\":1,\"c\":2}'\r\n```\r\n\r\nThis measures serializing the twitter.json fixture unsorted and sorted:\r\n\r\n| Library | unsorted (ms) | sorted (ms) | vs. orjson |\r\n|------------|-----------------|---------------|--------------|\r\n| orjson | 0.32 | 0.54 | 1 |\r\n| ujson | 1.6 | 2.07 | 3.8 |\r\n| rapidjson | 1.12 | 1.65 | 3.1 |\r\n| simplejson | 2.25 | 3.13 | 5.8 |\r\n| json | 1.78 | 2.32 | 4.3 |\r\n\r\nThe benchmark can be reproduced using the `pysort` script.\r\n\r\nThe sorting is not collation/locale-aware:\r\n\r\n```python\r\n>>> import orjson\r\n>>> orjson.dumps({\"a\": 1, \"\u00e4\": 2, \"A\": 3}, option=orjson.OPT_SORT_KEYS)\r\nb'{\"A\":3,\"a\":1,\"\\xc3\\xa4\":2}'\r\n```\r\n\r\nThis is the same sorting behavior as the standard library, rapidjson,\r\nsimplejson, and ujson.\r\n\r\n`dataclass` also serialize as maps but this has no effect on them.\r\n\r\n##### OPT_STRICT_INTEGER\r\n\r\nEnforce 53-bit limit on integers. The limit is otherwise 64 bits, the same as\r\nthe Python standard library. For more, see [int](https://github.com/ijl/orjson?tab=readme-ov-file#int).\r\n\r\n##### OPT_UTC_Z\r\n\r\nSerialize a UTC timezone on `datetime.datetime` instances as `Z` instead\r\nof `+00:00`.\r\n\r\n```python\r\n>>> import orjson, datetime, zoneinfo\r\n>>> orjson.dumps(\r\n datetime.datetime(1970, 1, 1, 0, 0, 0, tzinfo=zoneinfo.ZoneInfo(\"UTC\")),\r\n )\r\nb'\"1970-01-01T00:00:00+00:00\"'\r\n>>> orjson.dumps(\r\n datetime.datetime(1970, 1, 1, 0, 0, 0, tzinfo=zoneinfo.ZoneInfo(\"UTC\")),\r\n option=orjson.OPT_UTC_Z\r\n )\r\nb'\"1970-01-01T00:00:00Z\"'\r\n```\r\n\r\n#### Fragment\r\n\r\n`orjson.Fragment` includes already-serialized JSON in a document. This is an\r\nefficient way to include JSON blobs from a cache, JSONB field, or separately\r\nserialized object without first deserializing to Python objects via `loads()`.\r\n\r\n```python\r\n>>> import orjson\r\n>>> orjson.dumps({\"key\": \"zxc\", \"data\": orjson.Fragment(b'{\"a\": \"b\", \"c\": 1}')})\r\nb'{\"key\":\"zxc\",\"data\":{\"a\": \"b\", \"c\": 1}}'\r\n```\r\n\r\nIt does no reformatting: `orjson.OPT_INDENT_2` will not affect a\r\ncompact blob nor will a pretty-printed JSON blob be rewritten as compact.\r\n\r\nThe input must be `bytes` or `str` and given as a positional argument.\r\n\r\nThis raises `orjson.JSONEncodeError` if a `str` is given and the input is\r\nnot valid UTF-8. It otherwise does no validation and it is possible to\r\nwrite invalid JSON. This does not escape characters. The implementation is\r\ntested to not crash if given invalid strings or invalid JSON.\r\n\r\nThis is similar to `RawJSON` in rapidjson.\r\n\r\n### Deserialize\r\n\r\n```python\r\ndef loads(__obj: Union[bytes, bytearray, memoryview, str]) -> Any: ...\r\n```\r\n\r\n`loads()` deserializes JSON to Python objects. It deserializes to `dict`,\r\n`list`, `int`, `float`, `str`, `bool`, and `None` objects.\r\n\r\n`bytes`, `bytearray`, `memoryview`, and `str` input are accepted. If the input\r\nexists as a `memoryview`, `bytearray`, or `bytes` object, it is recommended to\r\npass these directly rather than creating an unnecessary `str` object. That is,\r\n`orjson.loads(b\"{}\")` instead of `orjson.loads(b\"{}\".decode(\"utf-8\"))`. This\r\nhas lower memory usage and lower latency.\r\n\r\nThe input must be valid UTF-8.\r\n\r\norjson maintains a cache of map keys for the duration of the process. This\r\ncauses a net reduction in memory usage by avoiding duplicate strings. The\r\nkeys must be at most 64 bytes to be cached and 2048 entries are stored.\r\n\r\nThe global interpreter lock (GIL) is held for the duration of the call.\r\n\r\nIt raises `JSONDecodeError` if given an invalid type or invalid\r\nJSON. This includes if the input contains `NaN`, `Infinity`, or `-Infinity`,\r\nwhich the standard library allows, but is not valid JSON.\r\n\r\nIt raises `JSONDecodeError` if a combination of array or object recurses\r\n1024 levels deep.\r\n\r\n`JSONDecodeError` is a subclass of `json.JSONDecodeError` and `ValueError`.\r\nThis is for compatibility with the standard library.\r\n\r\n## Types\r\n\r\n### dataclass\r\n\r\norjson serializes instances of `dataclasses.dataclass` natively. It serializes\r\ninstances 40-50x as fast as other libraries and avoids a severe slowdown seen\r\nin other libraries compared to serializing `dict`.\r\n\r\nIt is supported to pass all variants of dataclasses, including dataclasses\r\nusing `__slots__`, frozen dataclasses, those with optional or default\r\nattributes, and subclasses. There is a performance benefit to not\r\nusing `__slots__`.\r\n\r\n| Library | dict (ms) | dataclass (ms) | vs. orjson |\r\n|------------|-------------|------------------|--------------|\r\n| orjson | 1.40 | 1.60 | 1 |\r\n| ujson | | | |\r\n| rapidjson | 3.64 | 68.48 | 42 |\r\n| simplejson | 14.21 | 92.18 | 57 |\r\n| json | 13.28 | 94.90 | 59 |\r\n\r\nThis measures serializing 555KiB of JSON, orjson natively and other libraries\r\nusing `default` to serialize the output of `dataclasses.asdict()`. This can be\r\nreproduced using the `pydataclass` script.\r\n\r\nDataclasses are serialized as maps, with every attribute serialized and in\r\nthe order given on class definition:\r\n\r\n```python\r\n>>> import dataclasses, orjson, typing\r\n\r\n@dataclasses.dataclass\r\nclass Member:\r\n id: int\r\n active: bool = dataclasses.field(default=False)\r\n\r\n@dataclasses.dataclass\r\nclass Object:\r\n id: int\r\n name: str\r\n members: typing.List[Member]\r\n\r\n>>> orjson.dumps(Object(1, \"a\", [Member(1, True), Member(2)]))\r\nb'{\"id\":1,\"name\":\"a\",\"members\":[{\"id\":1,\"active\":true},{\"id\":2,\"active\":false}]}'\r\n```\r\n\r\n### datetime\r\n\r\norjson serializes `datetime.datetime` objects to\r\n[RFC 3339](https://tools.ietf.org/html/rfc3339) format,\r\ne.g., \"1970-01-01T00:00:00+00:00\". This is a subset of ISO 8601 and is\r\ncompatible with `isoformat()` in the standard library.\r\n\r\n```python\r\n>>> import orjson, datetime, zoneinfo\r\n>>> orjson.dumps(\r\n datetime.datetime(2018, 12, 1, 2, 3, 4, 9, tzinfo=zoneinfo.ZoneInfo(\"Australia/Adelaide\"))\r\n)\r\nb'\"2018-12-01T02:03:04.000009+10:30\"'\r\n>>> orjson.dumps(\r\n datetime.datetime(2100, 9, 1, 21, 55, 2).replace(tzinfo=zoneinfo.ZoneInfo(\"UTC\"))\r\n)\r\nb'\"2100-09-01T21:55:02+00:00\"'\r\n>>> orjson.dumps(\r\n datetime.datetime(2100, 9, 1, 21, 55, 2)\r\n)\r\nb'\"2100-09-01T21:55:02\"'\r\n```\r\n\r\n`datetime.datetime` supports instances with a `tzinfo` that is `None`,\r\n`datetime.timezone.utc`, a timezone instance from the python3.9+ `zoneinfo`\r\nmodule, or a timezone instance from the third-party `pendulum`, `pytz`, or\r\n`dateutil`/`arrow` libraries.\r\n\r\nIt is fastest to use the standard library's `zoneinfo.ZoneInfo` for timezones.\r\n\r\n`datetime.time` objects must not have a `tzinfo`.\r\n\r\n```python\r\n>>> import orjson, datetime\r\n>>> orjson.dumps(datetime.time(12, 0, 15, 290))\r\nb'\"12:00:15.000290\"'\r\n```\r\n\r\n`datetime.date` objects will always serialize.\r\n\r\n```python\r\n>>> import orjson, datetime\r\n>>> orjson.dumps(datetime.date(1900, 1, 2))\r\nb'\"1900-01-02\"'\r\n```\r\n\r\nErrors with `tzinfo` result in `JSONEncodeError` being raised.\r\n\r\nTo disable serialization of `datetime` objects specify the option\r\n`orjson.OPT_PASSTHROUGH_DATETIME`.\r\n\r\nTo use \"Z\" suffix instead of \"+00:00\" to indicate UTC (\"Zulu\") time, use the option\r\n`orjson.OPT_UTC_Z`.\r\n\r\nTo assume datetimes without timezone are UTC, use the option `orjson.OPT_NAIVE_UTC`.\r\n\r\n### enum\r\n\r\norjson serializes enums natively. Options apply to their values.\r\n\r\n```python\r\n>>> import enum, datetime, orjson\r\n>>>\r\nclass DatetimeEnum(enum.Enum):\r\n EPOCH = datetime.datetime(1970, 1, 1, 0, 0, 0)\r\n>>> orjson.dumps(DatetimeEnum.EPOCH)\r\nb'\"1970-01-01T00:00:00\"'\r\n>>> orjson.dumps(DatetimeEnum.EPOCH, option=orjson.OPT_NAIVE_UTC)\r\nb'\"1970-01-01T00:00:00+00:00\"'\r\n```\r\n\r\nEnums with members that are not supported types can be serialized using\r\n`default`:\r\n\r\n```python\r\n>>> import enum, orjson\r\n>>>\r\nclass Custom:\r\n def __init__(self, val):\r\n self.val = val\r\n\r\ndef default(obj):\r\n if isinstance(obj, Custom):\r\n return obj.val\r\n raise TypeError\r\n\r\nclass CustomEnum(enum.Enum):\r\n ONE = Custom(1)\r\n\r\n>>> orjson.dumps(CustomEnum.ONE, default=default)\r\nb'1'\r\n```\r\n\r\n### float\r\n\r\norjson serializes and deserializes double precision floats with no loss of\r\nprecision and consistent rounding.\r\n\r\n`orjson.dumps()` serializes Nan, Infinity, and -Infinity, which are not\r\ncompliant JSON, as `null`:\r\n\r\n```python\r\n>>> import orjson, ujson, rapidjson, json\r\n>>> orjson.dumps([float(\"NaN\"), float(\"Infinity\"), float(\"-Infinity\")])\r\nb'[null,null,null]'\r\n>>> ujson.dumps([float(\"NaN\"), float(\"Infinity\"), float(\"-Infinity\")])\r\nOverflowError: Invalid Inf value when encoding double\r\n>>> rapidjson.dumps([float(\"NaN\"), float(\"Infinity\"), float(\"-Infinity\")])\r\n'[NaN,Infinity,-Infinity]'\r\n>>> json.dumps([float(\"NaN\"), float(\"Infinity\"), float(\"-Infinity\")])\r\n'[NaN, Infinity, -Infinity]'\r\n```\r\n\r\n### int\r\n\r\norjson serializes and deserializes 64-bit integers by default. The range\r\nsupported is a signed 64-bit integer's minimum (-9223372036854775807) to\r\nan unsigned 64-bit integer's maximum (18446744073709551615). This\r\nis widely compatible, but there are implementations\r\nthat only support 53-bits for integers, e.g.,\r\nweb browsers. For those implementations, `dumps()` can be configured to\r\nraise a `JSONEncodeError` on values exceeding the 53-bit range.\r\n\r\n```python\r\n>>> import orjson\r\n>>> orjson.dumps(9007199254740992)\r\nb'9007199254740992'\r\n>>> orjson.dumps(9007199254740992, option=orjson.OPT_STRICT_INTEGER)\r\nJSONEncodeError: Integer exceeds 53-bit range\r\n>>> orjson.dumps(-9007199254740992, option=orjson.OPT_STRICT_INTEGER)\r\nJSONEncodeError: Integer exceeds 53-bit range\r\n```\r\n\r\n### numpy\r\n\r\norjson natively serializes `numpy.ndarray` and individual\r\n`numpy.float64`, `numpy.float32`, `numpy.float16` (`numpy.half`),\r\n`numpy.int64`, `numpy.int32`, `numpy.int16`, `numpy.int8`,\r\n`numpy.uint64`, `numpy.uint32`, `numpy.uint16`, `numpy.uint8`,\r\n`numpy.uintp`, `numpy.intp`, `numpy.datetime64`, and `numpy.bool`\r\ninstances.\r\n\r\norjson is compatible with both numpy v1 and v2.\r\n\r\norjson is faster than all compared libraries at serializing\r\nnumpy instances. Serializing numpy data requires specifying\r\n`option=orjson.OPT_SERIALIZE_NUMPY`.\r\n\r\n```python\r\n>>> import orjson, numpy\r\n>>> orjson.dumps(\r\n numpy.array([[1, 2, 3], [4, 5, 6]]),\r\n option=orjson.OPT_SERIALIZE_NUMPY,\r\n)\r\nb'[[1,2,3],[4,5,6]]'\r\n```\r\n\r\nThe array must be a contiguous C array (`C_CONTIGUOUS`) and one of the\r\nsupported datatypes.\r\n\r\nNote a difference between serializing `numpy.float32` using `ndarray.tolist()`\r\nor `orjson.dumps(..., option=orjson.OPT_SERIALIZE_NUMPY)`: `tolist()` converts\r\nto a `double` before serializing and orjson's native path does not. This\r\ncan result in different rounding.\r\n\r\n`numpy.datetime64` instances are serialized as RFC 3339 strings and\r\ndatetime options affect them.\r\n\r\n```python\r\n>>> import orjson, numpy\r\n>>> orjson.dumps(\r\n numpy.datetime64(\"2021-01-01T00:00:00.172\"),\r\n option=orjson.OPT_SERIALIZE_NUMPY,\r\n)\r\nb'\"2021-01-01T00:00:00.172000\"'\r\n>>> orjson.dumps(\r\n numpy.datetime64(\"2021-01-01T00:00:00.172\"),\r\n option=(\r\n orjson.OPT_SERIALIZE_NUMPY |\r\n orjson.OPT_NAIVE_UTC |\r\n orjson.OPT_OMIT_MICROSECONDS\r\n ),\r\n)\r\nb'\"2021-01-01T00:00:00+00:00\"'\r\n```\r\n\r\nIf an array is not a contiguous C array, contains an unsupported datatype,\r\nor contains a `numpy.datetime64` using an unsupported representation\r\n(e.g., picoseconds), orjson falls through to `default`. In `default`,\r\n`obj.tolist()` can be specified.\r\n\r\nIf an array is not in the native endianness, e.g., an array of big-endian values\r\non a little-endian system, `orjson.JSONEncodeError` is raised.\r\n\r\nIf an array is malformed, `orjson.JSONEncodeError` is raised.\r\n\r\nThis measures serializing 92MiB of JSON from an `numpy.ndarray` with\r\ndimensions of `(50000, 100)` and `numpy.float64` values:\r\n\r\n| Library | Latency (ms) | RSS diff (MiB) | vs. orjson |\r\n|------------|----------------|------------------|--------------|\r\n| orjson | 194 | 99 | 1.0 |\r\n| ujson | | | |\r\n| rapidjson | 3,048 | 309 | 15.7 |\r\n| simplejson | 3,023 | 297 | 15.6 |\r\n| json | 3,133 | 297 | 16.1 |\r\n\r\nThis measures serializing 100MiB of JSON from an `numpy.ndarray` with\r\ndimensions of `(100000, 100)` and `numpy.int32` values:\r\n\r\n| Library | Latency (ms) | RSS diff (MiB) | vs. orjson |\r\n|------------|----------------|------------------|--------------|\r\n| orjson | 178 | 115 | 1.0 |\r\n| ujson | | | |\r\n| rapidjson | 1,512 | 551 | 8.5 |\r\n| simplejson | 1,606 | 504 | 9.0 |\r\n| json | 1,506 | 503 | 8.4 |\r\n\r\nThis measures serializing 105MiB of JSON from an `numpy.ndarray` with\r\ndimensions of `(100000, 200)` and `numpy.bool` values:\r\n\r\n| Library | Latency (ms) | RSS diff (MiB) | vs. orjson |\r\n|------------|----------------|------------------|--------------|\r\n| orjson | 157 | 120 | 1.0 |\r\n| ujson | | | |\r\n| rapidjson | 710 | 327 | 4.5 |\r\n| simplejson | 931 | 398 | 5.9 |\r\n| json | 996 | 400 | 6.3 |\r\n\r\nIn these benchmarks, orjson serializes natively, ujson is blank because it\r\ndoes not support a `default` parameter, and the other libraries serialize\r\n`ndarray.tolist()` via `default`. The RSS column measures peak memory\r\nusage during serialization. This can be reproduced using the `pynumpy` script.\r\n\r\norjson does not have an installation or compilation dependency on numpy. The\r\nimplementation is independent, reading `numpy.ndarray` using\r\n`PyArrayInterface`.\r\n\r\n### str\r\n\r\norjson is strict about UTF-8 conformance. This is stricter than the standard\r\nlibrary's json module, which will serialize and deserialize UTF-16 surrogates,\r\ne.g., \"\\ud800\", that are invalid UTF-8.\r\n\r\nIf `orjson.dumps()` is given a `str` that does not contain valid UTF-8,\r\n`orjson.JSONEncodeError` is raised. If `loads()` receives invalid UTF-8,\r\n`orjson.JSONDecodeError` is raised.\r\n\r\norjson and rapidjson are the only compared JSON libraries to consistently\r\nerror on bad input.\r\n\r\n```python\r\n>>> import orjson, ujson, rapidjson, json\r\n>>> orjson.dumps('\\ud800')\r\nJSONEncodeError: str is not valid UTF-8: surrogates not allowed\r\n>>> ujson.dumps('\\ud800')\r\nUnicodeEncodeError: 'utf-8' codec ...\r\n>>> rapidjson.dumps('\\ud800')\r\nUnicodeEncodeError: 'utf-8' codec ...\r\n>>> json.dumps('\\ud800')\r\n'\"\\\\ud800\"'\r\n>>> orjson.loads('\"\\\\ud800\"')\r\nJSONDecodeError: unexpected end of hex escape at line 1 column 8: line 1 column 1 (char 0)\r\n>>> ujson.loads('\"\\\\ud800\"')\r\n''\r\n>>> rapidjson.loads('\"\\\\ud800\"')\r\nValueError: Parse error at offset 1: The surrogate pair in string is invalid.\r\n>>> json.loads('\"\\\\ud800\"')\r\n'\\ud800'\r\n```\r\n\r\nTo make a best effort at deserializing bad input, first decode `bytes` using\r\nthe `replace` or `lossy` argument for `errors`:\r\n\r\n```python\r\n>>> import orjson\r\n>>> orjson.loads(b'\"\\xed\\xa0\\x80\"')\r\nJSONDecodeError: str is not valid UTF-8: surrogates not allowed\r\n>>> orjson.loads(b'\"\\xed\\xa0\\x80\"'.decode(\"utf-8\", \"replace\"))\r\n'\ufffd\ufffd\ufffd'\r\n```\r\n\r\n### uuid\r\n\r\norjson serializes `uuid.UUID` instances to\r\n[RFC 4122](https://tools.ietf.org/html/rfc4122) format, e.g.,\r\n\"f81d4fae-7dec-11d0-a765-00a0c91e6bf6\".\r\n\r\n``` python\r\n>>> import orjson, uuid\r\n>>> orjson.dumps(uuid.UUID('f81d4fae-7dec-11d0-a765-00a0c91e6bf6'))\r\nb'\"f81d4fae-7dec-11d0-a765-00a0c91e6bf6\"'\r\n>>> orjson.dumps(uuid.uuid5(uuid.NAMESPACE_DNS, \"python.org\"))\r\nb'\"886313e1-3b8a-5372-9b90-0c9aee199e5d\"'\r\n```\r\n\r\n## Testing\r\n\r\nThe library has comprehensive tests. There are tests against fixtures in the\r\n[JSONTestSuite](https://github.com/nst/JSONTestSuite) and\r\n[nativejson-benchmark](https://github.com/miloyip/nativejson-benchmark)\r\nrepositories. It is tested to not crash against the\r\n[Big List of Naughty Strings](https://github.com/minimaxir/big-list-of-naughty-strings).\r\nIt is tested to not leak memory. It is tested to not crash\r\nagainst and not accept invalid UTF-8. There are integration tests\r\nexercising the library's use in web servers (gunicorn using multiprocess/forked\r\nworkers) and when\r\nmultithreaded. It also uses some tests from the ultrajson library.\r\n\r\norjson is the most correct of the compared libraries. This graph shows how each\r\nlibrary handles a combined 342 JSON fixtures from the\r\n[JSONTestSuite](https://github.com/nst/JSONTestSuite) and\r\n[nativejson-benchmark](https://github.com/miloyip/nativejson-benchmark) tests:\r\n\r\n| Library | Invalid JSON documents not rejected | Valid JSON documents not deserialized |\r\n|------------|---------------------------------------|-----------------------------------------|\r\n| orjson | 0 | 0 |\r\n| ujson | 31 | 0 |\r\n| rapidjson | 6 | 0 |\r\n| simplejson | 10 | 0 |\r\n| json | 17 | 0 |\r\n\r\nThis shows that all libraries deserialize valid JSON but only orjson\r\ncorrectly rejects the given invalid JSON fixtures. Errors are largely due to\r\naccepting invalid strings and numbers.\r\n\r\nThe graph above can be reproduced using the `pycorrectness` script.\r\n\r\n## Performance\r\n\r\nSerialization and deserialization performance of orjson is better than\r\nultrajson, rapidjson, simplejson, or json. The benchmarks are done on\r\nfixtures of real data:\r\n\r\n* twitter.json, 631.5KiB, results of a search on Twitter for \"\u4e00\", containing\r\nCJK strings, dictionaries of strings and arrays of dictionaries, indented.\r\n\r\n* github.json, 55.8KiB, a GitHub activity feed, containing dictionaries of\r\nstrings and arrays of dictionaries, not indented.\r\n\r\n* citm_catalog.json, 1.7MiB, concert data, containing nested dictionaries of\r\nstrings and arrays of integers, indented.\r\n\r\n* canada.json, 2.2MiB, coordinates of the Canadian border in GeoJSON\r\nformat, containing floats and arrays, indented.\r\n\r\n### Latency\r\n\r\n\r\n\r\n\r\n\r\n#### twitter.json serialization\r\n\r\n| Library | Median latency (milliseconds) | Operations per second | Relative (latency) |\r\n|------------|---------------------------------|-------------------------|----------------------|\r\n| orjson | 0.1 | 8377 | 1 |\r\n| ujson | 0.9 | 1088 | 7.3 |\r\n| rapidjson | 0.8 | 1228 | 6.8 |\r\n| simplejson | 1.9 | 531 | 15.6 |\r\n| json | 1.4 | 744 | 11.3 |\r\n\r\n#### twitter.json deserialization\r\n\r\n| Library | Median latency (milliseconds) | Operations per second | Relative (latency) |\r\n|------------|---------------------------------|-------------------------|----------------------|\r\n| orjson | 0.6 | 1811 | 1 |\r\n| ujson | 1.2 | 814 | 2.1 |\r\n| rapidjson | 2.1 | 476 | 3.8 |\r\n| simplejson | 1.6 | 626 | 3 |\r\n| json | 1.8 | 557 | 3.3 |\r\n\r\n#### github.json serialization\r\n\r\n| Library | Median latency (milliseconds) | Operations per second | Relative (latency) |\r\n|------------|---------------------------------|-------------------------|----------------------|\r\n| orjson | 0.01 | 104424 | 1 |\r\n| ujson | 0.09 | 10594 | 9.8 |\r\n| rapidjson | 0.07 | 13667 | 7.6 |\r\n| simplejson | 0.2 | 5051 | 20.6 |\r\n| json | 0.14 | 7133 | 14.6 |\r\n\r\n#### github.json deserialization\r\n\r\n| Library | Median latency (milliseconds) | Operations per second | Relative (latency) |\r\n|------------|---------------------------------|-------------------------|----------------------|\r\n| orjson | 0.05 | 20069 | 1 |\r\n| ujson | 0.11 | 8913 | 2.3 |\r\n| rapidjson | 0.13 | 8077 | 2.6 |\r\n| simplejson | 0.11 | 9342 | 2.1 |\r\n| json | 0.11 | 9291 | 2.2 |\r\n\r\n#### citm_catalog.json serialization\r\n\r\n| Library | Median latency (milliseconds) | Operations per second | Relative (latency) |\r\n|------------|---------------------------------|-------------------------|----------------------|\r\n| orjson | 0.3 | 3757 | 1 |\r\n| ujson | 1.7 | 598 | 6.3 |\r\n| rapidjson | 1.3 | 768 | 4.9 |\r\n| simplejson | 8.3 | 120 | 31.1 |\r\n| json | 3 | 331 | 11.3 |\r\n\r\n#### citm_catalog.json deserialization\r\n\r\n| Library | Median latency (milliseconds) | Operations per second | Relative (latency) |\r\n|------------|---------------------------------|-------------------------|----------------------|\r\n| orjson | 1.4 | 730 | 1 |\r\n| ujson | 2.6 | 384 | 1.9 |\r\n| rapidjson | 4 | 246 | 3 |\r\n| simplejson | 3.7 | 271 | 2.7 |\r\n| json | 3.7 | 267 | 2.7 |\r\n\r\n#### canada.json serialization\r\n\r\n| Library | Median latency (milliseconds) | Operations per second | Relative (latency) |\r\n|------------|---------------------------------|-------------------------|----------------------|\r\n| orjson | 2.4 | 410 | 1 |\r\n| ujson | 9.6 | 104 | 3.9 |\r\n| rapidjson | 28.7 | 34 | 11.8 |\r\n| simplejson | 49.3 | 20 | 20.3 |\r\n| json | 30.6 | 32 | 12.6 |\r\n\r\n#### canada.json deserialization\r\n\r\n| Library | Median latency (milliseconds) | Operations per second | Relative (latency) |\r\n|------------|---------------------------------|-------------------------|----------------------|\r\n| orjson | 3 | 336 | 1 |\r\n| ujson | 7.1 | 141 | 2.4 |\r\n| rapidjson | 20.1 | 49 | 6.7 |\r\n| simplejson | 16.8 | 59 | 5.6 |\r\n| json | 18.2 | 55 | 6.1 |\r\n\r\n### Memory\r\n\r\norjson as of 3.7.0 has higher baseline memory usage than other libraries\r\ndue to a persistent buffer used for parsing. Incremental memory usage when\r\ndeserializing is similar to the standard library and other third-party\r\nlibraries.\r\n\r\nThis measures, in the first column, RSS after importing a library and reading\r\nthe fixture, and in the second column, increases in RSS after repeatedly\r\ncalling `loads()` on the fixture.\r\n\r\n#### twitter.json\r\n\r\n| Library | import, read() RSS (MiB) | loads() increase in RSS (MiB) |\r\n|------------|----------------------------|---------------------------------|\r\n| orjson | 15.7 | 3.4 |\r\n| ujson | 16.4 | 3.4 |\r\n| rapidjson | 16.6 | 4.4 |\r\n| simplejson | 14.5 | 1.8 |\r\n| json | 13.9 | 1.8 |\r\n\r\n#### github.json\r\n\r\n| Library | import, read() RSS (MiB) | loads() increase in RSS (MiB) |\r\n|------------|----------------------------|---------------------------------|\r\n| orjson | 15.2 | 0.4 |\r\n| ujson | 15.4 | 0.4 |\r\n| rapidjson | 15.7 | 0.5 |\r\n| simplejson | 13.7 | 0.2 |\r\n| json | 13.3 | 0.1 |\r\n\r\n#### citm_catalog.json\r\n\r\n| Library | import, read() RSS (MiB) | loads() increase in RSS (MiB) |\r\n|------------|----------------------------|---------------------------------|\r\n| orjson | 16.8 | 10.1 |\r\n| ujson | 17.3 | 10.2 |\r\n| rapidjson | 17.6 | 28.7 |\r\n| simplejson | 15.8 | 30.1 |\r\n| json | 14.8 | 20.5 |\r\n\r\n#### canada.json\r\n\r\n| Library | import, read() RSS (MiB) | loads() increase in RSS (MiB) |\r\n|------------|----------------------------|---------------------------------|\r\n| orjson | 17.2 | 22.1 |\r\n| ujson | 17.4 | 18.3 |\r\n| rapidjson | 18 | 23.5 |\r\n| simplejson | 15.7 | 21.4 |\r\n| json | 15.4 | 20.4 |\r\n\r\n### Reproducing\r\n\r\nThe above was measured using Python 3.11.9 on Linux (amd64) with\r\norjson 3.10.6, ujson 5.10.0, python-rapidson 1.18, and simplejson 3.19.2.\r\n\r\nThe latency results can be reproduced using the `pybench` and `graph`\r\nscripts. The memory results can be reproduced using the `pymem` script.\r\n\r\n## Questions\r\n\r\n### Why can't I install it from PyPI?\r\n\r\nProbably `pip` needs to be upgraded to version 20.3 or later to support\r\nthe latest manylinux_x_y or universal2 wheel formats.\r\n\r\n### \"Cargo, the Rust package manager, is not installed or is not on PATH.\"\r\n\r\nThis happens when there are no binary wheels (like manylinux) for your\r\nplatform on PyPI. You can install [Rust](https://www.rust-lang.org/) through\r\n`rustup` or a package manager and then it will compile.\r\n\r\n### Will it deserialize to dataclasses, UUIDs, decimals, etc or support object_hook?\r\n\r\nNo. This requires a schema specifying what types are expected and how to\r\nhandle errors etc. This is addressed by data validation libraries a\r\nlevel above this.\r\n\r\n### Will it serialize to `str`?\r\n\r\nNo. `bytes` is the correct type for a serialized blob.\r\n\r\n### Will it support NDJSON or JSONL?\r\n\r\nNo. [orjsonl](https://github.com/umarbutler/orjsonl) may be appropriate.\r\n\r\n### Will it support JSON5 or RJSON?\r\n\r\nNo, it supports RFC 8259.\r\n\r\n## Packaging\r\n\r\nTo package orjson requires at least [Rust](https://www.rust-lang.org/) 1.72\r\nand the [maturin](https://github.com/PyO3/maturin) build tool. The recommended\r\nbuild command is:\r\n\r\n```sh\r\nmaturin build --release --strip\r\n```\r\n\r\nIt benefits from also having a C build environment to compile a faster\r\ndeserialization backend. See this project's `manylinux_2_28` builds for an\r\nexample using clang and LTO.\r\n\r\nThe project's own CI tests against `nightly-2024-09-25` and stable 1.72. It\r\nis prudent to pin the nightly version because that channel can introduce\r\nbreaking changes.\r\n\r\norjson is tested for amd64 on Linux and cross-compiles for aarch64, arm7,\r\nppc64le, and s390x. It is tested for either aarch64 or amd64 on macOS and\r\ncross-compiles for the other, depending on version. For Windows it is\r\ntested on amd64 and i686.\r\n\r\nThere are no runtime dependencies other than libc.\r\n\r\nThe source distribution on PyPI contains all dependencies' source and can be\r\nbuilt without network access. The file can be downloaded from\r\n`https://files.pythonhosted.org/packages/source/o/orjson/orjson-${version}.tar.gz`.\r\n\r\norjson's tests are included in the source distribution on PyPI. The\r\nrequirements to run the tests are specified in `test/requirements.txt`. The\r\ntests should be run as part of the build. It can be run with\r\n`pytest -q test`.\r\n\r\n## License\r\n\r\norjson was written by ijl <<ijl@mailbox.org>>, copyright 2018 - 2024, available\r\nto you under either the Apache 2 license or MIT license at your choice.\r\n\n",
"bugtrack_url": null,
"license": "Apache-2.0 OR MIT",
"summary": "Fast, correct Python JSON library supporting dataclasses, datetimes, and numpy",
"version": "3.10.11",
"project_urls": {
"Changelog": "https://github.com/ijl/orjson/blob/master/CHANGELOG.md",
"Documentation": "https://github.com/ijl/orjson",
"Homepage": "https://github.com/ijl/orjson"
},
"split_keywords": [
"fast",
" json",
" dataclass",
" dataclasses",
" datetime",
" rfc",
" 8259",
" 3339"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "bb29ca24efe043501b4a4584d728fdc65af5cfc070ab9021a07fb195bce98919",
"md5": "f6de86545a8d6269b5b16ed4ad4f5529",
"sha256": "1789d9db7968d805f3d94aae2c25d04014aae3a2fa65b1443117cd462c6da647"
},
"downloads": -1,
"filename": "orjson-3.10.11-cp310-none-win32.whl",
"has_sig": false,
"md5_digest": "f6de86545a8d6269b5b16ed4ad4f5529",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.8",
"size": 144456,
"upload_time": "2024-11-01T23:52:30",
"upload_time_iso_8601": "2024-11-01T23:52:30.448806Z",
"url": "https://files.pythonhosted.org/packages/bb/29/ca24efe043501b4a4584d728fdc65af5cfc070ab9021a07fb195bce98919/orjson-3.10.11-cp310-none-win32.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b7ecf15dc012928459cfb96ed86178d92fddb5c01847f2c53fd8be2fa62dee6c",
"md5": "844cf55a0836d456d350d9aa6b12d423",
"sha256": "5576b1e5a53a5ba8f8df81872bb0878a112b3ebb1d392155f00f54dd86c83ff6"
},
"downloads": -1,
"filename": "orjson-3.10.11-cp310-none-win_amd64.whl",
"has_sig": false,
"md5_digest": "844cf55a0836d456d350d9aa6b12d423",
"packagetype": "bdist_wheel",
"python_version": "cp310",
"requires_python": ">=3.8",
"size": 136442,
"upload_time": "2024-11-01T23:48:29",
"upload_time_iso_8601": "2024-11-01T23:48:29.318238Z",
"url": "https://files.pythonhosted.org/packages/b7/ec/f15dc012928459cfb96ed86178d92fddb5c01847f2c53fd8be2fa62dee6c/orjson-3.10.11-cp310-none-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2cc9710286a60b14e88288ca014d43befb08bb0a4a6a0f51b875f8c2f05e8205",
"md5": "0b2ee162d54106a4127d25af19041fbf",
"sha256": "a11225d7b30468dcb099498296ffac36b4673a8398ca30fdaec1e6c20df6aa55"
},
"downloads": -1,
"filename": "orjson-3.10.11-cp311-none-win32.whl",
"has_sig": false,
"md5_digest": "0b2ee162d54106a4127d25af19041fbf",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.8",
"size": 144459,
"upload_time": "2024-11-01T23:53:20",
"upload_time_iso_8601": "2024-11-01T23:53:20.741418Z",
"url": "https://files.pythonhosted.org/packages/2c/c9/710286a60b14e88288ca014d43befb08bb0a4a6a0f51b875f8c2f05e8205/orjson-3.10.11-cp311-none-win32.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7d68ef7b920e0a09e02b1a30daca1b4864938463797995c2fabe457c1500220a",
"md5": "ed34766b7ce46cd6017d2fe99e234d99",
"sha256": "df8c677df2f9f385fcc85ab859704045fa88d4668bc9991a527c86e710392bec"
},
"downloads": -1,
"filename": "orjson-3.10.11-cp311-none-win_amd64.whl",
"has_sig": false,
"md5_digest": "ed34766b7ce46cd6017d2fe99e234d99",
"packagetype": "bdist_wheel",
"python_version": "cp311",
"requires_python": ">=3.8",
"size": 136444,
"upload_time": "2024-11-01T23:49:41",
"upload_time_iso_8601": "2024-11-01T23:49:41.176834Z",
"url": "https://files.pythonhosted.org/packages/7d/68/ef7b920e0a09e02b1a30daca1b4864938463797995c2fabe457c1500220a/orjson-3.10.11-cp311-none-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2cf5d835fee01a0284d4b78effc24d16e7609daac2ff6b6851ca1bdd3b6194fc",
"md5": "e9be46526e8167aa530d6206dade72c7",
"sha256": "d4a62c49c506d4d73f59514986cadebb7e8d186ad510c518f439176cf8d5359d"
},
"downloads": -1,
"filename": "orjson-3.10.11-cp312-none-win32.whl",
"has_sig": false,
"md5_digest": "e9be46526e8167aa530d6206dade72c7",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.8",
"size": 144489,
"upload_time": "2024-11-01T23:53:46",
"upload_time_iso_8601": "2024-11-01T23:53:46.441694Z",
"url": "https://files.pythonhosted.org/packages/2c/f5/d835fee01a0284d4b78effc24d16e7609daac2ff6b6851ca1bdd3b6194fc/orjson-3.10.11-cp312-none-win32.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0360748e0e205060dec74328dfd835e47902eb5522ae011766da76bfff64e2f4",
"md5": "49b6e0297fc047c91d268eee35819c1d",
"sha256": "f1eec3421a558ff7a9b010a6c7effcfa0ade65327a71bb9b02a1c3b77a247284"
},
"downloads": -1,
"filename": "orjson-3.10.11-cp312-none-win_amd64.whl",
"has_sig": false,
"md5_digest": "49b6e0297fc047c91d268eee35819c1d",
"packagetype": "bdist_wheel",
"python_version": "cp312",
"requires_python": ">=3.8",
"size": 136614,
"upload_time": "2024-11-01T23:49:52",
"upload_time_iso_8601": "2024-11-01T23:49:52.212716Z",
"url": "https://files.pythonhosted.org/packages/03/60/748e0e205060dec74328dfd835e47902eb5522ae011766da76bfff64e2f4/orjson-3.10.11-cp312-none-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a497d904e26c1cabf2dd6ab1b0909e9b790af28a7f0fcb9d8378d7320d4869eb",
"md5": "0337281768542c56378056075b1758a8",
"sha256": "1a1222ffcee8a09476bbdd5d4f6f33d06d0d6642df2a3d78b7a195ca880d669b"
},
"downloads": -1,
"filename": "orjson-3.10.11-cp313-none-win32.whl",
"has_sig": false,
"md5_digest": "0337281768542c56378056075b1758a8",
"packagetype": "bdist_wheel",
"python_version": "cp313",
"requires_python": ">=3.8",
"size": 144486,
"upload_time": "2024-11-01T23:49:49",
"upload_time_iso_8601": "2024-11-01T23:49:49.921464Z",
"url": "https://files.pythonhosted.org/packages/a4/97/d904e26c1cabf2dd6ab1b0909e9b790af28a7f0fcb9d8378d7320d4869eb/orjson-3.10.11-cp313-none-win32.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "42623760bd1e6e949321d99bab238d08db2b1266564d2f708af668f57109bb36",
"md5": "c099d0a74840e246c603f4295127c800",
"sha256": "bc274ac261cc69260913b2d1610760e55d3c0801bb3457ba7b9004420b6b4270"
},
"downloads": -1,
"filename": "orjson-3.10.11-cp313-none-win_amd64.whl",
"has_sig": false,
"md5_digest": "c099d0a74840e246c603f4295127c800",
"packagetype": "bdist_wheel",
"python_version": "cp313",
"requires_python": ">=3.8",
"size": 136361,
"upload_time": "2024-11-01T23:49:49",
"upload_time_iso_8601": "2024-11-01T23:49:49.874808Z",
"url": "https://files.pythonhosted.org/packages/42/62/3760bd1e6e949321d99bab238d08db2b1266564d2f708af668f57109bb36/orjson-3.10.11-cp313-none-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "43c07676ecbb49451c3e510eb3c3bb5927353183d0ffa7cdb1c52cc3309f663f",
"md5": "309558fc1ac32d34f47a3fff2717d272",
"sha256": "b9546b278c9fb5d45380f4809e11b4dd9844ca7aaf1134024503e134ed226161"
},
"downloads": -1,
"filename": "orjson-3.10.11-cp38-none-win32.whl",
"has_sig": false,
"md5_digest": "309558fc1ac32d34f47a3fff2717d272",
"packagetype": "bdist_wheel",
"python_version": "cp38",
"requires_python": ">=3.8",
"size": 144244,
"upload_time": "2024-11-01T23:53:00",
"upload_time_iso_8601": "2024-11-01T23:53:00.304118Z",
"url": "https://files.pythonhosted.org/packages/43/c0/7676ecbb49451c3e510eb3c3bb5927353183d0ffa7cdb1c52cc3309f663f/orjson-3.10.11-cp38-none-win32.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a8d6eeba8cf9d276b7d341e9858a2c9fe23acc0c0758a8b0d1af09493355cf6e",
"md5": "7a4726d84b712ff4cef990856d80d455",
"sha256": "b592597fe551d518f42c5a2eb07422eb475aa8cfdc8c51e6da7054b836b26782"
},
"downloads": -1,
"filename": "orjson-3.10.11-cp38-none-win_amd64.whl",
"has_sig": false,
"md5_digest": "7a4726d84b712ff4cef990856d80d455",
"packagetype": "bdist_wheel",
"python_version": "cp38",
"requires_python": ">=3.8",
"size": 136149,
"upload_time": "2024-11-01T23:48:56",
"upload_time_iso_8601": "2024-11-01T23:48:56.665941Z",
"url": "https://files.pythonhosted.org/packages/a8/d6/eeba8cf9d276b7d341e9858a2c9fe23acc0c0758a8b0d1af09493355cf6e/orjson-3.10.11-cp38-none-win_amd64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "db66a61cb47eaf4b8afe10907e465d4e38f61f6e694fc982f01261b0020be8ed",
"md5": "d83e4e24474947e833bab1d72eee181d",
"sha256": "9fd0ad1c129bc9beb1154c2655f177620b5beaf9a11e0d10bac63ef3fce96950"
},
"downloads": -1,
"filename": "orjson-3.10.11-cp39-none-win32.whl",
"has_sig": false,
"md5_digest": "d83e4e24474947e833bab1d72eee181d",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.8",
"size": 144301,
"upload_time": "2024-11-01T23:53:17",
"upload_time_iso_8601": "2024-11-01T23:53:17.369173Z",
"url": "https://files.pythonhosted.org/packages/db/66/a61cb47eaf4b8afe10907e465d4e38f61f6e694fc982f01261b0020be8ed/orjson-3.10.11-cp39-none-win32.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cb0869b1ce42bb7ee604e23270cf46514ea775265960f3fa4b246e1f8bfde081",
"md5": "e6df279bbe553330e5fdb893d47f614a",
"sha256": "10f416b2a017c8bd17f325fb9dee1fb5cdd7a54e814284896b7c3f2763faa017"
},
"downloads": -1,
"filename": "orjson-3.10.11-cp39-none-win_amd64.whl",
"has_sig": false,
"md5_digest": "e6df279bbe553330e5fdb893d47f614a",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": ">=3.8",
"size": 136263,
"upload_time": "2024-11-01T23:51:42",
"upload_time_iso_8601": "2024-11-01T23:51:42.694550Z",
"url": "https://files.pythonhosted.org/packages/cb/08/69b1ce42bb7ee604e23270cf46514ea775265960f3fa4b246e1f8bfde081/orjson-3.10.11-cp39-none-win_amd64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-01 23:52:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ijl",
"github_project": "orjson",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "orjson"
}
JSON
