Parser / Decoder

All valid JSON5 1.0.0 and JSON data can be read, unless the nesting level is absurdly high.

Quick Decoder Summary

`decode`(data[, maxdepth, some])	Decodes JSON5 serialized data from an `str` object.
`decode_latin1`(data[, maxdepth, some])	Decodes JSON5 serialized data from a `bytes` object.
`decode_buffer`(obj[, maxdepth, some, wordlength])	Decodes JSON5 serialized data from an object that supports the buffer protocol, e.g.
`decode_callback`(cb[, maxdepth, some, args])	Decodes JSON5 serialized data by invoking a callback.
`decode_io`(fp[, maxdepth, some])	Decodes JSON5 serialized data from a file-like object.
`load`(fp, **kw)	Decodes JSON5 serialized data from a file-like object.
`loads`(s, *[, encoding])	Decodes JSON5 serialized data from a string.
`Json5DecoderException`([message, result])	Base class of any exception thrown by the parser.
`Json5NestingTooDeep`	The maximum nesting level on the input data was exceeded.
`Json5EOF`	The input ended prematurely.
`Json5IllegalCharacter`([message, result, ...])	An unexpected character was encountered.
`Json5ExtraData`([message, result, character])	The input contained extranous data.
`Json5IllegalType`([message, result, value])	The user supplied callback function returned illegal data.

Full Decoder Description

pyjson5.decode(data, maxdepth=None, some=False)

Decodes JSON5 serialized data from an str object.

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

Parameters

data (str) – JSON5 serialized data
maxdepth (Optional[int]) –
Maximum nesting level before are the parsing is aborted.
- If None is supplied, then the value of the global variable DEFAULT_MAX_NESTING_LEVEL is used instead.
- If the value is 0, then only literals are accepted, e.g. false, 47.11, or "string".
- If the value is negative, then the any nesting level is allowed until Python’s recursion limit is hit.
some (bool) – Allow trailing junk.

Raises

Json5DecoderException – An exception occured while decoding.
TypeError – An argument had a wrong type.

Returns

Deserialized data.

Return type

object

pyjson5.decode_latin1(data, maxdepth=None, some=False)

Decodes JSON5 serialized data from a bytes object.

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

Parameters

data (bytes) – JSON5 serialized data, encoded as Latin-1 or ASCII.
maxdepth (Optional[int]) – see decode(…)
some (bool) – see decode(…)

Raises

Json5DecoderException – An exception occured while decoding.
TypeError – An argument had a wrong type.

Returns

see decode(…)

Return type

object

pyjson5.decode_buffer(obj, maxdepth=None, some=False, wordlength=None)

Decodes JSON5 serialized data from an object that supports the buffer protocol, e.g. bytearray.

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

decode_buffer(obj) == ['Hello', 'world!']

Parameters

data (object) – JSON5 serialized data. The argument must support Python’s buffer protocol, i.e. memoryview(…) must work. The buffer must be contigious.
maxdepth (Optional[int]) – see decode(…)
some (bool) – see decode(…)
wordlength (Optional[int]) – Must be 0, 1, 2, 4 to denote UTF-8, UCS1, USC2 or USC4 data, resp. Surrogates are not supported. Decode the data to an str if need be. If None is supplied, then the buffer’s itemsize is used.

Raises

Json5DecoderException – An exception occured while decoding.
TypeError – An argument had a wrong type.
ValueError – The value of wordlength was invalid.

Returns

see decode(…)

Return type

object

pyjson5.decode_callback(cb, maxdepth=None, some=False, args=None)

Decodes JSON5 serialized data by invoking a callback.

cb = iter('["Hello","world!"]').__next__

decode_callback(cb) == ['Hello', 'world!']

Parameters

cb (Callable[Any, Union[str|bytes|bytearray|int|None]]) –
A function to get values from. The functions is called like cb(*args), and it returns:
- str, bytes, bytearray: len(…) == 0 denotes exhausted input. len(…) == 1 is the next character.
- int: < 0 denotes exhausted input. >= 0 is the ordinal value of the next character.
- None: input exhausted
maxdepth (Optional[int]) – see decode(…)
some (bool) – see decode(…)
args (Optional[Iterable[Any]]) – Arguments to call cb with.

Raises

Json5DecoderException – An exception occured while decoding.
TypeError – An argument had a wrong type.

Returns

see decode(…)

Return type

object

pyjson5.decode_io(fp, maxdepth=None, some=True)

Decodes JSON5 serialized data from a file-like object.

fp = io.StringIO("""
    ['Hello', /* TODO look into specs whom to greet */]
    'Wolrd' // FIXME: look for typos
""")

decode_io(fp) == ['Hello']
decode_io(fp) == 'Wolrd'

fp.seek(0)

decode_io(fp, some=False)
# raises Json5ExtraData('Extra data U+0027 near 56', ['Hello'], "'")

Parameters

fp (IOBase) – A file-like object to parse from.
maxdepth (Optional[int] = None) – see decode(…)
some (bool) – see decode(…)

Raises

Json5DecoderException – An exception occured while decoding.
TypeError – An argument had a wrong type.

Returns

see decode(…)

Return type

object

Decoder Compatibility Functions

pyjson5.load(fp, **kw)

Decodes JSON5 serialized data from a file-like object.

Use decode_io(…) instead!

load(fp) == decode_io(fp, None, False)

Parameters

fp (IOBase) – A file-like object to parse from.
kw – Silently ignored.

Returns

see decode_io(…)

Return type

str

pyjson5.loads(s, *, encoding='UTF-8', **kw)

Decodes JSON5 serialized data from a string.

Use decode(…) instead!

loads(s) == decode(s)

Parameters

s (object) – Unless the argument is an str, it gets decoded according to the parameter encoding.
encoding (str) – Codec to use if s is not an str.
kw – Silently ignored.

Returns

see decode(…)

Return type

object

Decoder Exceptions

Inheritance diagram of pyjson5.Json5DecoderException, pyjson5.Json5NestingTooDeep, pyjson5.Json5EOF, pyjson5.Json5IllegalCharacter, pyjson5.Json5ExtraData, pyjson5.Json5IllegalType

class pyjson5.Json5DecoderException(message=None, result=None, *args)

Base class of any exception thrown by the parser.

message: Human readable error description

result: Deserialized data up until now.

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

class pyjson5.Json5NestingTooDeep

The maximum nesting level on the input data was exceeded.

message: Human readable error description

result: Deserialized data up until now.

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

class pyjson5.Json5EOF

The input ended prematurely.

message: Human readable error description

result: Deserialized data up until now.

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

class pyjson5.Json5IllegalCharacter(message=None, result=None, character=None, *args)

An unexpected character was encountered.

character: Illegal character.

message: Human readable error description

result: Deserialized data up until now.

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

class pyjson5.Json5ExtraData(message=None, result=None, character=None, *args)

The input contained extranous data.

character: Extranous character.

message: Human readable error description

result: Deserialized data up until now.

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

class pyjson5.Json5IllegalType(message=None, result=None, value=None, *args)

The user supplied callback function returned illegal data.

message: Human readable error description

result: Deserialized data up until now.

value: Value that caused the problem.

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