chula.webservice – Webservice helper module

chula.webservice.expose(**kwargs)

Decorator for exposing a method as a web service. It takes a list of keyword arguments which are passed to the transport chula.webservice.Transport.encode() method for use with making decisions. This is best illustrated with a few examples:

Parameters:

• transport (str, default is JSON) – Desired transpoort
• x_header (bool, default is False) – Should json payload use the HTTP X-JSON header

Return type:

Decorator, see: PEP 318

Simple JSON web service method:

>>> from chula import webservice
>>> from chula.www.controller import base
>>>
>>> class Webservice(base.Controller):
...     @webservice.expose()
...     def simple_json(self):
...         return {'some':'payload'}
>>>

... Calling this webservice will look something like:

>>> import json, urllib2
>>> from chula.test.bat import PORT
>>>
>>> url = 'http://localhost:%s/webservice/simple_json' % PORT
>>> payload = json.loads(urllib2.urlopen(url).read())
>>> payload.keys()
[u'msg', u'exception', u'data', u'success']
>>> payload['success']
True
>>> payload['data']
{u'some': u'payload'}

... You can also call this method with some GET args:

>>> import json, urllib2
>>> from chula.test.bat import PORT
>>>
>>> url = 'http://localhost:%s/webservice/simple_json?indent=2' % PORT
>>> pretty_json = urllib2.urlopen(url).read()

A webservice that breaks, will always return valid payload:

>>> from chula import webservice
>>> from chula.www.controller import base
>>>
>>> class Webservice(base.Controller):
...     @webservice.expose()
...     def broken(self):
...         return 0 / 0
>>>

... Calling this webservice will look something like:

>>> import json, urllib2
>>> from chula.test.bat import PORT
>>>
>>> url = 'http://localhost:%s/webservice/broken' % PORT
>>> payload = json.loads(urllib2.urlopen(url).read())
>>> payload['success']
False
>>> payload['exception']
u'integer division or modulo by zero'

JSON web service method that uses the X-JSON HTTP header:

>>> from chula import webservice
>>> from chula.www.controller import base
>>>
>>> class Webservice(base.Controller):
...     @webservice.expose(x_header=True)
...     def xjson(self):
...         return {'some':'payload'}
>>>

... Calling this webservice will look something like:

>>> import json, urllib2
>>> from chula.test.bat import PORT
>>>
>>> url = 'http://localhost:%s/webservice/xjson' % PORT
>>> payload = json.loads(urllib2.urlopen(url).info().get('X-JSON'))
>>> payload.keys()
[u'msg', u'exception', u'data', u'success']
>>> payload['success']
True
>>> payload['data']
{u'some': u'payload'}

PICKLE web service method:

>>> from chula import webservice
>>> from chula.www.controller import base
>>>
>>> class Webservice(base.Controller):
...     @webservice.expose(transport='PICKLE')
...     def pickle(self):
...         return {'some':'payload'}
>>>

... Calling this webservice will look something like:

>>> import cPickle, urllib2
>>> from chula.test.bat import PORT
>>>
>>> url = 'http://localhost:%s/webservice/pickle' % PORT
>>> payload = cPickle.loads(urllib2.urlopen(url).read())
>>> payload.keys()
['msg', 'exception', 'data', 'success']
>>> payload['success']
True
>>> payload['data']
{'some': 'payload'}

Note

Using a cPickle transport will provide more “native” encoding. This method maintains the non unicode encoded string. Contrast this with the json transport which results in unicode encoded strings as a by product of json dumps/loads.

Note

It’s also true that while cPickle is not portable to non Python clients, it’s way faster, by orders of magnitude.

ASCII web service method:

>>> from chula import webservice
>>> from chula.www.controller import base
>>>
>>> class Foo(base.Controller):
...     @webservice.expose(transport='ASCII')
...     def foo(self):
...         return {'some':'payload'}
>>>

This isn’t super usefull, but say you the client is curl or something, this might actually be easiser to work with.

Note

Client’s can also specify the transport they want:

>>> import json, urllib2
>>> from chula.test.bat import PORT
>>>
>>> url = 'http://localhost:%s/webservice/pickle?transport=json' % PORT
>>> payload = json.loads(urllib2.urlopen(url).read())
>>> payload.keys()
[u'msg', u'exception', u'data', u'success']

Notice here that the webservice itself was configured to use the pickle transport, but the client specifically asked for json :)

Warning

The classes below are not intended for direct use. They are all intended to be used via the chula.webservice.expose() decorator.

Chula helper module for working with web services

class chula.webservice.JSON(controller)

Webservice that uses json as the transport layer

encode(**kwargs)

Encode the transport into a json string and return X-JSON

class chula.webservice.ASCII(controller)

Webservice that uses ascii as the transport layer

encode(**kwargs)

Encode the transport into an acii string

class chula.webservice.Transports

Bundle the transports in an object for use with getattr

class ASCII(controller)

Webservice that uses ascii as the transport layer

encode(**kwargs)

Encode the transport into an acii string

class Transports.JSON(controller)

Webservice that uses json as the transport layer

encode(**kwargs)

Encode the transport into a json string and return X-JSON

class Transports.PICKLE(controller)

Webservice that uses Python pickling as the transport layer

encode(**kwargs)

Encode the transport into a Python pickled string

class chula.webservice.Transport(controller)

Web service transport class designed to be subclassed to provide various means of encoding.

static __default__(controller, kwargs, arg, default)

Return a default value of the specified arg for use in the creation or calling of a webservice. This method allows the webservice usage to be controlled either at creation or runtime (kwargs, http args).

Parameters:

• kwargs – The collection of key=value arguments
• arg (String) – The specific argument to be used
• default – The default value

Type :

default: Boolean

The algorithm used is:

1. Fetch from HTTP GET variables
2. Fetch from HTTP POST variables
3. Fetch from kwargs passed in the decorated method
4. Use the default value set in the transport

Currently supported keyword arguments:

• x_header: Should the HTTP X-JSON header be used for payload

encode(**kwargs)

Each transport child class overloads this method to encode the supplied payload, into the appropriate transport encoding. For example when the transport is JSON, this method (defined in the subclass) will take the payload and json.dumps() it.