Description¶

A library that allows sax-like parsing of JSON. It is a thin wrapper around the yajl C library that aims to enable all yajl’s features. It uses ctypes to interface with yajl’s routines, and thus allows for using any yajl routine even if it isn’t explicitly wrapped in yajl-py. yajl-py aims to be as pythonic as possible and still be consistent with the general style of yajl itself. This can be seen by comparing yajl-py examples with the examples of yajl itself.

Installation¶

To install the latest version of yajl-py, run:

pip install yajl-py

For the development version you may visit yajl-py at github:

pip install git+https://github.com/pykler/yajl-py.git

Alternatives¶

Another python library that wraps yajl for python is py-yajl. py-yajl creates an alternative to the built in json.loads and json.dumps using yajl. On the other hand, yajl-py wraps only yajl’s functionality giving the user the flexibility of defining their callbacks and thus benifiting from yajl’s stream parsing.

Versioning¶

To maintain compatibility, yajl-py version numbering follows yajl’s version numbers, where releases of yajl-py are fully compatible with the same numbered releases of yajl. This document reflects yajl-py version 2.1.1.

Examples¶

Examples of how to use yajl-py quickly show how much slimmer the python versions are than their C counterparts. Each of the examples in that directory perform the same actions as the C versions. The code is layed out in a similar fashion to the C code such that one can follow the logic.

import sys
from yajl import *

# Sample callbacks, which output some debug info
# these are examples to show off the yajl parser
class ContentHandler(YajlContentHandler):
    def __init__(self):
        self.out = sys.stdout
    def yajl_null(self, ctx):
        self.out.write("null\n" )
    def yajl_boolean(self, ctx, boolVal):
        self.out.write("bool: %s\n" %('true' if boolVal else 'false'))
    def yajl_integer(self, ctx, integerVal):
        self.out.write("integer: %s\n" %integerVal)
    def yajl_double(self, ctx, doubleVal):
        self.out.write("double: %s\n" %doubleVal)
    def yajl_number(self, ctx, stringNum):
        ''' Since this is defined both integer and double callbacks are useless '''
        num = float(stringNum) if '.' in stringNum else int(stringNum)
        self.out.write("number: %s\n" %num)
    def yajl_string(self, ctx, stringVal):
        self.out.write("string: '%s'\n" %stringVal)
    def yajl_start_map(self, ctx):
        self.out.write("map open '{'\n")
    def yajl_map_key(self, ctx, stringVal):
        self.out.write("key: '%s'\n" %stringVal)
    def yajl_end_map(self, ctx):
        self.out.write("map close '}'\n")
    def yajl_start_array(self, ctx):
        self.out.write("array open '['\n")
    def yajl_end_array(self, ctx):
        self.out.write("array close ']'\n")

# Create the parser
parser = YajlParser(ContentHandler())
# Parse JSON from stdin
parser.parse()

from yajl import *

g = YajlGen(beautify=False)
g.yajl_gen_map_open()
g.yajl_gen_string("a")
g.yajl_gen_array_open()
g.yajl_gen_null()
g.yajl_gen_bool(True)
g.yajl_gen_integer(1)
g.yajl_gen_double(2.0)
g.yajl_gen_number(str(3))

g.yajl_gen_get_buf()
# [Out]: '{"a":[null,true,1,2,3'

g.yajl_gen_string("b")
g.yajl_gen_array_close()
g.yajl_gen_map_close()

g.yajl_gen_get_buf()
# [Out]: ',"b"]}'

Documentaion¶

yajl-py internally is divided in a similar way as yajl’s C api. However, for flexibility all the classes, methods and structures implemented in each of the submodules is directly available under the main yajl module. Therefore using yajl.yajl_parse.YajlParser is the same as using yajl.YajlParser and similarly yajl.yajl_gen.YajlGen is the same as using yajl.YajlGen. The shared object (dll in windows, and dylib for bsd/MacOSX) is accessible as yajl.yajl_common.yajl or simply yajl.yajl. Generally, you will not need to interact with the shared object directly, if this is the case then it is a short-comming of yajl-py.

The following links lead to documentation generated from the yajl-py docstrings: