Skip to main content
This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (pypi.python.org).
Help us improve Python packaging - Donate today!

Light-weight Python framework for building REST APIs.

Project Description

cleaREST

Light-weight Python framework for building REST APIs

  • WSGI
  • minimalistic
  • easy to use
  • advanced variables processing
  • automatic html documentation generation

URL Routing

is done by decorating your handling function with one of these decorators:

  • @GET
  • @POST

only one argument is required (url to handle) ie:

@GET("/my/awesome/url")
def my_function():
    ...

optionally you can specify successful http result status (default is HTTP_OK) ie:

@GET("/my/awesome/url", status=HTTP_CREATED)
def my_function():
    ...

list of status tuples:

  • HTTP_OK
  • HTTP_CREATED

Variables

  • GET variables from query string
  • POST variables can be send as:
  • application/x-www-form-urlencoded
  • multipart/form-data
  • application/json
  • url path variables (identifier inside curly brackets) ie:

    @GET("/my/awesome/url/{variable}")
    def my_function(variable):
        ...
    

Parsing

per parameter parsing function assigned as default value ie:

@GET("/my/awesome/url")
def my_function(myid=int):
    ...

optional parameter:

@GET("/my/awesome/url")
def my_function(myid=(int, 0)):
    ...

reduction multiple into one:

@GET("/my/awesome/url")
def my_function(user_id=lambda user, password: login):
    ...

Returning data

build-in support:

Class Content-type
str text/plain
dict application/json
minidom application/xml
etree application/xml

you can also register any custom data-type or override table above with:

register_content_type(type_, content_type, handler)

Errors

to return a http error raise one of these exceptions:

  • HttpBadRequest
  • HttpNotFound
  • HttpUnsupportedMediaType
  • HttpNotImplemented

ie:

@GET("/my/awesome/url")
def my_function(myid=int):
    if myid == -1:
         raise HttpNotFound()
    ...

HTML Documentation

when is url opened by web-browser html documentation is shown instead of actual function call.

  • “application/xhtml+xml” in accept http header
  • similar tags to sphinx/docutils
  • extra example tags: “:example:” and for response “:rexample”:

ie:

@GET("/my/api")
def my_function(a, b=int):
    """
    Describe your function here.

    :param str a: Describe a here.
    :param int b: Describe b here.
    :return: W/E you function returns.

    :example::

        GET /my/api?a=someting&b=42

    :rexample::

        {
            "something": "something"
            ...
        }
    """
    ...

“real app” example:

Examples:

GET Hello world:

from wsgiref.simple_server import make_server
from clearest import application, GET


@GET("/")
def hello():
    return "hello world!"

 httpd = make_server("", 8000, application)
 httpd.serve_forever()

Output:

curl localhost:8000

hello world!

POST var:

from wsgiref.simple_server import make_server
from clearest import application, POST


@POST("/")
def hello(what):
    return "hello {what}!".format(what=what)


httpd = make_server("", 8000, application)
httpd.serve_forever()

Output:

curl –data “what=world” localhost:8000

hello world!

Release History

Release History

This version
History Node

0.3.5

History Node

0.3.4

History Node

0.3.3

History Node

0.3.2

History Node

0.3.1

History Node

0.3.0

History Node

0.2.0

History Node

0.1.0

History Node

0.0.1

Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
cleaREST-0.3.5-py2.py3-none-any.whl (21.7 kB) Copy SHA256 Checksum SHA256 py2.py3 Wheel Jun 16, 2016
cleaREST-0.3.5.zip (23.9 kB) Copy SHA256 Checksum SHA256 Source Jun 16, 2016

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting