This package provides a lightweight wsgi framework for developing [JSON-RPC] (http://www.jsonrpc.org) services.
Levitas is designed to be simple to implement and extendable. It supports version 2 of the [JSON-RPC specification] (http://www.jsonrpc.org). Also it can serve javascript web applications like written in [pyjamas] (http://pyjs.org/) or in [rapydscript] (http://rapydscript.pyjeon.com/rapydscript), supports cookie handling, file uploading and more.
- python (>= 2.6)
- epydoc (optional)
- twisted web (optional)
cd src
python setup.py install
cd src
epydoc -v --html --debug --no-sourcecode --graph all --output=../api levitas
Install on local system:
- make install
Generate a deb package:
- make deb
Generate API documentation:
- make doc
Get rid of scratch and byte files:
- make clean
Levitas is configured in a settings file. The settings file is a Python module with variables. It must be inside PYTHONPATH. This is inspired by Django settings file.
Here is a complete settings module:
from levitas.middleware.jsonMiddleware import JSONMiddleware
from levitas.middleware.appMiddleware import AppMiddleware
from levitas.middleware.redirectMiddleware import RedirectMiddleware
from levitas.middleware.fileMiddleware import FileMiddleware
"""
A url definition is a tuple of three parts:
(r"/.*$", MiddlewareClass, {"arg": "value"})
1. regular expression of the request path.
2. Middleware class.
3. Arguments to instantiate the class.
"""
urls = [
# JSON-RPC service
(r"^/json/myservice", JSONMiddleware, {"service_class": MyService}),
# Site root for static files of your web application
(r"(?!/json/.*)^/.*$", AppMiddleware, {"path": "/path/to/app"}),
# Directory with static files
(r"^/path/to/files/(.*)", FileMiddleware, {"path": "/path/to/files"}),
# A redirect
(r"/oldpath", RedirectMiddleware, {"url": "/newpath", "permanent": True})
]
"""
Webserver.
"""
httpserver_address = ("127.0.0.1", 8080)
# httpserver_ssl = True
# httpserver_certfile = "/path/to/certfile"
# httpserver_keyfile = "/path/to/keyfile"
"""
Optional working directory of the wsgi application.
Default is the current working directory.
"""
# working_dir = "/path/to/working directory"
"""
Optional custom path to the favicon.
"""
# favicon = "/path/to/favicon.ico"
"""
Optional encoding settings. Default is utf-8.
"""
# encoding = "utf-8"
"""
Optional secret to sign cookies.
"""
# cookie_secret = "my_cookie_secret"
"""
Optional path for uploaded files. Default is a tempfile.
"""
# upload_path = "/path/to/upload/files"- The Content-Type can be 'text/json' or 'application/json' or 'text/json-rpc' or 'application/json-rpc'
- The Content-Length must be specified.
- The POST body contains the Object request specified in [section 4] (http://www.jsonrpc.org/specification).
- Response to a Post contains the Object response specified in [section 5] (http://www.jsonrpc.org/specification).
To deploy with [WSGI] (http://www.wsgi.org), an object named application in a Python module is needed:
import os
os.environ["LEVITAS_SETTINGS"] = "my_site.my_settings"
from levitas.handler import WSGIHandler
application = WSGIHandler()WSGI servers:
- [modwsgi for Apache] (http://code.google.com/p/modwsgi/)
- [uwsgi] (http://projects.unbit.it/uwsgi/)
Levitas webserver is based on twisted web.
levitas-httpd [OPTION] {start|stop|restart|foreground}
Options:
-h, --help show this help message and exit
-l LOGFILE, --logfile=LOGFILE
Path to logfile (optional)
-c LOGFILECOUNT, --logfilecount=LOGFILECOUNT
Count of old logfiles to be saved. (default: 0)
-v, --verbose
-s SETTINGS_MODULE, --settings=SETTINGS_MODULE
settings module (required)
-p PIDFILE, --pidfile=PIDFILE
pidfile
Example, if the settings module is a python module my_site/settings.py:
levitas-httpd -s my_site.settings -v foreground
Usage: C:\Python27\Scripts\levitas-httpd-service.py [OPTION] {start|stop|remove|install}
Options:
-h, --help show this help message and exit
-n NAME, --name=NAME Servicename (default: levitasServer)
-d DISPLAYNAME, --displayname=DISPLAYNAME
Displayname (default: Levitas Webserver)
-a, --stayalive Service will stop on logout if False (default: True)
-l LOGFILE, --logfile=LOGFILE
Path to logfile (optional)
-c LOGFILECOUNT, --logfilecount=LOGFILECOUNT
Count of old logfiles to be saved. (default: 0)
-v, --verbose
-s SETTINGS_MODULE, --settings=SETTINGS_MODULE
settings module (required)
Install levitas server as a windows service:
C:\Python27/Scripts\levitas-httpd-service.py -s my_site.settings -l C:\levitasserver.log -v install
Start the service:
C:\Python27/Scripts\levitas-httpd-service.py start
Here is a small example to show how to write and serve a JSON service.
Write a service myService.py:
from levitas.middleware.service import Service
class MyService(Service):
def getMessage(self):
# Return the message configured in service_attributes
return self.msg
def sendMessage(self, msg):
client = self.middleware.remote_host
return "Message from %s: %s" % (client, msg)
def _prepare(self):
"""
Method will be called after service class is instantiated.
"""
pass
def _complete(self):
"""
Method will be called after service method is finished.
"""
passWrite the settings file settings.py:
from levitas.middleware.jsonMiddleware import JSONMiddleware
from myService import MyService
urls = [
(r"^/json/myservice", JSONMiddleware, {"service_class": MyService,
"service_attributes":
{"msg": "Hello World!"}
}),
]
httpserver_address = ("127.0.0.1", 8080)Start the server:
levitas-httpd -s settings -v foreground
Test the service methods in a python console:
>>> import urllib2
>>> headers = {"Content-type": "application/json-rpc"}
>>> opener = urllib2.build_opener()
>>> url = "http://localhost:8080/json/myservice"
>>> data = '{"jsonrpc":"2.0","id":"ID01","method":"getMessage","params": []}'
>>> request = urllib2.Request(url, data=data, headers=headers)
>>> response = opener.open(request)
>>> print response.read()
>>> data = '{"jsonrpc":"2.0","id":"ID02","method":"sendMessage","params": ["Hello Server!"]}'
>>> request = urllib2.Request(url, data=data, headers=headers)
>>> response = opener.open(request)
>>> print response.read()