Friday, June 6, 2008

Announcing jsonpickle 0.0.2

jsonpickle, a python library for serializing Python objects to JSON, is now public. The unique feature of jsonpickle is that it will work on almost any existing builtin or custom object without modification. simplejson does include a mechanism for serializing objects by defining a '.default()' method, but this requires modification to the class. Additionally, Christopher Lenz's Python CouchDB wrapper, using the Schema class, allows a class to implement JSON safe fields. While powerful, it still requires an upfront effort and is unable to handle existing code.

Marc Stober proposed using an object's __dict__ to serialize an object. His approach forms the basic tenet of jsonpickle. jsonpickle, though, takes this approach to the extreme, allowing for a much more robust solution, including allowing embedded objects to be serialized.

jsonpickle is currently able to handle a wide-range of Python objects: new-style and old-style classes, dictionaries, lists, time_struct's, even Mark Pilgrim's Universal Feed Parser.


>>> import jsonpickle
>>> from jsonpickle.tests.classes import Thing


Create an object.

>>> obj = Thing('A String')
>>> print obj.name
A String


Use jsonpickle to transform the object into a JSON string

>>> pickled = jsonpickle.dumps(obj)
>>> print pickled
{"child": null, "__classname__": "Thing", "name": "A String", "__classmodule__": "jsonpickle.tests.classes"}


Use jsonpickle to recreate a Python object from a JSON string

>>> unpickled = jsonpickle.loads(pickled)
>>> print unpickled.name
A String


The new object has the same type and data, but essentially is now a copy of the original.

>>> obj == unpickled
False
>>> obj.name == unpickled.name
True
>>> type(obj) == type(unpickled)
True


If you will never need to load (regenerate the Python class from JSON), you can
pass in the keyword unpicklable=False to prevent extra information from being
added to JSON.

>>> oneway = jsonpickle.dumps(obj, unpicklable=False)
>>> print oneway
{"name": "A String", "child": null}


jsonpickle currently extends the functionality of simplejson (future releases may use a different library, such as cjson).

The package is available on PyPi (so you can get it via an 'easy_install jsonpickle'). Additionally, Google Code is hosting the binary distributions of the code (including a Windows installer).

Feel free to help out! We could use reports of what other modules work or do not work with jsonpickle. Submit bug reports. Hack the code (we are currently using Mercurial). Join the mailing list.

One warning: jsonpickle is still alpha level software. The code is tested, but bugs may exist. Additionally, we do not currently guarantee backwards-compatibility yet--so the json output may not be valid to jsonpickle in future releases.

Enjoy!

No comments: