python-jsend 0.5

What is it?
============
a python jsend module.
compatable with jsend: http://labs.omniti.com/labs/jsend


Note:
============
(note: if there is a "README.rst" file, it's a softlink of "README")

Install:
============
pip install python-jsend

Or download the tarbal, decompress it, then run "python setup.py install"

Test:
==========
python setup.py test
note: it may show the warning messages like something below:

"test.pytest.py/_pytest.core:147: UserWarning: Module _pytest was already imported from test.pytest.py/_pytest, but /usr/local/lib/python2.6/dist-packages is being added to sys.path"

It does no harm, just ommit it.


Shortely: (borrowed from http://labs.omniti.com/labs/jsend)
=================================================================
"""
A basic JSend-compliant response is as simple as this:
{{{
{
status : "success",
data : {
"post" : { "id" : 1, "title" : "A blog post", "body" : "Some useful content" }
}
}
}}}

When setting up a JSON API, you'll have all kinds of different types of calls and responses. JSend separates responses into some basic types, and defines required and optional keys for each type:

||''Type''||''Description''||''Required Keys''||''Optional Keys''||
||success ||All went well, and (usually) some data was returned.||status, data||||
||fail ||There was a problem with the data submitted, or some pre-condition of the API call wasn't satisfied||status, data||||
||error ||An error occurred in processing the request, i.e. an exception was thrown||status, message||code, data||



| ''Type'' | ''Description'' | ''Required Keys'' | ''Optional Keys'' |
|----------+--------------------------------------------------------+-------------------+-------------------|
| success | All went well, and (usually) some data was returned. | status, data | |
| | | | |
| fail | There was a problem with the data submitted, | status, data | |
| | or some pre-condition of the API call wasn't satisfied | | |
| | | | |
| error | An error occurred in processing the request, | status, message | code, data |
| | i.e. an exception was thrown | | |

"""


changelog: (2012-07-16)
In pracmatical usage, code representing status is very import, so add 'code' key to "Required Keys"


| ''Type'' | ''Description'' | ''Required Keys'' | ''Optional Keys'' |
|----------+--------------------------------------------------------+--------------------+-------------------|
| success | All went well, and (usually) some data was returned. | status, code, data | |
| | | | |
| fail | There was a problem with the data submitted, | status, code, data | |
| | or some pre-condition of the API call wasn't satisfied | | |
| | | | |
| error | An error occurred in processing the request, | status, message | code, data |
| | i.e. an exception was thrown | | |


changelog: (2012-07-26)
In pracmatical usage, a key "message" for all responese is very convenient for development.
So add 'message' key to "Optional Keys" for type(success, fail)


| ''Type'' | ''Description'' | ''Required Keys'' | ''Optional Keys'' |
|----------+--------------------------------------------------------+--------------------+-------------------|
| success | All went well, and (usually) some data was returned. | status, code, data | message |
| | | | |
| fail | There was a problem with the data submitted, | status, code, data | message |
| | or some pre-condition of the API call wasn't satisfied | | |
| | | | |
| error | An error occurred in processing the request, | status, message | code, data |
| | i.e. an exception was thrown | | |




This module includes 3 classes:
==============================
RSuccess --> Result Success

RFail --> Result Fail

RError --> Result Error


Usage: (sample)
========================


In [1]: from jsend import RSuccess, RFail, RError # from jsend import *

In [2]: rs = RSuccess()

In [3]: rs
Out[3]: {'data': {}, 'status': 'success'}

In [4]: rs.data['post'] = {'username' : 'you', 'password' : 'pwd' }

In [5]: rs
Out[5]: {'data': {'post': {'password': 'pwd', 'username': 'you'}}, 'status': 'success'}

In [6]: rf = RFail()

In [7]: rf
Out[7]: {'data': {}, 'status': 'fail'}

In [8]: rf.data['why'] = 'You have entered the wrong number'

In [9]: rf
Out[9]: {'data': {'why': 'You have entered the wrong number'}, 'status': 'fail'}

In [10]: rr = RError

In [11]: rr
Out[11]: jsend.jsend.RError

In [12]: rr = RError()

In [13]: rr
Out[13]:
{'code': {},
'data': {},
'message': 'error occurres during processing',
'status': 'error'}

In [14]: rr.data['stack'] = 'stack overflows'

In [15]: rr.code['return_code'] = 1

In [16]: rr
Out[16]:
{'code': {'return_code': 1},
'data': {'stack': 'stack overflows'},
'message': 'error occurres during processing',
'status': 'error'}