PyJSON5

PyJSON5 is implemented in Cython to provide performance superior to pure-Python implementations.

Decoder Performance

When processing pure JSON data, pyjson5.decode performs at speeds comparable to the standard Python json module.

Encoder Performance

The encoder is optimized for producing XML-safe output. It ensures that the serialized data contains no chevrons (<>), ampersands (&), apostrophes ('), or control characters.

Key encoder behaviors:

• Pure JSON Compatibility: If the input contains no NaN or infinite values, the output is valid pure JSON.
• ASCII Output: Regardless of whether you use pyjson5.encode or pyjson5.encode_bytes, the output is always ASCII.
• XML Safety: The output is automatically escaped for XML safety, making it faster than a combination of json.dumps and xml.sax.saxutils.escape.

The pyjson5 serializer produces ASCII data specifically designed to be safe for use within HTML templates. It automatically encodes apostrophes ('), ampersands (&), greater-than (>), and less-than (<) signs as Unicode escaped sequences. This prevents common injection issues when embedding data in HTML attributes or scripts.

Note: Unless the input contains Infinity or NaN values, the output is guaranteed to be valid standard JSON (RFC 8259).

"<a onclick='alert(" + encode(data) + ")'>show message</a>"

Install the pyjson5 library using pip to enable JSON5 serialization and parsing in your Python project.

$ pip install pyjson5

The pyjson5.encode function returns ASCII data specifically designed to be safe for use within HTML templates. It automatically encodes apostrophes ('), ampersands (&), greater-than (>), and less-than (<) signs as Unicode escaped sequences. This prevents XSS or syntax errors when injecting JSON data into HTML attributes or script tags.

Note: The resulting output is valid JSON (RFC 8259) as long as the input does not contain Infinity or NaN values.

"<a onclick='alert(" + encode(data) + ")'>show message</a>"

Use pyjson5.decode to parse valid JSON5 1.0.0 and standard JSON data. This function is the primary entry point for converting JSON5 strings or data into Python objects. It supports all valid JSON5 syntax unless the nesting level is excessively high.

import pyjson5

data = pyjson5.decode('{\n  key: "value",\n  // comment\n}')

For standard JSON compatibility (rather than HTML-safe encoding), use the following functions:

• pyjson5.dumps(obj): Returns a JSON-compatible string.
• pyjson5.dump(obj, fp): Writes a JSON-compatible representation to a file-like object fp.

To generate JSON strings that are safe to embed directly into HTML attributes or templates, use the encode_*() functions. These functions encode apostrophes ('), ampersands (&), greater-than (>), and less-than (<) signs as unicode escaped sequences. This prevents XSS or syntax errors when injecting data into JavaScript contexts within HTML.

# Example of safe embedding in an HTML template
# "<a onclick='alert(" + encode(data) + ")'>show message</a>"

If you are migrating from the standard json module or require compatibility with standard JSON patterns, use these functions:

• pyjson5.load(fp): Reads JSON5 data from a file-like object fp.
• pyjson5.loads(s): Parses a JSON5 string s.

import pyjson5

# Parsing a string
data = pyjson5.loads('{\n  name: "example"\n}')

# Parsing from a file
with open('config.json5', 'r') as f:
    data = pyjson5.load(f)

PyJSON5 provides several ways to serialize data depending on your required output format (string, bytes, stream, or callback):

• pyjson5.encode(obj): Returns an ASCII string safe for HTML.
• pyjson5.encode_bytes(obj): Returns encoded bytes.
• pyjson5.encode_io(obj, io): Writes encoded data directly to an I/O stream.
• pyjson5.encode_callback(obj, callback): Uses a callback function for the encoding process.
• pyjson5.encode_noop(obj): A no-op encoder (typically used for testing or as a placeholder).

PyJSON5 provides specialized decoding functions depending on the input type:

• pyjson5.decode_latin1: Decodes data using the latin1 encoding.
• pyjson5.decode_buffer: Decodes from a buffer/bytes-like object.
• pyjson5.decode_callback: Decodes using a callback mechanism.
• pyjson5.decode_io: Decodes from an I/O stream (file-like object).