0
# Types-ujson
1

2
Type stubs for ujson - an ultra-fast JSON encoder and decoder for Python. This package provides type annotations that enable static type checking and IDE support when working with ujson's high-performance JSON serialization and deserialization functions.
3

4
## Package Information
5

6
- **Package Name**: types-ujson
7
- **Package Type**: pypi (Python type stubs)
8
- **Language**: Python
9
- **Installation**: `pip install types-ujson`
10

11
## Core Imports
12

13
```python
14
import ujson
15
```
16

17
Import specific functions:
18

19
```python
20
from ujson import encode, decode, dumps, loads, dump, load, __version__
21
```
22

23
## Basic Usage
24

25
```python
26
import ujson
27

28
# Basic encoding (Python object to JSON string)
29
data = {"name": "Alice", "age": 30, "city": "New York"}
30
json_string = ujson.encode(data)
31
print(json_string)  # {"name":"Alice","age":30,"city":"New York"}
32

33
# Basic decoding (JSON string to Python object)
34
json_text = '{"name":"Bob","age":25}'
35
python_obj = ujson.decode(json_text)
36
print(python_obj)  # {'name': 'Bob', 'age': 25}
37

38
# Using common aliases
39
json_string = ujson.dumps(data)  # Same as encode
40
python_obj = ujson.loads(json_text)  # Same as decode
41

42
# File operations
43
with open('data.json', 'w') as f:
44
    ujson.dump(data, f, indent=2)
45

46
with open('data.json', 'r') as f:
47
    loaded_data = ujson.load(f)
48
```
49

50
## Capabilities
51

52
### JSON Encoding Functions
53

54
Convert Python objects to JSON strings with various formatting options.
55

56
```python { .api }
57
def encode(
58
    obj: Any,
59
    ensure_ascii: bool = ...,
60
    double_precision: int = ...,
61
    encode_html_chars: bool = ...,
62
    escape_forward_slashes: bool = ...,
63
    sort_keys: bool = ...,
64
    indent: int = ...
65
) -> str:
66
    """
67
    Encode Python object to JSON string.
68
    
69
    Args:
70
        obj: Python object to encode (dict, list, str, int, float, bool, None)
71
        ensure_ascii: If True, escape non-ASCII characters (default: True)
72
        double_precision: Number of decimal places for floats (default: 9)
73
        encode_html_chars: If True, encode HTML characters like <>&" (default: False)
74
        escape_forward_slashes: If True, escape forward slashes (default: True)  
75
        sort_keys: If True, sort dictionary keys (default: False)
76
        indent: Indentation level for pretty printing (default: 0)
77
        
78
    Returns:
79
        JSON string representation of the object
80
    """
81

82
def dumps(
83
    obj: Any,
84
    ensure_ascii: bool = ...,
85
    double_precision: int = ...,
86
    encode_html_chars: bool = ...,
87
    escape_forward_slashes: bool = ...,
88
    sort_keys: bool = ...,
89
    indent: int = ...
90
) -> str:
91
    """
92
    Serialize Python object to JSON string. Alias for encode().
93
    
94
    Args:
95
        obj: Python object to serialize
96
        ensure_ascii: If True, escape non-ASCII characters
97
        double_precision: Number of decimal places for floats
98
        encode_html_chars: If True, encode HTML characters like <>&"
99
        escape_forward_slashes: If True, escape forward slashes
100
        sort_keys: If True, sort dictionary keys
101
        indent: Indentation level for pretty printing
102
        
103
    Returns:
104
        JSON string representation of the object
105
    """
106

107
def dump(
108
    obj: Any,
109
    fp: IO[str],
110
    ensure_ascii: bool = ...,
111
    double_precision: int = ...,
112
    encode_html_chars: bool = ...,
113
    escape_forward_slashes: bool = ...,
114
    sort_keys: bool = ...,
115
    indent: int = ...
116
) -> None:
117
    """
118
    Serialize Python object to JSON and write to file-like object.
119
    
120
    Args:
121
        obj: Python object to serialize
122
        fp: File-like object to write JSON to (must have write() method)
123
        ensure_ascii: If True, escape non-ASCII characters
124
        double_precision: Number of decimal places for floats
125
        encode_html_chars: If True, encode HTML characters like <>&"
126
        escape_forward_slashes: If True, escape forward slashes
127
        sort_keys: If True, sort dictionary keys
128
        indent: Indentation level for pretty printing
129
        
130
    Returns:
131
        None (writes to file)
132
    """
133
```
134

135
### JSON Decoding Functions
136

137
Parse JSON strings into Python objects with precision control.
138

139
```python { .api }
140
def decode(s: AnyStr, precise_float: bool = ...) -> Any:
141
    """
142
    Decode JSON string to Python object.
143
    
144
    Args:
145
        s: JSON string or bytes to decode
146
        precise_float: If True, use precise float parsing (default: False)
147
        
148
    Returns:
149
        Python object (dict, list, str, int, float, bool, or None)
150
    """
151

152
def loads(s: AnyStr, precise_float: bool = ...) -> Any:
153
    """
154
    Parse JSON string to Python object. Alias for decode().
155
    
156
    Args:
157
        s: JSON string or bytes to parse
158
        precise_float: If True, use precise float parsing
159
        
160
    Returns:
161
        Python object (dict, list, str, int, float, bool, or None)
162
    """
163

164
def load(fp: IO[AnyStr], precise_float: bool = ...) -> Any:
165
    """
166
    Deserialize JSON from file-like object to Python object.
167
    
168
    Args:
169
        fp: File-like object to read JSON from (must have read() method)
170
        precise_float: If True, use precise float parsing
171
        
172
    Returns:
173
        Python object (dict, list, str, int, float, bool, or None)
174
    """
175
```
176

177
### Version Information
178

179
Access the ujson library version.
180

181
```python { .api }
182
__version__: str
183
    """
184
    Version string of the ujson library.
185
    """
186
```
187

188
## Types
189

190
```python { .api }
191
from typing import IO, Any, AnyStr
192

193
# AnyStr represents either str or bytes
194
# Any represents any Python object type
195
# IO[str] represents file-like objects that work with strings
196
# IO[AnyStr] represents file-like objects that work with strings or bytes
197
```
198

199
## Usage Examples
200

201
### Encoding with Options
202

203
```python
204
import ujson
205

206
data = {
207
    "user": "Alice",
208
    "score": 95.7,
209
    "tags": ["python", "json", "fast"]
210
}
211

212
# Pretty-printed JSON with sorted keys
213
formatted = ujson.encode(data, indent=2, sort_keys=True)
214
print(formatted)
215

216
# Ensure ASCII encoding for non-ASCII characters
217
non_ascii_data = {"name": "José", "city": "São Paulo"}
218
ascii_json = ujson.encode(non_ascii_data, ensure_ascii=True)
219
print(ascii_json)  # {"name":"Jos\\u00e9","city":"S\\u00e3o Paulo"}
220

221
# Control float precision
222
float_data = {"pi": 3.141592653589793}
223
precise = ujson.encode(float_data, double_precision=15)
224
print(precise)  # {"pi":3.141592653589793}
225
```
226

227
### File Operations
228

229
```python
230
import ujson
231

232
# Write JSON to file
233
data = {"users": [{"name": "Alice", "id": 1}, {"name": "Bob", "id": 2}]}
234

235
with open("users.json", "w") as f:
236
    ujson.dump(data, f, indent=2)
237

238
# Read JSON from file  
239
with open("users.json", "r") as f:
240
    loaded_data = ujson.load(f)
241
    
242
print(loaded_data["users"][0]["name"])  # Alice
243
```
244

245
### Precise Float Handling
246

247
```python
248
import ujson
249

250
# Standard parsing
251
json_with_floats = '{"value": 0.1234567890123456789}'
252
standard = ujson.loads(json_with_floats)
253
print(standard["value"])  # 0.12345678901234568
254

255
# Precise float parsing
256
precise = ujson.loads(json_with_floats, precise_float=True)
257
print(precise["value"])  # 0.1234567890123456789
258
```