Open Source Projects Europe

#!/usr/bin/env python

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

"""

Bottle is a fast and simple micro-framework for small web applications. It

offers request dispatching (Routes) with url parameter support, templates,

a built-in HTTP Server and adapters for many third party WSGI/HTTP-server and

template engines - all in a single file and with no dependencies other than the

Python Standard Library.

Homepage and documentation: http://bottlepy.org/

Copyright (c) 2011, Marcel Hellkamp.

License: MIT (see LICENSE.txt for details)

"""

from __future__ import with_statement

__author__ = 'Marcel Hellkamp'

__version__ = '0.10.11'

__license__ = 'MIT'

# The gevent server adapter needs to patch some modules before they are imported

# This is why we parse the commandline parameters here but handle them later

if __name__ == '__main__':

    from optparse import OptionParser

    _cmd_parser = OptionParser(usage="usage: %prog [options] package.module:app")

    _opt = _cmd_parser.add_option

    _opt("--version", action="store_true", help="show version number.")

    _opt("-b", "--bind", metavar="ADDRESS", help="bind socket to ADDRESS.")

    _opt("-s", "--server", default='wsgiref', help="use SERVER as backend.")

    _opt("-p", "--plugin", action="append", help="install additional plugin/s.")

    _opt("--debug", action="store_true", help="start server in debug mode.")

    _opt("--reload", action="store_true", help="auto-reload on file changes.")

    _cmd_options, _cmd_args = _cmd_parser.parse_args()

    if _cmd_options.server and _cmd_options.server.startswith('gevent'):

        import gevent.monkey; gevent.monkey.patch_all()

import sys

import base64

import cgi

import email.utils

import functools

import hmac

import httplib

import imp

import itertools

import mimetypes

import os

import re

import subprocess

import tempfile

import thread

import threading

import time

import warnings

from Cookie import SimpleCookie

from datetime import date as datedate, datetime, timedelta

from tempfile import TemporaryFile

from traceback import format_exc, print_exc

from urlparse import urljoin, SplitResult as UrlSplitResult

# Workaround for a bug in some versions of lib2to3 (fixed on CPython 2.7 and 3.2)

import urllib

urlencode = urllib.urlencode

urlquote = urllib.quote

urlunquote = urllib.unquote

try: from collections import MutableMapping as DictMixin

except ImportError: # pragma: no cover

    from UserDict import DictMixin

try: import cPickle as pickle

except ImportError: # pragma: no cover

    import pickle

try: from json import dumps as json_dumps, loads as json_lds

except ImportError: # pragma: no cover

    try: from simplejson import dumps as json_dumps, loads as json_lds

    except ImportError: # pragma: no cover

        try: from django.utils.simplejson import dumps as json_dumps, loads as json_lds

        except ImportError: # pragma: no cover

            def json_dumps(data):

                raise ImportError("JSON support requires Python 2.6 or simplejson.")

            json_lds = json_dumps

py = sys.version_info

py3k = py >= (3,0,0)

NCTextIOWrapper = None

if sys.version_info < (2,6,0):

    msg = "Python 2.5 support may be dropped in future versions of Bottle."

    warnings.warn(msg, DeprecationWarning)

if py3k: # pragma: no cover

    json_loads = lambda s: json_lds(touni(s))

    urlunquote = functools.partial(urlunquote, encoding='latin1')

    # See Request.POST

    from io import BytesIO

    def touni(x, enc='utf8', err='strict'):

        """ Convert anything to unicode """

        return str(x, enc, err) if isinstance(x, bytes) else str(x)

    if sys.version_info < (3,2,0):

        from io import TextIOWrapper

        class NCTextIOWrapper(TextIOWrapper):

            ''' Garbage collecting an io.TextIOWrapper(buffer) instance closes

                the wrapped buffer. This subclass keeps it open. '''

            def close(self): pass

else:

    json_loads = json_lds

    from StringIO import StringIO as BytesIO

    bytes = str

    def touni(x, enc='utf8', err='strict'):

        """ Convert anything to unicode """

        return x if isinstance(x, unicode) else unicode(str(x), enc, err)

def tob(data, enc='utf8'):

    """ Convert anything to bytes """

    return data.encode(enc) if isinstance(data, unicode) else bytes(data)

tonat = touni if py3k else tob

tonat.__doc__ = """ Convert anything to native strings """

def try_update_wrapper(wrapper, wrapped, *a, **ka):

    try: # Bug: functools breaks if wrapper is an instane method

        functools.update_wrapper(wrapper, wrapped, *a, **ka)

    except AttributeError: pass

# 3.2 fixes cgi.FieldStorage to accept bytes (which makes a lot of sense).

#     but defaults to utf-8 (which is not always true)

# 3.1 needs a workaround.

NCTextIOWrapper = None

if (3,0,0) < py < (3,2,0):

    from io import TextIOWrapper

    class NCTextIOWrapper(TextIOWrapper):

        def close(self): pass # Keep wrapped buffer open.

# Backward compatibility

def depr(message):

    warnings.warn(message, DeprecationWarning, stacklevel=3)

# Small helpers

def makelist(data):

    if isinstance(data, (tuple, list, set, dict)): return list(data)

    elif data: return [data]

    else: return []

class DictProperty(object):

    ''' Property that maps to a key in a local dict-like attribute. '''

    def __init__(self, attr, key=None, read_only=False):

        self.attr, self.key, self.read_only = attr, key, read_only

    def __call__(self, func):

        functools.update_wrapper(self, func, updated=[])

        self.getter, self.key = func, self.key or func.__name__

        return self

    def __get__(self, obj, cls):

        if obj is None: return self

        key, storage = self.key, getattr(obj, self.attr)

        if key not in storage: storage[key] = self.getter(obj)

        return storage[key]

    def __set__(self, obj, value):

        if self.read_only: raise AttributeError("Read-Only property.")

        getattr(obj, self.attr)[self.key] = value

    def __delete__(self, obj):

        if self.read_only: raise AttributeError("Read-Only property.")

        del getattr(obj, self.attr)[self.key]

class CachedProperty(object):

    ''' A property that is only computed once per instance and then replaces

        itself with an ordinary attribute. Deleting the attribute resets the

        property. '''

    def __init__(self, func):

        self.func = func

    def __get__(self, obj, cls):

        if obj is None: return self

        value = obj.__dict__[self.func.__name__] = self.func(obj)

        return value

cached_property = CachedProperty

class lazy_attribute(object): # Does not need configuration -> lower-case name

    ''' A property that caches itself to the class object. '''

    def __init__(self, func):

        functools.update_wrapper(self, func, updated=[])

        self.getter = func

    def __get__(self, obj, cls):

        value = self.getter(cls)

        setattr(cls, self.__name__, value)

        return value

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

# Exceptions and Events ########################################################

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

class BottleException(Exception):

    """ A base class for exceptions used by bottle. """

    pass

#TODO: These should subclass BaseRequest

class HTTPResponse(BottleException):

    """ Used to break execution and immediately finish the response """

    def __init__(self, output='', status=200, header=None):

        super(BottleException, self).__init__("HTTP Response %d" % status)

        self.status = int(status)

        self.output = output

        self.headers = HeaderDict(header) if header else None

    def apply(self, response):

        if self.headers:

            for key, value in self.headers.iterallitems():

                response.headers[key] = value

        response.status = self.status

class HTTPError(HTTPResponse):

    """ Used to generate an error page """

    def __init__(self, code=500, output='Unknown Error', exception=None,

                 traceback=None, header=None):

        super(HTTPError, self).__init__(output, code, header)

        self.exception = exception

        self.traceback = traceback

    def __repr__(self):

        return tonat(template(ERROR_PAGE_TEMPLATE, e=self))

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

# Routing ######################################################################

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

class RouteError(BottleException):

    """ This is a base class for all routing related exceptions """

class RouteReset(BottleException):

    """ If raised by a plugin or request handler, the route is reset and all

        plugins are re-applied. """

class RouterUnknownModeError(RouteError): pass

class RouteSyntaxError(RouteError):

    """ The route parser found something not supported by this router """

class RouteBuildError(RouteError):

    """ The route could not been built """

class Router(object):

    ''' A Router is an ordered collection of route->target pairs. It is used to

        efficiently match WSGI requests against a number of routes and return

        the first target that satisfies the request. The target may be anything,

        usually a string, ID or callable object. A route consists of a path-rule

        and a HTTP method.

        The path-rule is either a static path (e.g. `/contact`) or a dynamic

        path that contains wildcards (e.g. `/wiki/<page>`). The wildcard syntax

        and details on the matching order are described in docs:`routing`.

    '''

    default_pattern = '[^/]+'

    default_filter   = 're'

    #: Sorry for the mess. It works. Trust me.

    rule_syntax = re.compile('(\\\\*)'\

        '(?:(?::([a-zA-Z_][a-zA-Z_0-9]*)?()(?:#(.*?)#)?)'\

          '|(?:<([a-zA-Z_][a-zA-Z_0-9]*)?(?::([a-zA-Z_]*)'\

            '(?::((?:\\\\.|[^\\\\>]+)+)?)?)?>))')

    def __init__(self, strict=False):

        self.rules    = {} # A {rule: Rule} mapping

        self.builder  = {} # A rule/name->build_info mapping

        self.static   = {} # Cache for static routes: {path: {method: target}}

        self.dynamic  = [] # Cache for dynamic routes. See _compile()

        #: If true, static routes are no longer checked first.

        self.strict_order = strict

        self.filters = {'re': self.re_filter, 'int': self.int_filter,

                        'float': self.float_filter, 'path': self.path_filter}

    def re_filter(self, conf):

        return conf or self.default_pattern, None, None

    def int_filter(self, conf):

        return r'-?\d+', int, lambda x: str(int(x))

    def float_filter(self, conf):

        return r'-?[\d.]+', float, lambda x: str(float(x))

    def path_filter(self, conf):

        return r'.*?', None, None

    def add_filter(self, name, func):

        ''' Add a filter. The provided function is called with the configuration

        string as parameter and must return a (regexp, to_python, to_url) tuple.

        The first element is a string, the last two are callables or None. '''

        self.filters[name] = func

    def parse_rule(self, rule):

        ''' Parses a rule into a (name, filter, conf) token stream. If mode is

            None, name contains a static rule part. '''

        offset, prefix = 0, ''

        for match in self.rule_syntax.finditer(rule):

            prefix += rule[offset:match.start()]

            g = match.groups()

            if len(g[0])%2: # Escaped wildcard

                prefix += match.group(0)[len(g[0]):]

                offset = match.end()

                continue

            if prefix: yield prefix, None, None

            name, filtr, conf = g[1:4] if not g[2] is None else g[4:7]

            if not filtr: filtr = self.default_filter

            yield name, filtr, conf or None

            offset, prefix = match.end(), ''

        if offset <= len(rule) or prefix:

            yield prefix+rule[offset:], None, None

    def add(self, rule, method, target, name=None):

        ''' Add a new route or replace the target for an existing route. '''

        if rule in self.rules:

            self.rules[rule][method] = target

            if name: self.builder[name] = self.builder[rule]

            return

        target = self.rules[rule] = {method: target}

        # Build pattern and other structures for dynamic routes

        anons = 0      # Number of anonymous wildcards

        pattern = ''   # Regular expression  pattern

        filters = []   # Lists of wildcard input filters

        builder = []   # Data structure for the URL builder

        is_static = True

        for key, mode, conf in self.parse_rule(rule):

            if mode:

                is_static = False

                mask, in_filter, out_filter = self.filters[mode](conf)

                if key:

                    pattern += '(?P<%s>%s)' % (key, mask)

                else:

                    pattern += '(?:%s)' % mask

                    key = 'anon%d' % anons; anons += 1

                if in_filter: filters.append((key, in_filter))

                builder.append((key, out_filter or str))

            elif key:

                pattern += re.escape(key)

                builder.append((None, key))

        self.builder[rule] = builder

        if name: self.builder[name] = builder

        if is_static and not self.strict_order:

            self.static[self.build(rule)] = target

            return

        def fpat_sub(m):

            return m.group(0) if len(m.group(1)) % 2 else m.group(1) + '(?:'

        flat_pattern = re.sub(r'(\\*)(\(\?P<[^>]*>|\((?!\?))', fpat_sub, pattern)

        try:

            re_match = re.compile('^(%s)$' % pattern).match

        except re.error, e:

            raise RouteSyntaxError("Could not add Route: %s (%s)" % (rule, e))

        def match(path):

            """ Return an url-argument dictionary. """

            url_args = re_match(path).groupdict()

            for name, wildcard_filter in filters:

                try:

                    url_args[name] = wildcard_filter(url_args[name])

                except ValueError:

                    raise HTTPError(400, 'Path has wrong format.')

            return url_args

        try:

            combined = '%s|(^%s$)' % (self.dynamic[-1][0].pattern, flat_pattern)

            self.dynamic[-1] = (re.compile(combined), self.dynamic[-1][1])

            self.dynamic[-1][1].append((match, target))

        except (AssertionError, IndexError), e: # AssertionError: Too many groups

            self.dynamic.append((re.compile('(^%s$)' % flat_pattern),

                                [(match, target)]))

        return match

    def build(self, _name, *anons, **query):

        ''' Build an URL by filling the wildcards in a rule. '''

        builder = self.builder.get(_name)

        if not builder: raise RouteBuildError("No route with that name.", _name)

        try:

            for i, value in enumerate(anons): query['anon%d'%i] = value

            url = ''.join([f(query.pop(n)) if n else f for (n,f) in builder])

            return url if not query else url+'?'+urlencode(query)

        except KeyError, e:

            raise RouteBuildError('Missing URL argument: %r' % e.args[0])

    def match(self, environ):

        ''' Return a (target, url_agrs) tuple or raise HTTPError(400/404/405). '''

        path, targets, urlargs = environ['PATH_INFO'] or '/', None, {}

        if path in self.static:

            targets = self.static[path]

        else:

            for combined, rules in self.dynamic:

                match = combined.match(path)

                if not match: continue

                getargs, targets = rules[match.lastindex - 1]

                urlargs = getargs(path) if getargs else {}

                break

        if not targets:

            raise HTTPError(404, "Not found: " + repr(environ['PATH_INFO']))

        method = environ['REQUEST_METHOD'].upper()

        if method in targets:

            return targets[method], urlargs

        if method == 'HEAD' and 'GET' in targets:

            return targets['GET'], urlargs

        if 'ANY' in targets:

            return targets['ANY'], urlargs

        allowed = [verb for verb in targets if verb != 'ANY']

        if 'GET' in allowed and 'HEAD' not in allowed:

            allowed.append('HEAD')

        raise HTTPError(405, "Method not allowed.",

                        header=[('Allow',",".join(allowed))])

class Route(object):

    ''' This class wraps a route callback along with route specific metadata and

        configuration and applies Plugins on demand. It is also responsible for

        turing an URL path rule into a regular expression usable by the Router.

    '''

    def __init__(self, app, rule, method, callback, name=None,

                 plugins=None, skiplist=None, **config):

        #: The application this route is installed to.

        self.app = app

        #: The path-rule string (e.g. ``/wiki/:page``).

        self.rule = rule

        #: The HTTP method as a string (e.g. ``GET``).

        self.method = method

        #: The original callback with no plugins applied. Useful for introspection.

        self.callback = callback

        #: The name of the route (if specified) or ``None``.

        self.name = name or None

        #: A list of route-specific plugins (see :meth:`Bottle.route`).

        self.plugins = plugins or []

        #: A list of plugins to not apply to this route (see :meth:`Bottle.route`).

        self.skiplist = skiplist or []

        #: Additional keyword arguments passed to the :meth:`Bottle.route`

        #: decorator are stored in this dictionary. Used for route-specific

        #: plugin configuration and meta-data.

        self.config = ConfigDict(config)

    def __call__(self, *a, **ka):

        depr("Some APIs changed to return Route() instances instead of"\

             " callables. Make sure to use the Route.call method and not to"\

             " call Route instances directly.")

        return self.call(*a, **ka)

    @cached_property

    def call(self):

        ''' The route callback with all plugins applied. This property is

            created on demand and then cached to speed up subsequent requests.'''

        return self._make_callback()

    def reset(self):

        ''' Forget any cached values. The next time :attr:`call` is accessed,

            all plugins are re-applied. '''

        self.__dict__.pop('call', None)

    def prepare(self):

        ''' Do all on-demand work immediately (useful for debugging).'''

        self.call

    @property

    def _context(self):

        depr('Switch to Plugin API v2 and access the Route object directly.')

        return dict(rule=self.rule, method=self.method, callback=self.callback,

                    name=self.name, app=self.app, config=self.config,

                    apply=self.plugins, skip=self.skiplist)

    def all_plugins(self):

        ''' Yield all Plugins affecting this route. '''

        unique = set()

        for p in reversed(self.app.plugins + self.plugins):

            if True in self.skiplist: break

            name = getattr(p, 'name', False)

            if name and (name in self.skiplist or name in unique): continue

            if p in self.skiplist or type(p) in self.skiplist: continue

            if name: unique.add(name)

            yield p

    def _make_callback(self):

        callback = self.callback

        for plugin in self.all_plugins():

            try:

                if hasattr(plugin, 'apply'):

                    api = getattr(plugin, 'api', 1)

                    context = self if api > 1 else self._context

                    callback = plugin.apply(callback, context)

                else:

                    callback = plugin(callback)

            except RouteReset: # Try again with changed configuration.

                return self._make_callback()

            if not callback is self.callback:

                try_update_wrapper(callback, self.callback)

        return callback

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

# Application Object ###########################################################

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

class Bottle(object):

    """ WSGI application """

    def __init__(self, catchall=True, autojson=True, config=None):

        """ Create a new bottle instance.

            You usually don't do that. Use `bottle.app.push()` instead.

        """

        self.routes = [] # List of installed :class:`Route` instances.

        self.router = Router() # Maps requests to :class:`Route` instances.

        self.plugins = [] # List of installed plugins.

        self.error_handler = {}

        #: If true, most exceptions are catched and returned as :exc:`HTTPError`

        self.config = ConfigDict(config or {})

        self.catchall = catchall

        #: An instance of :class:`HooksPlugin`. Empty by default.

        self.hooks = HooksPlugin()

        self.install(self.hooks)

        if autojson:

            self.install(JSONPlugin())

        self.install(TemplatePlugin())

    def mount(self, prefix, app, **options):

        ''' Mount an application (:class:`Bottle` or plain WSGI) to a specific

            URL prefix. Example::

                root_app.mount('/admin/', admin_app)

            :param prefix: path prefix or `mount-point`. If it ends in a slash,

                that slash is mandatory.

            :param app: an instance of :class:`Bottle` or a WSGI application.

            All other parameters are passed to the underlying :meth:`route` call.

        '''

        if isinstance(app, basestring):

            prefix, app = app, prefix

            depr('Parameter order of Bottle.mount() changed.') # 0.10

        parts = filter(None, prefix.split('/'))

        if not parts: raise ValueError('Empty path prefix.')

        path_depth = len(parts)

        options.setdefault('skip', True)

        options.setdefault('method', 'ANY')

        @self.route('/%s/:#.*#' % '/'.join(parts), **options)

        def mountpoint():

            try:

                request.path_shift(path_depth)

                rs = BaseResponse([], 200)

                def start_response(status, header):

                    rs.status = status

                    for name, value in header: rs.add_header(name, value)

                    return rs.body.append

                rs.body = itertools.chain(rs.body, app(request.environ, start_response))

                return HTTPResponse(rs.body, rs.status_code, rs.headers)

            finally:

                request.path_shift(-path_depth)

        if not prefix.endswith('/'):

            self.route('/' + '/'.join(parts), callback=mountpoint, **options)

    def install(self, plugin):

        ''' Add a plugin to the list of plugins and prepare it for being

            applied to all routes of this application. A plugin may be a simple

            decorator or an object that implements the :class:`Plugin` API.

        '''

        if hasattr(plugin, 'setup'): plugin.setup(self)

        if not callable(plugin) and not hasattr(plugin, 'apply'):

            raise TypeError("Plugins must be callable or implement .apply()")

        self.plugins.append(plugin)

        self.reset()

        return plugin

    def uninstall(self, plugin):

        ''' Uninstall plugins. Pass an instance to remove a specific plugin, a type

            object to remove all plugins that match that type, a string to remove

            all plugins with a matching ``name`` attribute or ``True`` to remove all

            plugins. Return the list of removed plugins. '''

        removed, remove = [], plugin

        for i, plugin in list(enumerate(self.plugins))[::-1]:

            if remove is True or remove is plugin or remove is type(plugin) \

            or getattr(plugin, 'name', True) == remove:

                removed.append(plugin)

                del self.plugins[i]

                if hasattr(plugin, 'close'): plugin.close()

        if removed: self.reset()

        return removed

    def reset(self, route=None):

        ''' Reset all routes (force plugins to be re-applied) and clear all

            caches. If an ID or route object is given, only that specific route

            is affected. '''

        if route is None: routes = self.routes

        elif isinstance(route, Route): routes = [route]

        else: routes = [self.routes[route]]

        for route in routes: route.reset()

        if DEBUG:

            for route in routes: route.prepare()

        self.hooks.trigger('app_reset')

    def close(self):

        ''' Close the application and all installed plugins. '''

        for plugin in self.plugins:

            if hasattr(plugin, 'close'): plugin.close()

        self.stopped = True

    def match(self, environ):

        """ Search for a matching route and return a (:class:`Route` , urlargs)

            tuple. The second value is a dictionary with parameters extracted

            from the URL. Raise :exc:`HTTPError` (404/405) on a non-match."""

        return self.router.match(environ)

    def get_url(self, routename, **kargs):

        """ Return a string that matches a named route """

        scriptname = request.environ.get('SCRIPT_NAME', '').strip('/') + '/'

        location = self.router.build(routename, **kargs).lstrip('/')

        return urljoin(urljoin('/', scriptname), location)

    def route(self, path=None, method='GET', callback=None, name=None,

              apply=None, skip=None, **config):

        """ A decorator to bind a function to a request URL. Example::

                @app.route('/hello/:name')

                def hello(name):

                    return 'Hello %s' % name

            The ``:name`` part is a wildcard. See :class:`Router` for syntax

            details.

            :param path: Request path or a list of paths to listen to. If no

              path is specified, it is automatically generated from the

              signature of the function.

            :param method: HTTP method (`GET`, `POST`, `PUT`, ...) or a list of

              methods to listen to. (default: `GET`)

            :param callback: An optional shortcut to avoid the decorator

              syntax. ``route(..., callback=func)`` equals ``route(...)(func)``

            :param name: The name for this route. (default: None)

            :param apply: A decorator or plugin or a list of plugins. These are

              applied to the route callback in addition to installed plugins.

            :param skip: A list of plugins, plugin classes or names. Matching

              plugins are not installed to this route. ``True`` skips all.

            Any additional keyword arguments are stored as route-specific

            configuration and passed to plugins (see :meth:`Plugin.apply`).

        """

        if callable(path): path, callback = None, path

        plugins = makelist(apply)

        skiplist = makelist(skip)

        def decorator(callback):

            # TODO: Documentation and tests

            if isinstance(callback, basestring): callback = load(callback)

            for rule in makelist(path) or yieldroutes(callback):

                for verb in makelist(method):

                    verb = verb.upper()

                    route = Route(self, rule, verb, callback, name=name,

                                  plugins=plugins, skiplist=skiplist, **config)

                    self.routes.append(route)

                    self.router.add(rule, verb, route, name=name)

                    if DEBUG: route.prepare()

            return callback

        return decorator(callback) if callback else decorator

    def get(self, path=None, method='GET', **options):

        """ Equals :meth:`route`. """

        return self.route(path, method, **options)

    def post(self, path=None, method='POST', **options):

        """ Equals :meth:`route` with a ``POST`` method parameter. """

        return self.route(path, method, **options)

    def put(self, path=None, method='PUT', **options):

        """ Equals :meth:`route` with a ``PUT`` method parameter. """

        return self.route(path, method, **options)

    def delete(self, path=None, method='DELETE', **options):

        """ Equals :meth:`route` with a ``DELETE`` method parameter. """

        return self.route(path, method, **options)

    def error(self, code=500):

        """ Decorator: Register an output handler for a HTTP error code"""

        def wrapper(handler):

            self.error_handler[int(code)] = handler

            return handler

        return wrapper

    def hook(self, name):

        """ Return a decorator that attaches a callback to a hook. """

        def wrapper(func):

            self.hooks.add(name, func)

            return func

        return wrapper

    def handle(self, path, method='GET'):

        """ (deprecated) Execute the first matching route callback and return

            the result. :exc:`HTTPResponse` exceptions are catched and returned.

            If :attr:`Bottle.catchall` is true, other exceptions are catched as

            well and returned as :exc:`HTTPError` instances (500).

        """

        depr("This method will change semantics in 0.10. Try to avoid it.")

        if isinstance(path, dict):

            return self._handle(path)

        return self._handle({'PATH_INFO': path, 'REQUEST_METHOD': method.upper()})

    def _handle(self, environ):

        try:

            route, args = self.router.match(environ)

            environ['route.handle'] = environ['bottle.route'] = route

            environ['route.url_args'] = args

            return route.call(**args)

        except HTTPResponse, r:

            return r

        except RouteReset:

            route.reset()

            return self._handle(environ)

        except (KeyboardInterrupt, SystemExit, MemoryError):

            raise

        except Exception, e:

            if not self.catchall: raise

            stacktrace = format_exc(10)

            environ['wsgi.errors'].write(stacktrace)

            return HTTPError(500, "Internal Server Error", e, stacktrace)

    def _cast(self, out, request, response, peek=None):

        """ Try to convert the parameter into something WSGI compatible and set

        correct HTTP headers when possible.

        Support: False, str, unicode, dict, HTTPResponse, HTTPError, file-like,

        iterable of strings and iterable of unicodes

        """

        # Empty output is done here

        if not out:

            response['Content-Length'] = 0

            return []

        # Join lists of byte or unicode strings. Mixed lists are NOT supported

        if isinstance(out, (tuple, list))\

        and isinstance(out[0], (bytes, unicode)):

            out = out[0][0:0].join(out) # b'abc'[0:0] -> b''

        # Encode unicode strings

        if isinstance(out, unicode):

            out = out.encode(response.charset)

        # Byte Strings are just returned

        if isinstance(out, bytes):

            response['Content-Length'] = len(out)

            return [out]

        # HTTPError or HTTPException (recursive, because they may wrap anything)

        # TODO: Handle these explicitly in handle() or make them iterable.

        if isinstance(out, HTTPError):

            out.apply(response)

            out = self.error_handler.get(out.status, repr)(out)

            if isinstance(out, HTTPResponse):

                depr('Error handlers must not return :exc:`HTTPResponse`.') #0.9

            return self._cast(out, request, response)

        if isinstance(out, HTTPResponse):

            out.apply(response)

            return self._cast(out.output, request, response)

        # File-like objects.

        if hasattr(out, 'read'):

            if 'wsgi.file_wrapper' in request.environ:

                return request.environ['wsgi.file_wrapper'](out)

            elif hasattr(out, 'close') or not hasattr(out, '__iter__'):

                return WSGIFileWrapper(out)

        # Handle Iterables. We peek into them to detect their inner type.

        try:

            out = iter(out)

            first = out.next()

            while not first:

                first = out.next()

        except StopIteration:

            return self._cast('', request, response)

        except HTTPResponse, e:

            first = e

        except Exception, e:

            first = HTTPError(500, 'Unhandled exception', e, format_exc(10))

            if isinstance(e, (KeyboardInterrupt, SystemExit, MemoryError))\

            or not self.catchall:

                raise

        # These are the inner types allowed in iterator or generator objects.

        if isinstance(first, HTTPResponse):

            return self._cast(first, request, response)

        if isinstance(first, bytes):

            return itertools.chain([first], out)

        if isinstance(first, unicode):

            return itertools.imap(lambda x: x.encode(response.charset),

                                  itertools.chain([first], out))

        return self._cast(HTTPError(500, 'Unsupported response type: %s'\

                                         % type(first)), request, response)

    def wsgi(self, environ, start_response):

        """ The bottle WSGI-interface. """

        try:

            environ['bottle.app'] = self

            request.bind(environ)

            response.bind()

            out = self._cast(self._handle(environ), request, response)

            # rfc2616 section 4.3

            if response._status_code in (100, 101, 204, 304)\

            or request.method == 'HEAD':

                if hasattr(out, 'close'): out.close()

                out = []

            start_response(response._status_line, list(response.iter_headers()))

            return out

        except (KeyboardInterrupt, SystemExit, MemoryError):

            raise

        except Exception, e:

            if not self.catchall: raise

            err = '<h1>Critical error while processing request: %s</h1>' \

                  % html_escape(environ.get('PATH_INFO', '/'))

            if DEBUG:

                err += '<h2>Error:</h2>\n<pre>\n%s\n</pre>\n' \

                       '<h2>Traceback:</h2>\n<pre>\n%s\n</pre>\n' \

                       % (html_escape(repr(e)), html_escape(format_exc(10)))

            environ['wsgi.errors'].write(err)

            headers = [('Content-Type', 'text/html; charset=UTF-8')]

            start_response('500 INTERNAL SERVER ERROR', headers)

            return [tob(err)]

    def __call__(self, environ, start_response):

        ''' Each instance of :class:'Bottle' is a WSGI application. '''

        return self.wsgi(environ, start_response)

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

# HTTP and WSGI Tools ##########################################################

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

class BaseRequest(DictMixin):

    """ A wrapper for WSGI environment dictionaries that adds a lot of

        convenient access methods and properties. Most of them are read-only."""

    #: Maximum size of memory buffer for :attr:`body` in bytes.

    MEMFILE_MAX = 102400

    #: Maximum number pr GET or POST parameters per request

    MAX_PARAMS  = 100

    def __init__(self, environ):

        """ Wrap a WSGI environ dictionary. """

        #: The wrapped WSGI environ dictionary. This is the only real attribute.

        #: All other attributes actually are read-only properties.

        self.environ = environ

        environ['bottle.request'] = self

    @property

    def path(self):

        ''' The value of ``PATH_INFO`` with exactly one prefixed slash (to fix

            broken clients and avoid the "empty path" edge case). '''

        return '/' + self.environ.get('PATH_INFO','').lstrip('/')

    @property

    def method(self):

        ''' The ``REQUEST_METHOD`` value as an uppercase string. '''

        return self.environ.get('REQUEST_METHOD', 'GET').upper()

    @DictProperty('environ', 'bottle.request.headers', read_only=True)

    def headers(self):

        ''' A :class:`WSGIHeaderDict` that provides case-insensitive access to

            HTTP request headers. '''

        return WSGIHeaderDict(self.environ)

    def get_header(self, name, default=None):

        ''' Return the value of a request header, or a given default value. '''

        return self.headers.get(name, default)

    @DictProperty('environ', 'bottle.request.cookies', read_only=True)

    def cookies(self):

        """ Cookies parsed into a :class:`FormsDict`. Signed cookies are NOT

            decoded. Use :meth:`get_cookie` if you expect signed cookies. """

        cookies = SimpleCookie(self.environ.get('HTTP_COOKIE',''))

        cookies = list(cookies.values())[:self.MAX_PARAMS]

        return FormsDict((c.key, c.value) for c in cookies)

    def get_cookie(self, key, default=None, secret=None):

        """ Return the content of a cookie. To read a `Signed Cookie`, the

            `secret` must match the one used to create the cookie (see

            :meth:`BaseResponse.set_cookie`). If anything goes wrong (missing

            cookie or wrong signature), return a default value. """

        value = self.cookies.get(key)

        if secret and value:

            dec = cookie_decode(value, secret) # (key, value) tuple or None

            return dec[1] if dec and dec[0] == key else default

        return value or default

    @DictProperty('environ', 'bottle.request.query', read_only=True)

    def query(self):

        ''' The :attr:`query_string` parsed into a :class:`FormsDict`. These

            values are sometimes called "URL arguments" or "GET parameters", but

            not to be confused with "URL wildcards" as they are provided by the

            :class:`Router`. '''

        get = self.environ['bottle.get'] = FormsDict()

        pairs = _parse_qsl(self.environ.get('QUERY_STRING', ''))

        for key, value in pairs[:self.MAX_PARAMS]:

            get[key] = value

        return get

    @DictProperty('environ', 'bottle.request.forms', read_only=True)

    def forms(self):

        """ Form values parsed from an `url-encoded` or `multipart/form-data`

            encoded POST or PUT request body. The result is retuned as a

            :class:`FormsDict`. All keys and values are strings. File uploads

            are stored separately in :attr:`files`. """

        forms = FormsDict()

        for name, item in self.POST.iterallitems():

            if not hasattr(item, 'filename'):

                forms[name] = item

        return forms

    @DictProperty('environ', 'bottle.request.params', read_only=True)

    def params(self):

        """ A :class:`FormsDict` with the combined values of :attr:`query` and

            :attr:`forms`. File uploads are stored in :attr:`files`. """

        params = FormsDict()

        for key, value in self.query.iterallitems():

            params[key] = value

        for key, value in self.forms.iterallitems():

            params[key] = value

        return params

    @DictProperty('environ', 'bottle.request.files', read_only=True)

    def files(self):

        """ File uploads parsed from an `url-encoded` or `multipart/form-data`

            encoded POST or PUT request body. The values are instances of

            :class:`cgi.FieldStorage`. The most important attributes are:

            filename

                The filename, if specified; otherwise None; this is the client

                side filename, *not* the file name on which it is stored (that's

                a temporary file you don't deal with)

            file

                The file(-like) object from which you can read the data.

            value

                The value as a *string*; for file uploads, this transparently

                reads the file every time you request the value. Do not do this

                on big files.

        """

        files = FormsDict()

        for name, item in self.POST.iterallitems():

            if hasattr(item, 'filename'):

                files[name] = item

        return files

    @DictProperty('environ', 'bottle.request.json', read_only=True)

    def json(self):

        ''' If the ``Content-Type`` header is ``application/json``, this

            property holds the parsed content of the request body. Only requests

            smaller than :attr:`MEMFILE_MAX` are processed to avoid memory

            exhaustion. '''

        if 'application/json' in self.environ.get('CONTENT_TYPE', '') \

        and 0 < self.content_length < self.MEMFILE_MAX:

            return json_loads(self.body.read(self.MEMFILE_MAX))

        return None

    @DictProperty('environ', 'bottle.request.body', read_only=True)

    def _body(self):

        maxread = max(0, self.content_length)

        stream = self.environ['wsgi.input']

        body = BytesIO() if maxread < self.MEMFILE_MAX else TemporaryFile(mode='w+b')

        while maxread > 0:

            part = stream.read(min(maxread, self.MEMFILE_MAX))

            if not part: break

            body.write(part)

            maxread -= len(part)

        self.environ['wsgi.input'] = body

        body.seek(0)

        return body

    @property

    def body(self):

        """ The HTTP request body as a seek-able file-like object. Depending on

            :attr:`MEMFILE_MAX`, this is either a temporary file or a

            :class:`io.BytesIO` instance. Accessing this property for the first

            time reads and replaces the ``wsgi.input`` environ variable.

            Subsequent accesses just do a `seek(0)` on the file object. """

        self._body.seek(0)

        return self._body

    #: An alias for :attr:`query`.

    GET = query

    @DictProperty('environ', 'bottle.request.post', read_only=True)

    def POST(self):

        """ The values of :attr:`forms` and :attr:`files` combined into a single

            :class:`FormsDict`. Values are either strings (form values) or

            instances of :class:`cgi.FieldStorage` (file uploads).

        """

        post = FormsDict()

        # We default to application/x-www-form-urlencoded for everything that

        # is not multipart and take the fast path (also: 3.1 workaround)

        if not self.content_type.startswith('multipart/'):

            maxlen = max(0, min(self.content_length, self.MEMFILE_MAX))

            pairs = _parse_qsl(tonat(self.body.read(maxlen), 'latin1'))

            for key, value in pairs[:self.MAX_PARAMS]:

                post[key] = value

            return post

        safe_env = {'QUERY_STRING':''} # Build a safe environment for cgi

        for key in ('REQUEST_METHOD', 'CONTENT_TYPE', 'CONTENT_LENGTH'):

            if key in self.environ: safe_env[key] = self.environ[key]

        args = dict(fp=self.body, environ=safe_env, keep_blank_values=True)

        if py >= (3,2,0):

            args['encoding'] = 'ISO-8859-1'

        if NCTextIOWrapper:

            args['fp'] = NCTextIOWrapper(args['fp'], encoding='ISO-8859-1',

                                         newline='\n')

        data = cgi.FieldStorage(**args)

        for item in (data.list or [])[:self.MAX_PARAMS]:

            post[item.name] = item if item.filename else item.value

        return post

    @property

    def COOKIES(self):

        ''' Alias for :attr:`cookies` (deprecated). '''

        depr('BaseRequest.COOKIES was renamed to BaseRequest.cookies (lowercase).')

        return self.cookies

    @property

    def url(self):

        """ The full request URI including hostname and scheme. If your app

            lives behind a reverse proxy or load balancer and you get confusing

            results, make sure that the ``X-Forwarded-Host`` header is set

            correctly. """

        return self.urlparts.geturl()

    @DictProperty('environ', 'bottle.request.urlparts', read_only=True)

    def urlparts(self):

        ''' The :attr:`url` string as an :class:`urlparse.SplitResult` tuple.

            The tuple contains (scheme, host, path, query_string and fragment),

            but the fragment is always empty because it is not visible to the

            server. '''

        env = self.environ

        http = env.get('wsgi.url_scheme', 'http')

        host = env.get('HTTP_X_FORWARDED_HOST') or env.get('HTTP_HOST')

        if not host:

            # HTTP 1.1 requires a Host-header. This is for HTTP/1.0 clients.

            host = env.get('SERVER_NAME', '127.0.0.1')

            port = env.get('SERVER_PORT')

            if port and port != ('80' if http == 'http' else '443'):

                host += ':' + port

        path = urlquote(self.fullpath)

        return UrlSplitResult(http, host, path, env.get('QUERY_STRING'), '')

    @property

    def fullpath(self):

        """ Request path including :attr:`script_name` (if present). """

        return urljoin(self.script_name, self.path.lstrip('/'))

    @property

    def query_string(self):

        """ The raw :attr:`query` part of the URL (everything in between ``?``

            and ``#``) as a string. """

        return self.environ.get('QUERY_STRING', '')

    @property

    def script_name(self):

        ''' The initial portion of the URL's `path` that was removed by a higher

            level (server or routing middleware) before the application was

            called. This script path is returned with leading and tailing

            slashes. '''

        script_name = self.environ.get('SCRIPT_NAME', '').strip('/')

        return '/' + script_name + '/' if script_name else '/'

    def path_shift(self, shift=1):

        ''' Shift path segments from :attr:`path` to :attr:`script_name` and

            vice versa.

           :param shift: The number of path segments to shift. May be negative

                         to change the shift direction. (default: 1)

        '''

        script = self.environ.get('SCRIPT_NAME','/')

        self['SCRIPT_NAME'], self['PATH_INFO'] = path_shift(script, self.path, shift)

    @property

    def content_length(self):

        ''' The request body length as an integer. The client is responsible to

            set this header. Otherwise, the real length of the body is unknown

            and -1 is returned. In this case, :attr:`body` will be empty. '''

        return int(self.environ.get('CONTENT_LENGTH') or -1)

    @property

    def content_type(self):

        ''' The Content-Type header as a lowercase-string (default: empty). '''

        return self.environ.get('CONTENT_TYPE', '').lower()

    @property

    def is_xhr(self):

        ''' True if the request was triggered by a XMLHttpRequest. This only

            works with JavaScript libraries that support the `X-Requested-With`

            header (most of the popular libraries do). '''

        requested_with = self.environ.get('HTTP_X_REQUESTED_WITH','')

        return requested_with.lower() == 'xmlhttprequest'

    @property

    def is_ajax(self):

        ''' Alias for :attr:`is_xhr`. "Ajax" is not the right term. '''

        return self.is_xhr

    @property

    def auth(self):

        """ HTTP authentication data as a (user, password) tuple. This