jyson

h1. Using Jyson to decode 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 cpython json module API, a process that is [[JysonCompliance|not yet complete]] . However, you can use a limited subset of the cpython API, by importing jyson 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>

You might want to read this discussion of [[JysonCompliance#character_encoding|why jyson does not deal with character encodings]].

h2. Mappings to jython data types.

JSON documents consist of specific datatypes, which jyson maps to specific jython objects. The types to which they are mapped is described on a separate page: [[JysonDecodeMappings|jyson decode mappings]].

h2. Options to control the parsing process.

Jyson can operate in either *strict* mode, under which all JSON documents must strictly conform to the JSON specification, or in *permissive* mode, under which a variety of non-conformant (but useful) syntactical constructs are accepted. These options are described on a separate page [[JysonDecodeOptions|jyson decode options]].