5 Ijson is an iterative JSON parser with a standard Python iterator interface.
11 All usage example will be using a JSON document describing geographical
17 {"name": "Paris", "type": "city", "info": { ... }},
18 {"name": "Thames", "type": "river", "info": { ... }},
22 {"name": "Texas", "type": "state", "info": { ... }},
28 Most common usage is having ijson yield native Python objects out of a JSON
29 stream located under a prefix. Here's how to process all European cities::
33 f = urlopen('http://.../')
34 objects = ijson.items(f, 'earth.europe.item')
35 cities = (o for o in objects if o['type'] == 'city')
37 do_something_with(city)
39 Sometimes when dealing with a particularly large JSON payload it may worth to
40 not even construct individual Python objects and react on individual events
41 immediately producing some result::
45 parser = ijson.parse(urlopen('http://.../'))
47 for prefix, event, value in parser:
48 if (prefix, event) == ('earth', 'map_key'):
49 stream.write('<%s>' % value)
51 elif prefix.endswith('.name'):
52 stream.write('<object name="%s"/>' % value)
53 elif (prefix, event) == ('earth.%s' % continent, 'end_map'):
54 stream.write('</%s>' % continent)
55 stream.write('</geo>')
61 Ijson provides several implementations of the actual parsing in the form of
62 backends located in ijson/backends:
64 - ``yajl2``: wrapper around `YAJL <http://lloyd.github.com/yajl/>`_ version 2.x
65 - ``yajl``: wrapper around `YAJL <http://lloyd.github.com/yajl/>`_ version 1.x
66 - ``python``: pure Python parser (good to use under PyPy)
68 You can import a specific backend and use it in the same way as the top level
71 import ijson.backends.python as ijson
73 for item in ijson.items(...):
76 Importing the top level library as ``import ijson`` tries to import all backends
77 in order, so it either finds an appropriate version of YAJL or falls back to the
78 Python backend if none is found.
84 Python parser in ijson is relatively simple thanks to `Douglas Crockford
85 <http://www.crockford.com/>`_ who invented a strict, easy to parse syntax.
87 The `YAJL <http://lloyd.github.com/yajl/>`_ library by `Lloyd Hilaiel
88 <http://lloyd.io/>`_ is the most popular and efficient way to parse JSON in an
91 Ijson was inspired by `yajl-py <http://pykler.github.com/yajl-py/>`_ wrapper by
92 `Hatem Nassrat <http://www.nassrat.ca/>`_. Though ijson borrows almost nothing
93 from the actual yajl-py code it was used as an example of integration with yajl