{"id":7329,"library":"jsonseq","title":"JSON Text Sequences (RFC 7464)","description":"jsonseq is a Python library that provides support for encoding and decoding JSON text sequences as defined by RFC 7464. This format is designed for streaming multiple JSON objects, each prefixed by an ASCII Record Separator (0x1E) and terminated by a Line Feed (0x0A). It's particularly useful for handling large or indefinite streams of JSON data incrementally. The current version is 1.0.0, with releases historically following an as-needed cadence.","status":"active","version":"1.0.0","language":"en","source_language":"en","source_url":"https://github.com/sgillies/jsonseq","tags":["json","rfc7464","streaming","serialization","deserialization","text-sequence"],"install":[{"cmd":"pip install jsonseq","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"symbol":"JSONSeqEncoder","correct":"from jsonseq.encode import JSONSeqEncoder"},{"symbol":"JSONSeqDecoder","correct":"from jsonseq.decode import JSONSeqDecoder"}],"quickstart":{"code":"import io\nfrom jsonseq.encode import JSONSeqEncoder\nfrom jsonseq.decode import JSONSeqDecoder\n\n# --- Encoding ---\ndata_to_encode = [\n    {'id': 1, 'name': 'Alice'},\n    {'id': 2, 'name': 'Bob', 'details': {'age': 30}},\n    {'id': 3, 'name': 'Charlie'}\n]\n\n# Encode to a BytesIO stream\noutput_buffer = io.BytesIO()\nencoder = JSONSeqEncoder(output_buffer)\nfor obj in data_to_encode:\n    encoder.encode(obj)\n\nencoded_bytes = output_buffer.getvalue()\nprint(\"Encoded JSONSeq:\")\nprint(encoded_bytes.decode('utf-8'))\n\n# --- Decoding ---\n# Simulate reading from the stream\ninput_buffer = io.BytesIO(encoded_bytes)\ndecoder = JSONSeqDecoder(input_buffer)\n\ndecoded_objects = []\nfor obj in decoder:\n    decoded_objects.append(obj)\n\nprint(\"\\nDecoded objects:\")\nfor obj in decoded_objects:\n    print(obj)\n","lang":"python","description":"This quickstart demonstrates how to encode a list of Python dictionaries into a JSON text sequence using `JSONSeqEncoder` and then decode it back into Python objects using `JSONSeqDecoder`. It uses `io.BytesIO` to simulate file or network streams."},"warnings":[{"fix":"Be aware of this leniency when interoperating with other systems. If strict adherence to the initial RS is required for output, manually prepend `b'\\x1e'` to the stream or first record if the library's default behavior doesn't include it. For decoding, be aware that sequences starting without an RS will still be processed.","message":"RFC 7464 specifies that each JSON text *must* be prefixed by an ASCII Record Separator (RS, 0x1E). However, the `jsonseq` Python library's `JSONSeqEncoder` makes the initial RS optional for encoding, and `JSONSeqDecoder` is lenient, accepting sequences that omit the very first RS. While convenient, strict interoperability with other RFC 7464 implementations might expect the first RS.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Wrap the iteration over the `JSONSeqDecoder` in a `try...except json.JSONDecodeError` block to catch and handle individual malformed JSON records gracefully. This allows your application to log errors and continue processing subsequent valid records in the stream.","message":"The RFC 7464 standard suggests that parsers 'SHOULD NOT abort when an octet string contains a malformed JSON text' but instead report the failure and continue. The `jsonseq` library's `JSONSeqDecoder` wraps `json.loads`, which will raise a `json.JSONDecodeError` upon encountering malformed JSON within the sequence. This will halt iteration rather than skipping the bad record and continuing.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure that the underlying stream (e.g., `io.TextIOWrapper` or a network socket) is opened or configured with `encoding='utf-8'`. When working with raw bytes streams, ensure any manual decoding operations (e.g., `bytes.decode()`) also specify `utf-8`.","message":"RFC 7464 explicitly states that all JSON text sequences must be encoded in UTF-8. While Python 3 generally handles Unicode well, incorrect handling of the underlying stream's encoding can lead to `UnicodeDecodeError`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure all JSON objects passed to `JSONSeqEncoder` are valid, or, when decoding, wrap the iteration over `JSONSeqDecoder` in a `try...except json.JSONDecodeError` block to catch and handle malformed records gracefully. Log the error details (line, column, char) to pinpoint the problematic data.","cause":"An individual JSON object within the sequence is syntactically malformed (e.g., missing quotes, commas, or incorrect primitive types).","error":"json.decoder.JSONDecodeError: Expecting value: line 1 column X (char Y)"},{"fix":"Verify the actual encoding of the source data. If it's not UTF-8 (e.g., Latin-1, Windows-1252), you'll need to decode the raw bytes stream with the correct encoding *before* passing it to `JSONSeqDecoder` or ensure the file/network stream is opened with the appropriate `encoding` parameter.","cause":"The input stream contains bytes that are not valid UTF-8, but the decoder is attempting to interpret them as such.","error":"UnicodeDecodeError: 'utf-8' codec can't decode byte 0xXX in position Y: invalid start byte"},{"fix":"This typically indicates an incomplete JSON object or a truncated stream. Ensure the entire JSON text sequence is available to the decoder. If reading from a file, verify the file is not truncated. When processing network streams, handle `EOFError` or ensure all expected data chunks are received.","cause":"The Python interpreter encountered the end of a file or stream prematurely while attempting to parse an incomplete JSON object, often due to truncation or an unexpected end of the input stream.","error":"SyntaxError: unexpected EOF while parsing"}]}