jyson

h1. Using Jyson for encoding JSON objects.

{{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.dumps(["Hello World!"])

u'["Hello World!"]'

>>>

</pre>

h2. Usage

To encode a jython object into JSON, simply pass the object to the *dumps()* method, like so

<pre>

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

>>> my_object = {"hello": "world", "integer": 42, "float": 42.0}

>>> json.dumps(my_object)

u'{"float":42.0,"integer":42,"hello":"world"}'

>>>

</pre>

You will notice that, because of the syntactic similarities of python/jython and javascript, the JSON representation and jython representation of the object is the same (although the order of dictionary keys may be different).

h3. Encoding matters

The JSON string returned from the *dumps()* operation is a java.lang.String, i.e. *it is not byte encoded*. If you want for the string to be byte encoded, then you should do this encoding yourself. The following code sample achieves this

<pre>

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

>>> jython_object = [u"Hello W\u00f6rld"]

>>> json_data = json.dumps(jython_object)

>>> desired_character_encoding = 'utf-8'

>>> encoded_json_data = json_data.encode(desired_character_encoding)

>>> json_data

u'["Hello W\xf6rld"]'

>>> encoded_json_data

'["Hello W\xc3\xb6rld"]'

>>>

</pre>

h3. Emitting ASCII

Jyson has a single option whch controls the output character set of the encoding operation: *emit_ascii*. If this option is *true*, then all characters with a Unicode value above 127 will be encoded as Unicode escapes. If the option is *false*, then a standard java Unicode string will be returned. The default value for the *emit_ascii* option is *False*. The following illustrates the principle (assuming you run it on a terminal which will display Unicode character \u00e1 as an accented a (á)).

<pre>

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

>>> s = u"Al\u00e1in"

>>> json.dumps(s)

u'"Al\xe1in"'

>>> json.dumps(s, emit_ascii=True)

u'"Al\\u00E1in"'

>>>

</pre>

h2. Jython object types supported

Jyson includes builtin support for encoding the following jython types

|Type|Implementation type|Example|Notes|

|None|org.python.core.Py.None|None||

|True, False|org.python.core.Py.True, org.python.core.Py.False|True||

|int|org.python.core.PyInteger|42||

|long|org.python.core.PyLong|42L||

|float|org.python.core.PyFloat|42.0||

|str|org.python.core.PyString|"Hello World!"||

|dict|org.python.core.PyDictionary, org.python.core.PyStringMap|{"hello": 1, "world": 2}|Only dictionaries with string keys can be encoded, as according to the JSON spec. Any attempt to encode a dictionary with a non-string key will cause a JysonEncodeException. The values in a dictionary can be any JSON encodable type, including tuples, lists and dictionaries.|

|list|org.python.core.PyList|[1, 42, "Hello world!"]|List elements may be of any JSON encodable type, including tuples, lists and dictionaries|

|tuple|org.python.core.PyTuple|(1, 42, "Hello world!")|Tuple elements may be of any JSON encodable type, including tuples, lists and dictionaries|

h2. Encoding your own objects

If you wish to encode objects that include elements not contained in the above table, but are still representable in JSON, then you can control the JSON generation process by implementing a <pre>__json__()</pre> method on your objects. If you do so, then this method will be invoked at JSON generation time, and should return the JSON corresponding to your object. The return JSON text is not checked for correctness: that is your responsiblity. Here is some sample code.

<pre>

from com.xhaus.jyson import JysonCodec as json

class MyTestClass:

	def __init__(self):

		self.i = -1

		self.f = -2.0

		self.s = 'hi'

	def __json__(self):

		return """{"i":%d, "f":%lf, "s":"%s"}""" % (abs(self.i), abs(self.f), self.s.upper())

mtc = MyTestClass()

print json.dumps(mtc)

</pre>

Which outputs

<pre>

{"i":1, "f":2.000000, "s":"HI"}

</pre>