#### PATTERN | SERVER ##############################################################################

# -*- coding: utf-8 -*-

# Copyright (c) 2014 University of Antwerp, Belgium

# Copyright (c) 2014 St. Lucas University College of Art & Design, Antwerp.

# Author: Tom De Smedt <tom@organisms.be>

# License: BSD (see LICENSE.txt for details).

####################################################################################################

from __future__ import with_statement

import __main__

import sys

import os

import re

import time; _time=time

import atexit

import urllib

import hashlib

import base64

import random

import string

import textwrap

import types

import inspect

import threading

import subprocess

import tempfile

import itertools

import collections

import sqlite3 as sqlite

try: # Python 2.x vs 3.x

import htmlentitydefs

except:

from html import entities as htmlentitydefs

try: # Python 2.x vs 3.x

from cStringIO import StringIO

except:

from io import BytesIO as StringIO

try: # Python 2.x vs 3.x

import cPickle as pickle

except:

import pickle

try:

# Folder that contains pattern.server.

MODULE = os.path.dirname(os.path.realpath(__file__))

except:

MODULE = ""

try:

# Folder that contains the script that (indirectly) imports pattern.server.

# This is used as the default App.path.

f = inspect.currentframe()

f = inspect.getouterframes(f)[-1][0]

f = f.f_globals["__file__"]

SCRIPT = os.path.dirname(os.path.abspath(f))

except:

SCRIPT = os.getcwd()

try:

# Import from python2.x/site-packages/cherrypy

import cherrypy; cp=cherrypy

except:

# Import from pattern/server/cherrypy/cherrypy

# Bundled package is "hidden" in a non-package folder,

# otherwise it conflicts with site-packages/cherrypy.

sys.path.insert(0, os.path.join(MODULE, "cherrypy"))

import cherrypy; cp=cherrypy

try: import json # Python 2.6+

except:

try: from pattern.web import json # simplejson

except:

json = None

#### STRING FUNCTIONS ##############################################################################

RE_AMPERSAND = re.compile("\&(?!\#)") # & not followed by #

RE_UNICODE = re.compile(r'&(#?)(x|X?)(\w+);') # &#201;

def encode_entities(string):

""" Encodes HTML entities in the given string ("<" => "&lt;").

For example, to display "<em>hello</em>" in a browser,

we need to pass "&lt;em&gt;hello&lt;/em&gt;" (otherwise "hello" in italic is displayed).

"""

if isinstance(string, basestring):

string = RE_AMPERSAND.sub("&amp;", string)

string = string.replace("<", "&lt;")

string = string.replace(">", "&gt;")

string = string.replace('"', "&quot;")

string = string.replace("'", "&#39;")

return string

def decode_entities(string):

""" Decodes HTML entities in the given string ("&lt;" => "<").

"""

# http://snippets.dzone.com/posts/show/4569

def replace_entity(match):

hash, hex, name = match.group(1), match.group(2), match.group(3)

if hash == "#" or name.isdigit():

if hex == "":

return unichr(int(name)) # "&#38;" => "&"

if hex.lower() == "x":

return unichr(int("0x" + name, 16)) # "&#x0026;" = > "&"

else:

cp = htmlentitydefs.name2codepoint.get(name) # "&amp;" => "&"

return unichr(cp) if cp else match.group() # "&foo;" => "&foo;"

if isinstance(string, basestring):

return RE_UNICODE.subn(replace_entity, string)[0]

return string

def encode_url(string):

return urllib.quote_plus(bytestring(string)) # "black/white" => "black%2Fwhite".

def decode_url(string):

return urllib.unquote_plus(string)

_TEMPORARY_FILES = []

def openable(string, **kwargs):

""" Returns the path to a temporary file that contains the given string.

"""

f = tempfile.NamedTemporaryFile(**kwargs)

f.write(string)

f.seek(0)

_TEMPORARY_FILES.append(f) # Delete when program terminates.

return f.name

#### INTROSPECTION #################################################################################

# URL paths are routed to handler functions, whose arguments represent URL path & query parameters.

# So we need to know what the arguments and keywords arguments are at runtime.

def define(f):

""" Returns (name, type, tuple, dict) for the given function,

with a tuple of argument names and a dict of keyword arguments.

If the given function has *args, returns True instead of tuple.

If the given function has **kwargs, returns True instead of dict.

"""

def undecorate(f): # "__closure__" in Py3.

while getattr(f, "func_closure", None):

f = [v.cell_contents for v in getattr(f, "func_closure")]

f = [v for v in f if callable(v)]

f = f[0] # We need guess (arg could also be a function).

return f

f = undecorate(f)

a = inspect.getargspec(f) # (names, *args, **kwargs, values)

i = len(a[0]) - len(a[3] or [])

x = tuple(a[0][:i])

y = dict(zip(a[0][i:], a[3] or []))

x = x if not a[1] else True

y = y if not a[2] else True

return (f.__name__, type(f), x, y)

#### DATABASE ######################################################################################

#--- DATABASE --------------------------------------------------------------------------------------

# A simple wrapper for SQLite and MySQL databases.

# Database type:

SQLITE, MYSQL = "sqlite", "mysql"

# Database host:

LOCALHOST = "127.0.0.1"

class Row(dict):

def __init__(self, cursor, row):

""" Row as dictionary.

"""

d = cursor.description

dict.__init__(self, ((d[i][0], v) for i, v in enumerate(row)))

def __getattr__(self, k):

return self[k] # Row.[field]

class DatabaseError(Exception):

pass

class Database(object):

def __init__(self, name, **kwargs):

""" Creates and opens the SQLite database with the given name.

"""

k = kwargs.get

self._name = name

self._type = k("type", SQLITE)

self._host = k("host", LOCALHOST)

self._port = k("port", 3306)

self._user = k("user", (k("username", "root"), k("password", "")))

self._factory = k("factory", Row)

self._timeout = k("timeout", 10)

self._connection = None

if kwargs.get("connect", True):

self.connect()

if kwargs.get("schema"):

# Database(schema="create table if not exists" `...`)

# initializes the database table and index structure.

for q in kwargs["schema"].split(";"):

self.execute(q+";", commit=False)

self.commit()

@property

def name(self):

""" Yields the database name (for SQLITE, file path).

"""

return self._name

@property

def type(self):

""" Yields the database type (SQLITE or MYSQL).

"""

return self._type

@property

def host(self):

""" Yields the database server host (MYSQL).

"""

return self._host

@property

def port(self):

""" Yields the database server port (MYSQL).

"""

return self._port

@property

def connection(self):

""" Yields the sqlite3.Connection object.

"""

return self._connection

def connect(self):

if self._type == SQLITE:

self._connection = sqlite.connect(self._name, timeout=self._timeout)

self._connection.row_factory = self._factory

if self._type == MYSQL:

import MySQLdb

self._connection = MySQLdb.connect(

host = self._host,

port = self._port,

user = self._user[0],

passwd = self._user[1],

connect_timeout = self._timeout,

use_unicode = True,

charset = "utf8"

)

self._connection.row_factory = self._factory

self._connection.cursor().execute("create database if not exists `%s`" % self._name)

self._connection.cursor().execute("use `%s`" % self._name)

def disconnect(self):

if self._connection is not None:

self._connection.commit()

self._connection.close()

self._connection = None

def execute(self, sql, values=(), first=False, commit=True):

""" Executes the given SQL query string and returns an iterator of rows.

With first=True, returns the first row.

"""

try:

r = self._connection.cursor().execute(sql, values)

if commit:

self._connection.commit()

except Exception as e:

# "OperationalError: database is locked" means that

# SQLite is receiving too many concurrent write ops.

# A write operation locks the entire database;

# other threaded connections may time out waiting.

# In this case you can raise Database(timeout=10),

# lower Application.run(threads=10) or switch to MySQL or Redis.

self._connection.rollback()

raise DatabaseError(str(e))

return r.fetchone() if first else r

def commit(self):

""" Commits changes (pending insert/update/delete queries).

"""

self._connection.commit()

def rollback(self):

""" Discard changes since the last commit.

"""

self._connection.rollback()

def __call__(self, *args, **kwargs):

return self.execute(*args, **kwargs)

def __repr__(self):

return "Database(name=%s)" % repr(self._name)

def __del__(self):

try:

self.disconnect()

except:

pass

@property

def batch(self):

return Database._batch.setdefault(self._name, DatabaseTransaction(self._name, **self.__dict__))

_batch = {} # Shared across all instances.

#--- DATABASE TRANSACTION BUFFER -------------------------------------------------------------------

class DatabaseTransaction(Database):

def __init__(self, name, **kwargs):

""" Database.batch.execute() stores given the SQL query in RAM memory, across threads.

Database.batch.commit() commits all buffered queries.

This can be combined with @app.task() to periodically write batches to the database

(instead of writing on each request).

"""

Database.__init__(self, name, **dict(kwargs, connect=False))

self._queue = []

def execute(self, sql, values=()):

self._queue.append((sql, values))

def commit(self):

q, self._queue = self._queue, []

if q:

try:

Database.connect(self) # Connect in this thread.

for sql, v in q:

Database.execute(self, sql, v, commit=False)

Database.commit(self)

except DatabaseError as e:

Database.rollback(self) # Data in q will be lost.

raise e

def rollback(self):

self._queue = []

def __len__(self):

return len(self._queue)

def __repr__(self):

return "DatabaseTransaction(name=%s)" % repr(self._name)

@property

def batch(self):

raise AttributeError

#---------------------------------------------------------------------------------------------------

# MySQL on Mac OS X installation notes:

# 1) Download Sequel Pro: http://www.sequelpro.com (GUI).

# 2) Download MySQL .dmg: http://dev.mysql.com/downloads/mysql/ (for 64-bit Python, 64-bit MySQL).

# 3) Install the .pkg, startup item and preferences pane.

# 4) Start server in preferences pane (user: "root", password: "").

# 5) Command line: open -a "TextEdit" .bash_profile =>

# 6) export PATH=~/bin:/usr/local/bin:/usr/local/mysql/bin:$PATH

# 7) Command line: sudo pip install MySQL-python

# 8) Command line: sudo ln -s /usr/local/mysql/lib/libmysqlclient.xx.dylib

# /usr/lib/libmysqlclient.xx.dylib

# 9) import MySQLdb

#### RATE LIMITING #################################################################################

# With @app.route(path, limit=True), the decorated URL path handler function calls RateLimit().

# For performance, rate limiting uses a RAM cache of api keys + the time of the last request.

# This will not work with multi-processing, since each process gets its own RAM.

_RATELIMIT_CACHE = {} # RAM cache of request counts.

_RATELIMIT_LOCK = threading.RLock()

SECOND, MINUTE, HOUR, DAY = 1., 60., 60*60., 60*60*24.

class RateLimitError(Exception):

pass

class RateLimitExceeded(RateLimitError):

pass

class RateLimitForbidden(RateLimitError):

pass

class RateLimit(Database):

def __init__(self, name="rate.db", **kwargs):

""" A database for rate limiting API requests.

It manages a table with (key, path, limit, time) entries.

It grants each key a rate (number of requests / time) for a URL path.

It keeps track of the number of requests in local memory (i.e., RAM).

If RateLimit()() is called with the optional limit and time arguments,

unknown keys are temporarily granted this rate.

"""

Database.__init__(self, name, **dict(kwargs, factory=None, schema=(

"create table if not exists `rate` ("

"`key` text," # API key (e.g., ?key="1234").

"`path` text," # API URL path (e.g., "/api/1/").

"`limit` integer," # Maximum number of requests.

"`time` float" # Time frame.

");"

"create index if not exists `rate1` on rate(key);"

"create index if not exists `rate2` on rate(path);")

))

self.load()

@property

def cache(self):

return _RATELIMIT_CACHE

@property

def lock(self):

return _RATELIMIT_LOCK

@property

def key(self, pairs=("rA","aZ","gQ","hH","hG","aR","DD")):

""" Yields a new random key ("ZjNmYTc4ZDk0MTkyYk...").

"""

k = str(random.getrandbits(256))

k = hashlib.sha256(k).hexdigest()

k = base64.b64encode(k, random.choice(pairs)).rstrip('==')

return k

def reset(self):

self.cache.clear()

self.load()

def load(self):

""" For performance, rate limiting is handled in memory (i.e., RAM).

Loads the stored rate limits in memory (100,000 records ~= 5MB RAM).

"""

with self.lock:

if not self.cache:

# Lock concurrent threads when modifying cache.

for r in self.execute("select * from `rate`;"):

self.cache[(r[0], r[1])] = (0, r[2], r[3], _time.time())

self._rowcount = len(self.cache)

def set(self, key, path="/", limit=100, time=HOUR):

""" Sets the rate for the given key and path,

where limit is the maximum number of requests in the given time (e.g., 100/hour).

"""

# Update database.

p = "/" + path.strip("/")

q1 = "delete from `rate` where key=? and path=?;"

q2 = "insert into `rate` values (?, ?, ?, ?);"

self.execute(q1, (key, p), commit=False)

self.execute(q2, (key, p, limit, time))

# Update cache.

with self.lock:

self.cache[(key, p)] = (0, limit, time, _time.time())

self._rowcount += 1

return (key, path, limit, time)

def get(self, key, path="/"):

""" Returns the rate for the given key and path (or None).

"""

p = "/" + path.strip("/")

q = "select * from `rate` where key=? and path=?;"

return self.execute(q, (key, p), first=True, commit=False)

def __setitem__(self, k, v): # (key, path), (limit, time)

return self.set(key, path, limit, time)

def __getitem__(self, k): # (key, path)

return self.get(*k)

def __contains__(self, key, path="%"):

""" Returns True if the given key exists (for the given path).

"""

q = "select * from `rate` where key=? and path like ?;"

return self.execute(q, (key, path), first=True, commit=False) is not None

def __call__(self, key, path="/", limit=None, time=None, reset=100000):

""" Increases the (cached) request count by 1 for the given key and path.

If the request count exceeds its limit, raises RateLimitExceeded.

If the optional limit and time are given, unknown keys (!= None)

are given this rate limit - as long as the cache exists in memory.

Otherwise a RateLimitForbidden is raised.

"""

with self.lock:

t = _time.time()

p = "/" + path.strip("/")

r = self.cache.get((key, p))

# Reset the cache if too large (e.g., 1M+ IP addresses).

if reset and reset < len(self.cache) and reset > self._rowcount:

self.reset()

# Unknown key (apply default limit / time rate).

if r is None and key is not None and limit is not None and time is not None:

self.cache[(key, p)] = r = (0, limit, time, t)

# Unknown key (apply root key, if any).

if r is None and p != "/":

self.cache.get((key, "/"))

if r is None:

raise RateLimitForbidden

# Limit reached within time frame (raise error).

elif r[0] >= r[1] and r[2] > t - r[3]:

raise RateLimitExceeded

# Limit reached out of time frame (reset count).

elif r[0] >= r[1]:

self.cache[(key, p)] = (1, r[1], r[2], t)

# Limit not reached (increment count).

elif r[0] < r[1]:

self.cache[(key, p)] = (r[0] + 1, r[1], r[2], r[3])

#print(self.cache.get((key, path)))

#### ROUTER ########################################################################################

# The @app.route(path) decorator registers each URL path handler in Application.router.

class RouteError(Exception):

pass

class Router(dict):

def __init__(self):

""" A router resolves URL paths to handler functions.

"""

pass

def __setitem__(self, path, handler):

""" Defines the handler function for the given URL path.

The path is a slash-formatted string (e.g., "/api/1/en/parser").

The handler is a function that takes

arguments (path) and keyword arguments (query data).

"""

p = "/" + path.strip("/")

p = p.lower()

p = p.encode("utf8") if isinstance(p, unicode) else p

# Store the handler + its argument names (tuple(args), dict(kwargs)),

# so that we can call this function without (all) keyword arguments,

# if it does not take (all) query data.

if callable(handler):

dict.__setitem__(self, p, (handler, define(handler)[2:]))

else:

dict.__setitem__(self, p, (handler, ((), {})))

def __call__(self, path, **data):

""" Calls the handler function for the given URL path.

If no handler is found, raises a RouteError.

If a base handler is found (e.g., "/api" for "/api/1/en"),

calls the handler with arguments (e.g., handler("1", "en")).

"""

if not isinstance(path, tuple):

path = path.strip("/").split("/") # ["api", "1", "en"]

n = len(path)

for i in xrange(n + 1):

p0 = "/" + "/".join(path[:n-i])

p0 = p0.lower() # "/api/1/en", "/api/1", "/api", ...

p1 = path[n-i:] # [], ["en"], ["1", "en"], ...

if p0 in self:

(handler, (args, kwargs)) = self[p0]

i = len(p1)

j = len(args) if args is not True else i

# Handler takes 1 argument, 0 given (pass None for convenience).

if i == 0 and j == 1:

p1 = (None,); i=j

# Handler does not take path.

if i != j:

continue

# Handler is a string / dict.

if not callable(handler):

return handler

# Handler takes path, but no query data.

if not kwargs:

return handler(*p1)

# Handler takes path and all query data.

if kwargs is True:

return handler(*p1, **data)

# Handler takes path and some query data.

return handler(*p1, **dict((k, v) for k, v in data.items() if k in kwargs))

# No handler.

raise RouteError

#### APPLICATION ###################################################################################

#--- APPLICATION ERRORS & REQUESTS -----------------------------------------------------------------

class HTTPRequest(object):

def __init__(self, app, ip, path="/", method="get", data={}, headers={}):

""" A HTTP request object with metadata returned from app.request.

"""

self.app = app

self.ip = ip

self.path = "/" + path.strip("/")

self.method = method.lower()

self.data = dict(data)

self.headers = dict(headers)

def __repr__(self):

return "HTTPRequest(ip=%s, path=%s)" % repr(self.ip, self.path)

class HTTPRedirect(Exception):

def __init__(self, url, code=303):

""" A HTTP redirect raised in an @app.route() handler.

"""

self.url = url

self.code = code

def __repr__(self):

return "HTTPRedirect(url=%s)" % repr(self.url)

class HTTPError(Exception):

def __init__(self, status="", message="", traceback=""):

""" A HTTP error raised in an @app.route() handler + passed to @app.error().

"""

self.code = int(status.split(" ")[0])

self.status = status

self.message = message

self.traceback = traceback or ""

def __repr__(self):

return "HTTPError(status=%s)" % repr(self.status)

def _HTTPErrorSubclass(status):

return type("HTTP%sError" % status.split(" ")[0], (HTTPError,), {'__init__': \

lambda self, message="", traceback="": HTTPError.__init__(self, status, message, traceback)})

HTTP200OK = _HTTPErrorSubclass("200 OK")

HTTP401Authentication = _HTTPErrorSubclass("401 Authentication")

HTTP403Forbidden = _HTTPErrorSubclass("403 Forbidden")

HTTP404NotFound = _HTTPErrorSubclass("404 Not Found")

HTTP429TooManyRequests = _HTTPErrorSubclass("429 Too Many Requests")

HTTP500InternalServerError = _HTTPErrorSubclass("500 InternalServerError")

HTTP503ServiceUnavailable = _HTTPErrorSubclass("503 ServiceUnavailable")

#--- APPLICATION THREAD-SAFE DATA ------------------------------------------------------------------

# With a multi-threaded server, each thread requires its own local data (i.e., database connection).

# Local data can be initialized with @app.thread(START):

#

# >>> @app.thread(START)

# >>> def db():

# >>> g.db = Database()

# >>>

# >>> @app.route("/")

# >>> def index(*path, db=None):

# >>> print(db) # = Database object.

#

# The thread-safe database connection can then be retrieved from

# app.thread.db, g.db, or as a keyword argument of a URL handler.

class localdict(dict):

def __init__(self, data=None, **kwargs):

""" Thread-safe dictionary.

"""

self.__dict__["_data"] = data if data != None else threading.local()

self.__dict__.update(kwargs) # Attributes are global in every thread.

def items(self):

return self._data.__dict__.items()

def keys(self):

return self._data.__dict__.keys()

def values(self):

return self._data.__dict__.values()

def update(self, d):

return self._data.__dict__.update(d)

def clear(self):

return self._data.__dict__.clear()

def pop(self, *kv):

return self._data.__dict__.pop(*kv)

def setdefault(self, k, v=None):

return self._data.__dict__.setdefault(k, v)

def set(self, k, v):

return setattr(self._data, k, v)

def get(self, k, default=None):

return getattr(self._data, k, default)

def __delitem__(self, k):

return delattr(self._data, k)

def __getitem__(self, k):

return getattr(self._data, k)

def __setitem__(self, k, v):

return setattr(self._data, k, v)

def __delattr__(self, k):

return delattr(self._data, k)

def __getattr__(self, k):

return getattr(self._data, k)

def __setattr__(self, k, v):

return setattr(self._data, k, v)

def __len__(self):

return len(self._data.__dict__)

def __iter__(self):

return iter(self._data.__dict__)

def __contains__(self, k):

return k in self._data.__dict__

def __str__(self):

return repr(self)

def __repr__(self):

return "localdict({%s})" % ", ".join(

("%s: %s" % (repr(k), repr(v)) for k, v in self.items()))

# Global alias for app.thread (Flask-style):

g = localdict(data=cp.thread_data)

def threadsafe(function):

""" The @threadsafe decorator ensures that no two threads execute the function simultaneously.

"""

# In some cases, global data must be available across all threads (e.g., rate limits).

# Atomic operations like dict.get() or list.append() (= single execution step) are thread-safe,

# but some operations like dict[k] += 1 are not, and require a lock.

# http://effbot.org/zone/thread-synchronization.htm

#

# >>> count = defaultdict(int)

# >>> @threadsafe

# >>> def inc(k):

# >>> count[k] += 1

#

lock = threading.RLock()

def decorator(*args, **kwargs):

with lock:

v = function(*args, **kwargs)

return v

return decorator

#--- APPLICATION -----------------------------------------------------------------------------------

# With Apache + mod_wsgi, the Application instance must be named "application".

# Server host.

LOCALHOST = "127.0.0.1"

INTRANET = "0.0.0.0"

# Server thread handlers.

START = "start"

STOP = "stop"

class ApplicationError(Exception):

pass

class Application(object):

def __init__(self, name=None, path=SCRIPT, static="./static", rate="rate.db"):

""" A web app served by a WSGI-server that starts with App.run().

By default, the app is served from the folder of the script that imports pattern.server.

By default, static content is served from the given subfolder.

@App.route(path) defines a URL path handler.

@App.error(code) defines a HTTP error handler.

"""

# RateLimit db resides in app folder:

rate = os.path.join(path, rate)

self._name = name # App name.

self._path = path # App path.

self._host = None # Server host, see App.run().

self._port = None # Server port, see App.run().

self._app = None # CherryPy Application object.

self._up = False # True if server is up & running.

self._cache = {} # Memoize cache.

self._cached = 1000 # Memoize cache size.

self._static = static # Static content folder.

self._rate = rate # RateLimit db name, see also App.route(limit=True).

self.router = Router() # Router object, maps URL paths to handlers.

self.thread = App.Thread() # Thread-safe dictionary.

os.chdir(path)

@property

def name(self):

return self._name

@property

def host(self):

return self._host

@property

def port(self):

return self._port

@property

def up(self):

return self._up

running = up

@property

def path(self):

""" Yields the absolute path to the folder containing the app.

"""

return self._path

@property

def static(self):

""" Yields the absolute path to the folder with static content.

"""

return os.path.join(self._path, self._static)

@property

def session(self):

""" Yields the dictionary of session data.

"""

return cp.session

@property

def request(self):

""" Yields a request object with metadata

(IP address, request path, query data and headers).

"""

r = cp.request # Deep copy (ensures garbage colletion).

return HTTPRequest(

app = self,

ip = r.remote.ip,

path = r.path_info,

method = r.method,

data = r.params,

headers = r.headers)

@property

def response(self):

""" Yields a response object with metadata

(status, headers).

"""

return cp.response

@property

def elapsed(self):

""" Yields the elapsed time since the start of the request.

"""

return time.time() - cp.request.time # See also _request_time().

def _cast(self, v):

""" Returns the given value as a string (used to cast handler functions).

If the value is a dictionary, returns a JSON-string.

If the value is a generator, starts a stream.

If the value is an iterable, joins the values with a space.

"""

if isinstance(v, basestring):

return v

if isinstance(v, cp.lib.file_generator): # serve_file()

return v

if isinstance(v, dict):

cp.response.headers["Content-Type"] = "application/json; charset=utf-8"

cp.response.headers["Access-Control-Allow-Origin"] = "*" # CORS

return json.dumps(v)

if isinstance(v, types.GeneratorType):

cp.response.stream = True

return iter(self._cast(v) for v in v)

if isinstance(v, (list, tuple, set)):

return " ".join(self._cast(v) for v in v)

if isinstance(v, HTTPError):

raise cp.HTTPError(v.status, message=v.message)

if v is None:

return ""

try: # (bool, int, float, object.__unicode__)

return unicode(v)

except:

return encode_entities(repr(v))

@cp.expose

def default(self, *path, **data):

""" Resolves URL paths to handler functions and casts the return value.

"""

# If there is an app.thread.db connection,

# pass it as a keyword argument named "db".

# If there is a query parameter named "db",

# it is overwritten (the reverse is not safe).

for k, v in g.items():

data[k] = v

# Call the handler function for the given path.

# Call @app.error(404) if no handler is found.

# Call @app.error(403) if rate limit forbidden (= no API key).

# Call @app.error(429) if rate limit exceeded.

# Call @app.error(503) if a database error occurs.

try:

v = self.router(path, **data)

except RouteError:

raise cp.HTTPError("404 Not Found")

except RateLimitForbidden:

raise cp.HTTPError("403 Forbidden")

except RateLimitExceeded:

raise cp.HTTPError("429 Too Many Requests")

except DatabaseError as e:

raise cp.HTTPError("503 Service Unavailable", message=str(e))

except HTTPRedirect as e:

raise cp.HTTPRedirect(e.url)

except HTTPError as e:

raise cp.HTTPError(e.status, message=e.message)

v = self._cast(v)

#print(self.elapsed)

return v

def unlimited(self, v=None):

self._ratelimited = False # See App.route() below.

return v

def route(self, path, limit=False, time=None, key=lambda data: data.get("key"), reset=100000):

""" The @app.route(path) decorator defines the handler function for the given path.

The function can take arguments (path) and keyword arguments (query data), e.g.,

if no handler exists for URL "/api/1/en", but a handler exists for URL "/api/1",

this handler will be called with 1 argument: "en".

It returns a string, a generator or a dictionary (which is parsed to a JSON-string).

"""

_a = (key, limit, time, reset) # Avoid ambiguity with key=lambda inside define().

def decorator(handler):

def ratelimited(handler):

# With @app.route(path, limit=True), rate limiting is applied.

# The handler function is wrapped in a function that first calls

# RateLimit()(key, path, limit, time) before calling the handler.

# By default, a query parameter "key" is expected.

# If the key is known, apply rate limiting (429 Too Many Requests).

# If the key is unknown or None, deny access (403 Forbidden).

# If the key is unknown and a default limit and time are given,

# add the key and grant the given credentials, e.g.:

# @app.route(path, limit=100, time=HOUR, key=lambda data: app.request.ip).

# This grants each IP-address a 100 requests per hour.

@self.thread(START)

def connect():

g.rate = RateLimit(name=self._rate)

def wrapper(*args, **kwargs):

self = cp.request.app.root

self._ratelimited = True

v = handler(*args, **kwargs)

if self._ratelimited: # App.unlimited() in handler() sets it to False.

self.rate(

key = _a[0](cp.request.params),

path = "/" + cp.request.path_info.strip("/"),

limit = _a[1], # Default limit for unknown keys.

time = _a[2], # Default time for unknown keys.

reset = _a[3] # Threshold for clearing cache.

)

return v

return wrapper

if limit is True or (limit is not False and limit is not None and time is not None):

handler = ratelimited(handler)

self.router[path] = handler # Register the handler.

return handler

return decorator

def error(self, code="*"):

""" The @app.error(code) decorator defines the handler function for the given HTTP error.

The function takes a HTTPError object and returns a string.

"""

def decorator(handler):

# CherryPy error handlers take keyword arguments.

# Wrap as a HTTPError and pass it to the handler.

def wrapper(status="", message="", traceback="", version=""):

# Avoid CherryPy bug "ValueError: status message was not supplied":

v = handler(HTTPError(status, message, traceback))

v = self._cast(v) if not isinstance(v, HTTPError) else repr(v)

return v

# app.error("*") catches all error codes.

if code in ("*", None):

cp.config.update({"error_page.default": wrapper})

# app.error(404) catches 404 error codes.

elif isinstance(code, (int, basestring)):

cp.config.update({"error_page.%s" % code: wrapper})

# app.error((404, 500)) catches 404 + 500 error codes.

elif isinstance(code, (tuple, list)):

for x in code:

cp.config.update({"error_page.%s" % x: wrapper})

return handler

return decorator

def view(self, template, cached=True):

""" The @app.view(template) decorator defines a template to format the handler function.

The function returns a dict of keyword arguments for Template.render().

"""

def decorator(handler):

def wrapper(*args, **kwargs):

if not hasattr(template, "render"): # bottle.py templates have render() too.

t = Template(template, root=self.static, cached=cached)

else:

t = template

v = handler(*args, **kwargs)

if isinstance(v, dict):

return t.render(**v) # {kwargs}

return t.render(*v) # (globals(), locals(), {kwargs})

return wrapper

return decorator

class Thread(localdict):

""" The @app.thread(event) decorator can be used to initialize thread-safe data.

Get data (e.g., a database connection) with app.thread.[name] or g.[name].

"""

def __init__(self):

localdict.__init__(self, data=cp.thread_data, handlers=set())

def __call__(self, event=START): # START / STOP

def decorator(handler):

def wrapper(id):

return handler()

# If @app.thread() is called twice for

# the same handler, register it only once.

if not (event, handler) in self.handlers:

self.handlers.add((event, handler))

cp.engine.subscribe(event + "_thread", wrapper)

return handler

return decorator

@property

def rate(self, name="rate"):

""" Yields a thread-safe connection to the app's RateLimit db.

"""

if not hasattr(g, name): setattr(g, name, RateLimit(name=self._rate))

return getattr(g, name)

def bind(self, name="db"):

""" The @app.bind(name) decorator binds the given function to a keyword argument

that can be used with @app.route() handlers.

The return value is stored thread-safe in app.thread.[name] & g.[name].

The return value is available in handlers as a keyword argument [name].

"""

# This is useful for multi-threaded database connections:

# >>>

# >>> @app.bind("db")

# >>> def db():

# >>> return Database("products.db")