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_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 (unicode) – 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_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 1, 2, 4 to denote UCS1, USC2 or USC4 data. 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(...)

Return type:

object

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

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

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.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.