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

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

digraph inheritance2fa95081c8 { bgcolor=transparent; fontsize=32; rankdir=LR; size="6.0, 8.0"; "pyjson5.pyjson5.Json5DecoderException" [URL="#pyjson5.Json5DecoderException",color=black,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="filled,solid",target="_top",tooltip="Json5DecoderException(message=None, result=None, *args)"]; "pyjson5.pyjson5.Json5Exception" -> "pyjson5.pyjson5.Json5DecoderException" [arrowsize=0.8,penwidth=1.2,style="setlinewidth(0.5)"]; "pyjson5.pyjson5.Json5EOF" [URL="#pyjson5.Json5EOF",color=black,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="filled,solid",target="_top",tooltip="The input ended prematurely."]; "pyjson5.pyjson5.Json5DecoderException" -> "pyjson5.pyjson5.Json5EOF" [arrowsize=0.8,penwidth=1.2,style="setlinewidth(0.5)"]; "pyjson5.pyjson5.Json5Exception" [URL="exceptions.html#pyjson5.Json5Exception",color=black,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="filled,solid",target="_top",tooltip="Json5Exception(message=None, *args)"]; "pyjson5.pyjson5.Json5ExtraData" [URL="#pyjson5.Json5ExtraData",color=black,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="filled,solid",target="_top",tooltip="Json5ExtraData(message=None, result=None, character=None, *args)"]; "pyjson5.pyjson5.Json5DecoderException" -> "pyjson5.pyjson5.Json5ExtraData" [arrowsize=0.8,penwidth=1.2,style="setlinewidth(0.5)"]; "pyjson5.pyjson5.Json5IllegalCharacter" [URL="#pyjson5.Json5IllegalCharacter",color=black,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="filled,solid",target="_top",tooltip="Json5IllegalCharacter(message=None, result=None, character=None, *args)"]; "pyjson5.pyjson5.Json5DecoderException" -> "pyjson5.pyjson5.Json5IllegalCharacter" [arrowsize=0.8,penwidth=1.2,style="setlinewidth(0.5)"]; "pyjson5.pyjson5.Json5IllegalType" [URL="#pyjson5.Json5IllegalType",color=black,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="filled,solid",target="_top",tooltip="Json5IllegalType(message=None, result=None, value=None, *args)"]; "pyjson5.pyjson5.Json5DecoderException" -> "pyjson5.pyjson5.Json5IllegalType" [arrowsize=0.8,penwidth=1.2,style="setlinewidth(0.5)"]; "pyjson5.pyjson5.Json5NestingTooDeep" [URL="#pyjson5.Json5NestingTooDeep",color=black,fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="filled,solid",target="_top",tooltip="The maximum nesting level on the input data was exceeded."]; "pyjson5.pyjson5.Json5DecoderException" -> "pyjson5.pyjson5.Json5NestingTooDeep" [arrowsize=0.8,penwidth=1.2,style="setlinewidth(0.5)"]; }

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

Base class of any exception thrown by the parser.

add_note()

Exception.add_note(note) – add a note to the exception

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.

exception pyjson5.Json5NestingTooDeep

The maximum nesting level on the input data was exceeded.

add_note()

Exception.add_note(note) – add a note to the exception

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.

exception pyjson5.Json5EOF

The input ended prematurely.

add_note()

Exception.add_note(note) – add a note to the exception

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.

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

An unexpected character was encountered.

add_note()

Exception.add_note(note) – add a note to the exception

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.

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

The input contained extranous data.

add_note()

Exception.add_note(note) – add a note to the exception

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.

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

The user supplied callback function returned illegal data.

add_note()

Exception.add_note(note) – add a note to the exception

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.