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=u'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¶: 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.