Using Jyson for decoding json documents¶

• Table of contents
• Using Jyson for decoding json documents
  • API compatibility with the cpython json module.
  • Usage
  • Strings passed to jyson must not be byte-encoded
  • JSON data object types supported
    • JSON null
    • JSON true and false.
    • JSON integers.
    • JSON floats
    • JSON strings
    • JSON objects
    • JSON arrays
  • Options for controlling the decoding process.

API compatibility with the cpython json module.¶

When I originally wrote jyson, I devised my own api, to make it suitable for usage both from jython and from java. However, as discussed on the wiki front page, I have decided that it is better for jyson to use the same API as the cpython json module .

Therefore, I have changed the jyson API to be closer to the json module API, a process that is not yet complete. However, the API can be made the same at a higher level, by using it like this (assuming that you have placed the jyson.jar file on your classpath)

>>> from com.xhaus.jyson import JysonCodec as json
>>> json.loads('["Hello World!"]')
['Hello World!']

Usage¶

To decode JSON text into jython objects, simply pass the JSON data to the loads method, like so

>>> from com.xhaus.jyson import JysonCodec as json
>>> json.loads('{"Hello":"World"}')
{'Hello': 'World'}
>>> json.loads('[1,1.1,null,"Hello World"]')
[1, 1.1, None, 'Hello World']
>>>

Strings passed to jyson must not be byte-encoded¶

Note that the string that is passed to the decode method must be a jython string or java.lang.String that is not byte encoded. If you wish to decode a string that is byte encoded, then you should decode it yourself first before passing it to the method. The following code illustrates

>>> from com.xhaus.jyson import JysonCodec as json
>>> utf8_json_data = '["Al\xc3\xa1in"]'
>>> decoded_json_data = utf8_json_data.decode('utf-8')
>>> decoded_json_data
u'["Al\xe1in"]'
>>> json.loads(decoded_json_data)
['Al\xe1in']
>>>

JSON data object types supported¶

Jyson includes builtin support for all JSON data types.

JSON null¶

The JSON constant null is decoded as a jython None (specifically, the jython singleton object Py.None which is of type org.python.core.PyObject).

>>> from com.xhaus.jyson import JysonCodec as json
>>> json.loads('[null]')
[None]
>>>

JSON true and false.¶

The JSON constants true and false are decoded as jython True and False respectively (specifically as the jython singleton objects Py.True and Py.False respectively).

>>> from com.xhaus.jyson import JysonCodec as json
>>> json.loads('[true,false]')
[True, False]
>>>

JSON integers.¶

JSON integers are decoded as either a jython int (org.python.core.PyInteger) or long (org.python.core.PyLong)

>>> from com.xhaus.jyson import JysonCodec as json
>>> json.loads('[42]')
[42]
>>>

If an JSON integer is greater than the maximum value representable by a jython integer, then it will instead be returned as a jython long. The following illustrates

>>> import sys
>>> json_ints = "[%d,%d]" % (sys.maxint, sys.maxint+1)
>>> json_ints
'[2147483647,2147483648]'
>>> json.loads(json_ints)
[2147483647, 2147483648L]
>>>

JSON floats¶

JSON floats are decoded as jython float (org.python.core.PyFloat)

>>> from com.xhaus.jyson import JysonCodec as json
>>> json.loads('[42.0]')
[42.0]
>>>

JSON strings¶

JSON strings are decoded as jython strings (org.python.core.PyString)

>>> from com.xhaus.jyson import JysonCodec as json
>>> json.loads('["Hello World!"]')
['Hello World!']
>>>

JSON objects¶

JSON objects are decoded as jython dictionaries (org.python.core.PyStringMap)

>>> from com.xhaus.jyson import JysonCodec as json
>>> json.loads('{"hello": 1, "world": 2.0}')
{'world': 2.0, 'hello': 1}
>>>

NOTE Only objects with string keys can be decoded, as according to the JSON spec. Any attempt to decode an object with a non-string key will cause a JSONDecodeError. The values in an object can be any JSON type, including arrays and objects.

JSON arrays¶

JSON arrays are decoded as jython lists (org.python.core.PyList)

>>> from com.xhaus.jyson import JysonCodec as json
>>> json.loads('[1, 42, "Hello world!"]')
[1, 42, 'Hello world!']
>>>

Array elements may be of any JSON type, including arrays and objects.

Options for controlling the decoding process.¶

There are various options that you can use to control the way that the jyson decoder treats the JSON to be decoded.