Serializer / Encoder¶

The serializer returns ASCII data that can safely be used in an HTML template. Apostrophes, ampersands, greater-than, and less-then signs are encoded as unicode escaped sequences. E.g. this snippet is safe for any and all input:

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

Unless the input contains infinite or NaN values, the result will be valid JSON data.

Quick Encoder Summary¶

`encode`(data, *[, options])	Serializes a Python object to a JSON5 compatible unicode string.
`encode_bytes`(data, *[, options])	Serializes a Python object to a JSON5 compatible bytes string.
`encode_callback`(data, cb[, supply_bytes, ...])	Serializes a Python object into a callback function.
`encode_io`(data, fp[, supply_bytes, options])	Serializes a Python object into a file-object.
`encode_noop`(data, *[, options])	Test if the input is serializable.
`dump`(obj, fp, **kw)	Serializes a Python object to a JSON5 compatible unicode string.
`dumps`(obj, **kw)	Serializes a Python object to a JSON5 compatible unicode string.
`Options`	Customizations for the `encoder_*(...)` function family.
`Json5EncoderException`	Base class of any exception thrown by the serializer.
`Json5UnstringifiableType`([message, ...])	The encoder was not able to stringify the input, or it was told not to by the supplied `Options`.

Full Encoder Description¶

pyjson5.encode(data, *, options=None, **options_kw)¶

Serializes a Python object to a JSON5 compatible unicode string.

encode(['Hello', 'world!']) == '["Hello","world!"]'

Parameters

data (object) – Python object to serialize.
options (Optional[Options]) – Extra options for the encoder. If options and options_kw are specified, then options.update(**options_kw) is used.
options_kw – See Option’s arguments.

Raises

Json5EncoderException – An exception occured while encoding.
TypeError – An argument had a wrong type.

Returns

Unless float('inf') or float('nan') is encountered, the result will be valid JSON data (as of RFC8259).

The result is always ASCII. All characters outside of the ASCII range are encoded.

The result safe to use in an HTML template, e.g. <a onclick='alert({{ encode(url) }})'>show message</a>. Apostrophes "'" are encoded as "\u0027", less-than, greater-than, and ampersand likewise.

Return type

str

pyjson5.encode_bytes(data, *, options=None, **options_kw)¶

Serializes a Python object to a JSON5 compatible bytes string.

encode_bytes(['Hello', 'world!']) == b'["Hello","world!"]'

Parameters

data (object) – see `encode(...) <pyjson5.encode_>`_
options (Optional[Options]) – see `encode(...) <pyjson5.encode_>`_
options_kw – see `encode(...) <pyjson5.encode_>`_

Raises

Json5EncoderException – An exception occured while encoding.
TypeError – An argument had a wrong type.

Returns

see `encode(...) <pyjson5.encode_>`_

Return type

bytes

pyjson5.encode_callback(data, cb, supply_bytes=False, *, options=None, **options_kw)¶

Serializes a Python object into a callback function.

The callback function cb gets called with single characters and strings until the input data is fully serialized.

encode_callback(['Hello', 'world!'], print)
#prints:
# [
# "
# Hello
# "
# ,
# "
# world!
# "
" ]

Parameters

data (object) – see `encode(...) <pyjson5.encode_>`_
cb (Callable[[Union[bytes|str]], None]) – A callback function. Depending on the truthyness of supply_bytes either bytes or str is supplied.
supply_bytes (bool) – Call cb(...) with a bytes argument if true, otherwise str.
options (Optional[Options]) – see `encode(...) <pyjson5.encode_>`_
options_kw – see `encode(...) <pyjson5.encode_>`_

Raises

Json5EncoderException – An exception occured while encoding.
TypeError – An argument had a wrong type.

Returns

The supplied argument cb.

Return type

Callable[[Union[bytes|str]], None]

pyjson5.encode_io(data, fp, supply_bytes=True, *, options=None, **options_kw)¶

Serializes a Python object into a file-object.

The return value of fp.write(...) is not checked. If fp is unbuffered, then the result will be garbage!

Parameters

data (object) – see `encode(...) <pyjson5.encode_>`_
fp (IOBase) – A file-like object to serialize into.
supply_bytes (bool) – Call fp.write(...) with a bytes argument if true, otherwise str.
options (Optional[Options]) – see `encode(...) <pyjson5.encode_>`_
options_kw – see `encode(...) <pyjson5.encode_>`_

Raises

Json5EncoderException – An exception occured while encoding.
TypeError – An argument had a wrong type.

Returns

The supplied argument fp.

Return type

IOBase

pyjson5.encode_noop(data, *, options=None, **options_kw)¶

Test if the input is serializable.

Most likely you want to serialize data directly, and catch exceptions instead of using this function!

encode_noop({47: 11}) == True
encode_noop({47: object()}) == False

Parameters

data (object) – see `encode(...) <pyjson5.encode_>`_
options (Optional[Options]) – see `encode(...) <pyjson5.encode_>`_
options_kw – see `encode(...) <pyjson5.encode_>`_

Returns

True iff data is serializable.

Return type

bool

class pyjson5.Options¶

Customizations for the encoder_*(...) function family.

Immutable. Use Options.update(**kw) to create a new Options instance.

Parameters

tojson (str|False|None) –
- str: A special method to call on objects to return a custom JSON encoded string. Must return ASCII data!
- False: No such member exists. (Default.)
- None: Use default.
posinfinity (str|False|None) –
- str: String to represent positive infinity. Must be ASCII.
- False: Throw an exception if float('+inf') is encountered.
- None: Use default: "Infinity".
neginfinity (str|False|None) –
- str: String to represent negative infinity. Must be ASCII.
- False: Throw an exception if float('-inf') is encountered.
- None: Use default: "-Infinity".
nan (str|False|None) –
- str: String to represent not-a-number. Must be ASCII.
- False: Throw an exception if float('NaN') is encountered.
- None: Use default: "NaN".
intformat (str|False|None) –
- str: Format string to use with int.
- False: Throw an exception if an int is encountered.
- None: Use default: "%d".
floatformat (str|False|None) –
- str: Format string to use with float.
- False: Throw an exception if a float is encountered.
- None: Use default: "%.6e".
decimalformat (str|False|None) –
- str: Format string to use with Decimal.
- False: Throw an exception if a Decimal is encountered.
- None: Use default: "%s".
mappingtypes (Iterable[type]|False|None) –
- Iterable[type]: Classes the should be encoded to objects. Must be iterable over their keys, and implement __getitem__.
- False: There are no objects. Any object will be encoded as list of key-value tuples.
- None: Use default: [collections.abc.Mapping].

decimalformat¶: The creation argument decimalformat. None if False was specified.

floatformat¶: The creation argument floatformat. None if False was specified.

intformat¶: The creation argument intformat. None if False was specified.

mappingtypes¶: The creation argument mappingtypes. () if False was specified.

nan¶: The creation argument nan. None if False was specified.

neginfinity¶: The creation argument neginfinity. None if False was specified.

posinfinity¶: The creation argument posinfinity. None if False was specified.

tojson¶: The creation argument tojson. None if False was specified.

update(self, **kw)¶: Creates a new Options instance by modifying some members.

Encoder Compatibility Functions¶

pyjson5.dump(obj, fp, **kw)¶

Serializes a Python object to a JSON5 compatible unicode string.

Use `encode_io(...) <pyjson5.encode_io_>`_ instead!

dump(obj, fp) == encode_io(obj, fp)

Parameters

obj (object) – Python object to serialize.
fp (IOBase) – A file-like object to serialize into.
kw – Silently ignored.

pyjson5.dumps(obj, **kw)¶

Serializes a Python object to a JSON5 compatible unicode string.

Use `encode(...) <pyjson5.encode_>`_ instead!

dumps(obj) == encode(obj)

Parameters

obj (object) – Python object to serialize.
kw – Silently ignored.

Returns

see encode(data)

Return type

unicode

Encoder Exceptions¶

Inheritance diagram of pyjson5.Json5Exception, pyjson5.Json5EncoderException, pyjson5.Json5UnstringifiableType

class pyjson5.Json5EncoderException¶

Base class of any exception thrown by the serializer.

message¶: Human readable error description

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class pyjson5.Json5UnstringifiableType(message=None, unstringifiable=None)¶

The encoder was not able to stringify the input, or it was told not to by the supplied Options.

message¶: Human readable error description

unstringifiable¶: The value that caused the problem.

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.