jyson

JysonDecoding » History » Revision 2

Revision 1 (Alan Kennedy, 2009-03-17 03:30 PM) → Revision 2/3 (Alan Kennedy, 2009-03-17 07:52 PM)

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

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

 h2. Mappings to jython JSON data object types supported 

 Jyson includes builtin support for all JSON data types. 

 h3. JSON documents consist null 

 The JSON constant *null* is decoded as a jython *None* (specifically, the jython singleton object *Py.None* which is of specific datatypes, which jyson maps to specific jython objects. 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 types to which they JSON constants *true* and *false* are mapped 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 described on greater than the maximum value representable by a separate page: [[JysonDecodeMappings|jyson 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 mappings]]. 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 to control for controlling the parsing decoding process. 

 Jyson There are various options that you can operate in either *strict* mode, under which all JSON documents must strictly conform use to control the way that the jyson decoder treats 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]]. to be decoded.