projects.mako.cc - github-barcamp-201407/blob - ijson-1.1/README.rst

   1 =====
   2 ijson
   3 =====
   4
   5 Ijson is an iterative JSON parser with a standard Python iterator interface.
   6
   7
   8 Usage
   9 =====
  10
  11 All usage example will be using a JSON document describing geographical
  12 objects::
  13
  14     {
  15       "earth": {
  16         "europe": [
  17           {"name": "Paris", "type": "city", "info": { ... }},
  18           {"name": "Thames", "type": "river", "info": { ... }},
  19           // ...
  20         ],
  21         "america": [
  22           {"name": "Texas", "type": "state", "info": { ... }},
  23           // ...
  24         ]
  25       }
  26     }
  27
  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::
  30
  31     import ijson
  32
  33     f = urlopen('http://.../')
  34     objects = ijson.items(f, 'earth.europe.item')
  35     cities = (o for o in objects if o['type'] == 'city')
  36     for city in cities:
  37         do_something_with(city)
  38
  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::
  42
  43     import ijson
  44
  45     parser = ijson.parse(urlopen('http://.../'))
  46     stream.write('<geo>')
  47     for prefix, event, value in parser:
  48         if (prefix, event) == ('earth', 'map_key'):
  49             stream.write('<%s>' % value)
  50             continent = 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>')
  56
  57
  58 Backends
  59 ========
  60
  61 Ijson provides several implementations of the actual parsing in the form of
  62 backends located in ijson/backends:
  63
  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)
  67
  68 You can import a specific backend and use it in the same way as the top level
  69 library::
  70
  71     import ijson.backends.python as ijson
  72
  73     for item in ijson.items(...):
  74         # ...
  75
  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.
  79
  80
  81 Acknowledgements
  82 ================
  83
  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.
  86
  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
  89 iterative fashion.
  90
  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
  94 using ctypes.