1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
|
Metadata-Version: 2.1
Name: ujson
Version: 5.10.0
Summary: Ultra fast JSON encoder and decoder for Python
Home-page: https://github.com/ultrajson/ultrajson
Download-URL: https://github.com/ultrajson/ultrajson
Author: Jonas Tarnstrom
Project-URL: Source, https://github.com/ultrajson/ultrajson
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: C
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
# UltraJSON
[](https://pypi.org/project/ujson)
[](https://pypi.org/project/ujson)
[](https://pypistats.org/packages/ujson)
[](https://github.com/ultrajson/ultrajson/actions)
[](https://codecov.io/gh/ultrajson/ultrajson)
[](https://zenodo.org/badge/latestdoi/1418941)
[](https://github.com/psf/black)
UltraJSON is an ultra fast JSON encoder and decoder written in pure C with bindings for
Python 3.8+.
Install with pip:
```sh
python -m pip install ujson
```
## Project status
> [!WARNING]
> UltraJSON's architecture is fundamentally ill-suited to making changes without
> risk of introducing new security vulnerabilities. As a result, this library
> has been put into a *maintenance-only* mode. Support for new Python versions
> will be added and critical bugs and security issues will still be
> fixed but all other changes will be rejected. Users are encouraged to migrate
> to [orjson](https://pypi.org/project/orjson/) which is both much faster and
> less likely to introduce a surprise buffer overflow vulnerability in the
> future.
## Usage
May be used as a drop in replacement for most other JSON parsers for Python:
```pycon
>>> import ujson
>>> ujson.dumps([{"key": "value"}, 81, True])
'[{"key":"value"},81,true]'
>>> ujson.loads("""[{"key": "value"}, 81, true]""")
[{'key': 'value'}, 81, True]
```
### Encoder options
#### encode_html_chars
Used to enable special encoding of "unsafe" HTML characters into safer Unicode
sequences. Default is `False`:
```pycon
>>> ujson.dumps("<script>John&Doe", encode_html_chars=True)
'"\\u003cscript\\u003eJohn\\u0026Doe"'
```
#### ensure_ascii
Limits output to ASCII and escapes all extended characters above 127. Default is `True`.
If your end format supports UTF-8, setting this option to false is highly recommended to
save space:
```pycon
>>> ujson.dumps("åäö")
'"\\u00e5\\u00e4\\u00f6"'
>>> ujson.dumps("åäö", ensure_ascii=False)
'"åäö"'
```
#### escape_forward_slashes
Controls whether forward slashes (`/`) are escaped. Default is `True`:
```pycon
>>> ujson.dumps("https://example.com")
'"https:\\/\\/example.com"'
>>> ujson.dumps("https://example.com", escape_forward_slashes=False)
'"https://example.com"'
```
#### indent
Controls whether indentation ("pretty output") is enabled. Default is `0` (disabled):
```pycon
>>> ujson.dumps({"foo": "bar"})
'{"foo":"bar"}'
>>> print(ujson.dumps({"foo": "bar"}, indent=4))
{
"foo":"bar"
}
```
## Benchmarks
*UltraJSON* calls/sec compared to other popular JSON parsers with performance gain
specified below each.
### Test machine
Linux 5.15.0-1037-azure x86_64 #44-Ubuntu SMP Thu Apr 20 13:19:31 UTC 2023
### Versions
- CPython 3.11.3 (main, Apr 6 2023, 07:55:46) [GCC 11.3.0]
- ujson : 5.7.1.dev26
- orjson : 3.9.0
- simplejson : 3.19.1
- json : 2.0.9
| | ujson | orjson | simplejson | json |
|-------------------------------------------------------------------------------|-----------:|-----------:|-----------:|-----------:|
| Array with 256 doubles | | | | |
| encode | 18,282 | 79,569 | 5,681 | 5,935 |
| decode | 28,765 | 93,283 | 13,844 | 13,367 |
| Array with 256 UTF-8 strings | | | | |
| encode | 3,457 | 26,437 | 3,630 | 3,653 |
| decode | 3,576 | 4,236 | 522 | 1,978 |
| Array with 256 strings | | | | |
| encode | 44,769 | 125,920 | 21,401 | 23,565 |
| decode | 28,518 | 75,043 | 41,496 | 42,221 |
| Medium complex object | | | | |
| encode | 11,672 | 47,659 | 3,913 | 5,729 |
| decode | 12,522 | 23,599 | 8,007 | 9,720 |
| Array with 256 True values | | | | |
| encode | 110,444 | 425,919 | 81,428 | 84,347 |
| decode | 203,430 | 318,193 | 146,867 | 156,249 |
| Array with 256 dict{string, int} pairs | | | | |
| encode | 14,170 | 72,514 | 3,050 | 7,079 |
| decode | 19,116 | 27,542 | 9,374 | 13,713 |
| Dict with 256 arrays with 256 dict{string, int} pairs | | | | |
| encode | 55 | 282 | 11 | 26 |
| decode | 48 | 53 | 27 | 34 |
| Dict with 256 arrays with 256 dict{string, int} pairs, outputting sorted keys | | | | |
| encode | 42 | | 8 | 27 |
| Complex object | | | | |
| encode | 462 | | 397 | 444 |
| decode | 480 | 618 | 177 | 310 |
Above metrics are in call/sec, larger is better.
## Build options
For those with particular needs, such as Linux distribution packagers, several
build options are provided in the form of environment variables.
### Debugging symbols
#### UJSON_BUILD_NO_STRIP
By default, debugging symbols are stripped on Linux platforms. Setting this
environment variable with a value of `1` or `True` disables this behavior.
### Using an external or system copy of the double-conversion library
These two environment variables are typically used together, something like:
```sh
export UJSON_BUILD_DC_INCLUDES='/usr/include/double-conversion'
export UJSON_BUILD_DC_LIBS='-ldouble-conversion'
```
Users planning to link against an external shared library should be aware of
the ABI-compatibility requirements this introduces when upgrading system
libraries or copying compiled wheels to other machines.
#### UJSON_BUILD_DC_INCLUDES
One or more directories, delimited by `os.pathsep` (same as the `PATH`
environment variable), in which to look for `double-conversion` header files;
the default is to use the bundled copy.
#### UJSON_BUILD_DC_LIBS
Compiler flags needed to link the `double-conversion` library; the default
is to use the bundled copy.
|
