jyson

h1. Using Jyson for decoding json documents

{{toc}}

h2. 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":http://docs.python.org/library/json.html .

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)

<pre>

>>> from com.xhaus.jyson import JysonCodec as json

>>> json.loads('["Hello World!"]')

['Hello World!']

</pre>

h2. Usage

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

<pre>

>>> 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']

>>>

</pre>

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

<pre>

>>> 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']

>>>

</pre>

h2. JSON data object types supported

Jyson includes builtin support for all JSON data types.

h3. 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*).

<pre>

>>> from com.xhaus.jyson import JysonCodec as json

>>> json.loads('[null]')

[None]

>>>

</pre>

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

<pre>

>>> from com.xhaus.jyson import JysonCodec as json

>>> json.loads('[true,false]')

[True, False]

>>>

</pre>

h3. JSON integers.

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

<pre>

>>> from com.xhaus.jyson import JysonCodec as json

>>> json.loads('[42]')

[42]

>>>

</pre>

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

<pre>

>>> import sys

>>> json_ints = "[%d,%d]" % (sys.maxint, sys.maxint+1)

>>> json_ints

'[2147483647,2147483648]'

>>> json.loads(json_ints)

[2147483647, 2147483648L]

>>>

</pre>

h3. JSON floats

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

<pre>

>>> from com.xhaus.jyson import JysonCodec as json

>>> json.loads('[42.0]')

[42.0]

>>>

</pre>

h3. JSON strings

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

<pre>

>>> from com.xhaus.jyson import JysonCodec as json

>>> json.loads('["Hello World!"]')

['Hello World!']

>>>

</pre>

h3. JSON objects

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

<pre>

>>> from com.xhaus.jyson import JysonCodec as json

>>> json.loads('{"hello": 1, "world": 2.0}')

{'world': 2.0, 'hello': 1}

>>>

</pre>

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

h3. JSON arrays

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

<pre>

>>> from com.xhaus.jyson import JysonCodec as json

>>> json.loads('[1, 42, "Hello world!"]')

[1, 42, 'Hello world!']

>>>

</pre>

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

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