0
# ndjson
1

2
A simple and familiar interface for handling NDJSON (Newline Delimited JSON) data in Python. This package exposes the same API as Python's built-in `json` and `pickle` packages, making it easy to integrate into existing codebases. It includes JSONEncoder and JSONDecoder classes for seamless integration with other libraries like requests, as well as reader and writer classes similar to the standard csv module for streaming NDJSON data.
3

4
## Package Information
5

6
- **Package Name**: ndjson  
7
- **Language**: Python
8
- **Installation**: `pip install ndjson`
9
- **Version**: 0.3.1
10
- **License**: GPL-3.0
11
- **Dependencies**: None (zero dependencies)
12
- **Python Version Support**: Python 2.7, 3.5-3.7
13

14
## Core Imports
15

16
```python
17
import ndjson
18
```
19

20
All public functions and classes are available directly from the main module:
21

22
```python
23
# Functions
24
from ndjson import load, loads, dump, dumps
25

26
# Classes  
27
from ndjson import reader, writer, Decoder, Encoder
28
```
29

30
## Basic Usage
31

32
```python
33
import ndjson
34

35
# Load from file-like objects
36
with open('data.ndjson') as f:
37
    data = ndjson.load(f)
38

39
# Convert to and from objects
40
text = ndjson.dumps(data)
41
data = ndjson.loads(text)
42

43
# Dump to file-like objects
44
with open('backup.ndjson', 'w') as f:
45
    ndjson.dump(items, f)
46

47
# Streaming processing with reader/writer classes
48
with open('./posts.ndjson') as f:
49
    reader = ndjson.reader(f)
50
    for post in reader:
51
        print(post)
52

53
# Writing items to a ndjson file
54
with open('./posts.ndjson', 'w') as f:
55
    writer = ndjson.writer(f, ensure_ascii=False)
56
    for post in posts:
57
        writer.writerow(post)
58
```
59

60
## Capabilities
61

62
### Core Functions
63

64
Standard json-like API for loading and dumping NDJSON data.
65

66
```python { .api }
67
def load(*args, **kwargs):
68
    """
69
    Load NDJSON from file-like object. Uses json.load() with ndjson.Decoder by default.
70
    
71
    Parameters:
72
    - *args: Arguments passed to json.load() (typically fp)
73
    - **kwargs: Keyword arguments passed to json.load() (cls defaults to ndjson.Decoder)
74
    
75
    Returns:
76
    List of parsed objects from each JSON line
77
    """
78

79
def loads(*args, **kwargs):
80
    """
81
    Load NDJSON from string. Uses json.loads() with ndjson.Decoder by default.
82
    
83
    Parameters:
84
    - *args: Arguments passed to json.loads() (typically s)
85
    - **kwargs: Keyword arguments passed to json.loads() (cls defaults to ndjson.Decoder)
86
    
87
    Returns:
88
    List of parsed objects from each JSON line
89
    """
90

91
def dump(obj, fp, cls=None, **kwargs):
92
    """
93
    Dump object to NDJSON file.
94
    
95
    Parameters:
96
    - obj: list/iterable of objects to serialize
97
    - fp: file-like object to write to
98
    - cls: JSONEncoder class to use (defaults to ndjson.Encoder if None)
99
    - **kwargs: additional arguments passed to encoder
100
    """
101

102
def dumps(*args, **kwargs):
103
    """
104
    Dump object to NDJSON string. Uses json.dumps() with ndjson.Encoder by default.
105
    
106
    Parameters:
107
    - *args: Arguments passed to json.dumps() (typically obj)
108
    - **kwargs: Keyword arguments passed to json.dumps() (cls defaults to ndjson.Encoder)
109
    
110
    Returns:
111
    String containing NDJSON text
112
    """
113
```
114

115
### Streaming Classes
116

117
CSV-like reader and writer classes for efficient streaming processing of NDJSON files.
118

119
```python { .api }
120
class reader:
121
    """
122
    CSV-like reader for streaming NDJSON input.
123
    
124
    Iterates over lines in a file-like object, parsing each JSON line.
125
    """
126
    
127
    def __init__(self, f, **kwargs):
128
        """
129
        Initialize reader with file-like object.
130
        
131
        Parameters:
132
        - f: file-like object containing NDJSON text
133
        - **kwargs: additional arguments passed to json.loads()
134
        """
135
    
136
    def __iter__(self):
137
        """Return iterator protocol support."""
138
    
139
    def __next__(self):
140
        """
141
        Get next JSON object from stream.
142
        
143
        Returns:
144
        Parsed object from next JSON line
145
        
146
        Raises:
147
        StopIteration: when end of file is reached
148
        """
149
    
150
    def next(self):
151
        """
152
        Python 2.7 compatibility wrapper for __next__().
153
        
154
        Returns:
155
        Parsed object from next JSON line
156
        
157
        Raises:
158
        StopIteration: when end of file is reached
159
        """
160

161
class writer:
162
    """
163
    CSV-like writer for streaming NDJSON output.
164
    
165
    Writes objects as JSON lines to a file-like object.
166
    """
167
    
168
    def __init__(self, f, **kwargs):
169
        """
170
        Initialize writer with file-like object.
171
        
172
        Parameters:
173
        - f: file-like object to write to
174
        - **kwargs: additional arguments passed to json.dumps()
175
        """
176
    
177
    def writerow(self, row):
178
        """
179
        Write single row as JSON line.
180
        
181
        Parameters:
182
        - row: object to serialize and write as JSON line
183
        """
184
```
185

186
### Codec Classes
187

188
JSONEncoder and JSONDecoder subclasses for integration with other libraries.
189

190
```python { .api }
191
class Decoder(json.JSONDecoder):
192
    """
193
    JSON decoder that handles NDJSON format.
194
    
195
    Converts NDJSON text (multiple JSON objects separated by newlines)
196
    into a list of Python objects.
197
    """
198
    
199
    def decode(self, s, *args, **kwargs):
200
        """
201
        Decode NDJSON string to list of objects.
202
        
203
        Parameters:
204
        - s: NDJSON string to decode
205
        - *args, **kwargs: additional arguments passed to parent decode()
206
        
207
        Returns:
208
        List of decoded objects from each JSON line
209
        """
210

211
class Encoder(json.JSONEncoder):
212
    """
213
    JSON encoder that outputs NDJSON format.
214
    
215
    Converts a list/iterable of Python objects into NDJSON text
216
    (multiple JSON objects separated by newlines).
217
    """
218
    
219
    def encode(self, obj, *args, **kwargs):
220
        """
221
        Encode list of objects to NDJSON string.
222
        
223
        Parameters:
224
        - obj: list/iterable of objects to encode
225
        - *args, **kwargs: additional arguments passed to parent encode()
226
        
227
        Returns:
228
        NDJSON string with objects separated by newlines
229
        """
230
```
231

232
## Integration Examples
233

234
### Using with requests
235

236
```python
237
import ndjson
238
import requests
239

240
# Use custom decoder class with requests
241
response = requests.get('https://example.com/api/data')
242
items = response.json(cls=ndjson.Decoder)
243
```
244

245
### Working with file-like objects
246

247
```python
248
import ndjson
249
from io import StringIO
250

251
# Works with StringIO and other file-like objects
252
data = ['{"name": "Alice"}', '{"name": "Bob"}']
253
ndjson_text = '\\n'.join(data)
254

255
# Load from StringIO
256
f = StringIO(ndjson_text)
257
objects = ndjson.load(f)
258

259
# Dump to StringIO
260
output = StringIO()
261
ndjson.dump(objects, output)
262
result = output.getvalue()
263
```
264

265
### Large file streaming
266

267
```python
268
import ndjson
269

270
# Memory-efficient processing of large NDJSON files
271
def process_large_file(filename):
272
    with open(filename) as f:
273
        reader = ndjson.reader(f)
274
        for item in reader:
275
            # Process each item individually without loading entire file
276
            yield process_item(item)
277

278
# Writing large datasets
279
def write_large_dataset(filename, data_generator):
280
    with open(filename, 'w') as f:
281
        writer = ndjson.writer(f)
282
        for item in data_generator:
283
            writer.writerow(item)
284
```