Update Flask

libs/flask/__init__.py

@@ -10,7 +10,7 @@
     :license: BSD, see LICENSE for more details.
 """
 
-__version__ = '0.9-dev'
+__version__ = '0.9'
 
 # utilities we import from Werkzeug and Jinja2 that are unused
 # in the module but are exported as public interface.
@@ -22,9 +22,12 @@ from .app import Flask, Request, Response
 from .config import Config
 from .helpers import url_for, jsonify, json_available, flash, \
     send_file, send_from_directory, get_flashed_messages, \
-    get_template_attribute, make_response, safe_join
-from .globals import current_app, g, request, session, _request_ctx_stack
-from .ctx import has_request_context
+    get_template_attribute, make_response, safe_join, \
+    stream_with_context
+from .globals import current_app, g, request, session, _request_ctx_stack, \
+     _app_ctx_stack
+from .ctx import has_request_context, has_app_context, \
+     after_this_request
 from .module import Module
 from .blueprints import Blueprint
 from .templating import render_template, render_template_string

libs/flask/app.py

@@ -19,7 +19,7 @@ from itertools import chain
 from functools import update_wrapper
 
 from werkzeug.datastructures import ImmutableDict
-from werkzeug.routing import Map, Rule, RequestRedirect
+from werkzeug.routing import Map, Rule, RequestRedirect, BuildError
 from werkzeug.exceptions import HTTPException, InternalServerError, \
      MethodNotAllowed, BadRequest
 
@@ -28,14 +28,14 @@ from .helpers import _PackageBoundObject, url_for, get_flashed_messages, \
     find_package
 from .wrappers import Request, Response
 from .config import ConfigAttribute, Config
-from .ctx import RequestContext
+from .ctx import RequestContext, AppContext, _RequestGlobals
 from .globals import _request_ctx_stack, request
 from .sessions import SecureCookieSessionInterface
 from .module import blueprint_is_module
 from .templating import DispatchingJinjaLoader, Environment, \
     _default_template_ctx_processor
 from .signals import request_started, request_finished, got_request_exception, \
-    request_tearing_down
+    request_tearing_down, appcontext_tearing_down
 
 # a lock used for logger initialization
 _logger_lock = Lock()
@@ -148,6 +148,18 @@ class Flask(_PackageBoundObject):
     #: :class:`~flask.Response` for more information.
     response_class = Response
 
+    #: The class that is used for the :data:`~flask.g` instance.
+    #:
+    #: Example use cases for a custom class:
+    #:
+    #: 1. Store arbitrary attributes on flask.g.
+    #: 2. Add a property for lazy per-request database connectors.
+    #: 3. Return None instead of AttributeError on expected attributes.
+    #: 4. Raise exception if an unexpected attr is set, a "controlled" flask.g.
+    #:
+    #: .. versionadded:: 0.9
+    request_globals_class = _RequestGlobals
+
     #: The debug flag.  Set this to `True` to enable debugging of the
     #: application.  In debug mode the debugger will kick in when an unhandled
     #: exception ocurrs and the integrated server will automatically reload
@@ -249,8 +261,10 @@ class Flask(_PackageBoundObject):
         'SESSION_COOKIE_HTTPONLY':              True,
         'SESSION_COOKIE_SECURE':                False,
         'MAX_CONTENT_LENGTH':                   None,
+        'SEND_FILE_MAX_AGE_DEFAULT':            12 * 60 * 60, # 12 hours
         'TRAP_BAD_REQUEST_ERRORS':              False,
-        'TRAP_HTTP_EXCEPTIONS':                 False
+        'TRAP_HTTP_EXCEPTIONS':                 False,
+        'PREFERRED_URL_SCHEME':                 'http'
     })
 
     #: The rule object to use for URL rules created.  This is used by
@@ -327,6 +341,15 @@ class Flask(_PackageBoundObject):
         #: decorator.
         self.error_handler_spec = {None: self._error_handlers}
 
+        #: A list of functions that are called when :meth:`url_for` raises a
+        #: :exc:`~werkzeug.routing.BuildError`.  Each function registered here
+        #: is called with `error`, `endpoint` and `values`.  If a function
+        #: returns `None` or raises a `BuildError` the next function is
+        #: tried.
+        #:
+        #: .. versionadded:: 0.9
+        self.url_build_error_handlers = []
+
         #: A dictionary with lists of functions that should be called at the
         #: beginning of the request.  The key of the dictionary is the name of
         #: the blueprint this function is active for, `None` for all requests.
@@ -362,6 +385,14 @@ class Flask(_PackageBoundObject):
         #: .. versionadded:: 0.7
         self.teardown_request_funcs = {}
 
+        #: A list of functions that are called when the application context
+        #: is destroyed.  Since the application context is also torn down
+        #: if the request ends this is the place to store code that disconnects
+        #: from databases.
+        #:
+        #: .. versionadded:: 0.9
+        self.teardown_appcontext_funcs = []
+
         #: A dictionary with lists of functions that can be used as URL
         #: value processor functions.  Whenever a URL is built these functions
         #: are called to modify the dictionary of values in place.  The key
@@ -884,6 +915,10 @@ class Flask(_PackageBoundObject):
         # a tuple of only `GET` as default.
         if methods is None:
             methods = getattr(view_func, 'methods', None) or ('GET',)
+        methods = set(methods)
+
+        # Methods that should always be added
+        required_methods = set(getattr(view_func, 'required_methods', ()))
 
         # starting with Flask 0.8 the view_func object can disable and
         # force-enable the automatic options handling.
@@ -892,11 +927,14 @@ class Flask(_PackageBoundObject):
 
         if provide_automatic_options is None:
             if 'OPTIONS' not in methods:
-                methods = tuple(methods) + ('OPTIONS',)
                 provide_automatic_options = True
+                required_methods.add('OPTIONS')
             else:
                 provide_automatic_options = False
 
+        # Add the required methods now.
+        methods |= required_methods
+
         # due to a werkzeug bug we need to make sure that the defaults are
         # None if they are an empty dictionary.  This should not be necessary
         # with Werkzeug 0.7
@@ -1098,10 +1136,42 @@ class Flask(_PackageBoundObject):
         that they will fail.  If they do execute code that might fail they
         will have to surround the execution of these code by try/except
         statements and log ocurring errors.
+
+        When a teardown function was called because of a exception it will
+        be passed an error object.
         """
         self.teardown_request_funcs.setdefault(None, []).append(f)
         return f
 
+    @setupmethod
+    def teardown_appcontext(self, f):
+        """Registers a function to be called when the application context
+        ends.  These functions are typically also called when the request
+        context is popped.
+
+        Example::
+
+            ctx = app.app_context()
+            ctx.push()
+            ...
+            ctx.pop()
+
+        When ``ctx.pop()`` is executed in the above example, the teardown
+        functions are called just before the app context moves from the
+        stack of active contexts.  This becomes relevant if you are using
+        such constructs in tests.
+
+        Since a request context typically also manages an application
+        context it would also be called when you pop a request context.
+
+        When a teardown function was called because of an exception it will
+        be passed an error object.
+
+        .. versionadded:: 0.9
+        """
+        self.teardown_appcontext_funcs.append(f)
+        return f
+
     @setupmethod
     def context_processor(self, f):
         """Registers a template context processor function."""
@@ -1312,7 +1382,7 @@ class Flask(_PackageBoundObject):
     def make_default_options_response(self):
         """This method is called to create the default `OPTIONS` response.
         This can be changed through subclassing to change the default
-        behaviour of `OPTIONS` responses.
+        behavior of `OPTIONS` responses.
 
         .. versionadded:: 0.7
         """
@@ -1346,23 +1416,48 @@ class Flask(_PackageBoundObject):
                                 string as body
         :class:`unicode`        a response object is created with the
                                 string encoded to utf-8 as body
-        :class:`tuple`          the response object is created with the
-                                contents of the tuple as arguments
         a WSGI function         the function is called as WSGI application
                                 and buffered as response object
+        :class:`tuple`          A tuple in the form ``(response, status,
+                                headers)`` where `response` is any of the
+                                types defined here, `status` is a string
+                                or an integer and `headers` is a list of
+                                a dictionary with header values.
         ======================= ===========================================
 
         :param rv: the return value from the view function
+
+        .. versionchanged:: 0.9
+           Previously a tuple was interpreted as the arguments for the
+           response object.
         """
+        status = headers = None
+        if isinstance(rv, tuple):
+            rv, status, headers = rv + (None,) * (3 - len(rv))
+
         if rv is None:
             raise ValueError('View function did not return a response')
-        if isinstance(rv, self.response_class):
-            return rv
-        if isinstance(rv, basestring):
-            return self.response_class(rv)
-        if isinstance(rv, tuple):
-            return self.response_class(*rv)
-        return self.response_class.force_type(rv, request.environ)
+
+        if not isinstance(rv, self.response_class):
+            # When we create a response object directly, we let the constructor
+            # set the headers and status.  We do this because there can be
+            # some extra logic involved when creating these objects with
+            # specific values (like defualt content type selection).
+            if isinstance(rv, basestring):
+                rv = self.response_class(rv, headers=headers, status=status)
+                headers = status = None
+            else:
+                rv = self.response_class.force_type(rv, request.environ)
+
+        if status is not None:
+            if isinstance(status, basestring):
+                rv.status = status
+            else:
+                rv.status_code = status
+        if headers:
+            rv.headers.extend(headers)
+
+        return rv
 
     def create_url_adapter(self, request):
         """Creates a URL adapter for the given request.  The URL adapter
@@ -1370,9 +1465,21 @@ class Flask(_PackageBoundObject):
         so the request is passed explicitly.
 
         .. versionadded:: 0.6
+
+        .. versionchanged:: 0.9
+           This can now also be called without a request object when the
+           UR adapter is created for the application context.
         """
-        return self.url_map.bind_to_environ(request.environ,
-            server_name=self.config['SERVER_NAME'])
+        if request is not None:
+            return self.url_map.bind_to_environ(request.environ,
+                server_name=self.config['SERVER_NAME'])
+        # We need at the very least the server name to be set for this
+        # to work.
+        if self.config['SERVER_NAME'] is not None:
+            return self.url_map.bind(
+                self.config['SERVER_NAME'],
+                script_name=self.config['APPLICATION_ROOT'] or '/',
+                url_scheme=self.config['PREFERRED_URL_SCHEME'])
 
     def inject_url_defaults(self, endpoint, values):
         """Injects the URL defaults for the given endpoint directly into
@@ -1383,11 +1490,30 @@ class Flask(_PackageBoundObject):
         """
         funcs = self.url_default_functions.get(None, ())
         if '.' in endpoint:
-            bp = endpoint.split('.', 1)[0]
+            bp = endpoint.rsplit('.', 1)[0]
             funcs = chain(funcs, self.url_default_functions.get(bp, ()))
         for func in funcs:
             func(endpoint, values)
 
+    def handle_url_build_error(self, error, endpoint, values):
+        """Handle :class:`~werkzeug.routing.BuildError` on :meth:`url_for`.
+        """
+        exc_type, exc_value, tb = sys.exc_info()
+        for handler in self.url_build_error_handlers:
+            try:
+                rv = handler(error, endpoint, values)
+                if rv is not None:
+                    return rv
+            except BuildError, error:
+                pass
+
+        # At this point we want to reraise the exception.  If the error is
+        # still the same one we can reraise it with the original traceback,
+        # otherwise we raise it from here.
+        if error is exc_value:
+            raise exc_type, exc_value, tb
+        raise error
+
     def preprocess_request(self):
         """Called before the actual request dispatching and will
         call every as :meth:`before_request` decorated function.
@@ -1429,7 +1555,7 @@ class Flask(_PackageBoundObject):
         """
         ctx = _request_ctx_stack.top
         bp = ctx.request.blueprint
-        funcs = ()
+        funcs = ctx._after_request_functions
         if bp is not None and bp in self.after_request_funcs:
             funcs = reversed(self.after_request_funcs[bp])
         if None in self.after_request_funcs:
@@ -1440,23 +1566,54 @@ class Flask(_PackageBoundObject):
             self.save_session(ctx.session, response)
         return response
 
-    def do_teardown_request(self):
+    def do_teardown_request(self, exc=None):
         """Called after the actual request dispatching and will
         call every as :meth:`teardown_request` decorated function.  This is
         not actually called by the :class:`Flask` object itself but is always
         triggered when the request context is popped.  That way we have a
         tighter control over certain resources under testing environments.
+
+        .. versionchanged:: 0.9
+           Added the `exc` argument.  Previously this was always using the
+           current exception information.
         """
+        if exc is None:
+            exc = sys.exc_info()[1]
         funcs = reversed(self.teardown_request_funcs.get(None, ()))
         bp = _request_ctx_stack.top.request.blueprint
         if bp is not None and bp in self.teardown_request_funcs:
             funcs = chain(funcs, reversed(self.teardown_request_funcs[bp]))
-        exc = sys.exc_info()[1]
         for func in funcs:
             rv = func(exc)
-            if rv is not None:
-                return rv
-        request_tearing_down.send(self)
+        request_tearing_down.send(self, exc=exc)
+
+    def do_teardown_appcontext(self, exc=None):
+        """Called when an application context is popped.  This works pretty
+        much the same as :meth:`do_teardown_request` but for the application
+        context.
+
+        .. versionadded:: 0.9
+        """
+        if exc is None:
+            exc = sys.exc_info()[1]
+        for func in reversed(self.teardown_appcontext_funcs):
+            func(exc)
+        appcontext_tearing_down.send(self, exc=exc)
+
+    def app_context(self):
+        """Binds the application only.  For as long as the application is bound
+        to the current context the :data:`flask.current_app` points to that
+        application.  An application context is automatically created when a
+        request context is pushed if necessary.
+
+        Example usage::
+
+            with app.app_context():
+                ...
+
+        .. versionadded:: 0.9
+        """
+        return AppContext(self)
 
     def request_context(self, environ):
         """Creates a :class:`~flask.ctx.RequestContext` from the given

libs/flask/blueprints.py

@@ -25,7 +25,7 @@ class BlueprintSetupState(object):
         #: a reference to the current application
         self.app = app
 
-        #: a reference to the blurprint that created this setup state.
+        #: a reference to the blueprint that created this setup state.
         self.blueprint = blueprint
 
         #: a dictionary with all options that were passed to the

libs/flask/config.py

@@ -106,8 +106,7 @@ class Config(dict):
                                'loaded.  Set this variable and make it '
                                'point to a configuration file' %
                                variable_name)
-        self.from_pyfile(rv)
-        return True
+        return self.from_pyfile(rv, silent=silent)
 
     def from_pyfile(self, filename, silent=False):
         """Updates the values in the config from a Python file.  This function

libs/flask/ctx.py

@@ -9,16 +9,44 @@
     :license: BSD, see LICENSE for more details.
 """
 
+import sys
+
 from werkzeug.exceptions import HTTPException
 
-from .globals import _request_ctx_stack
+from .globals import _request_ctx_stack, _app_ctx_stack
 from .module import blueprint_is_module
 
 
 class _RequestGlobals(object):
+    """A plain object."""
     pass
 
 
+def after_this_request(f):
+    """Executes a function after this request.  This is useful to modify
+    response objects.  The function is passed the response object and has
+    to return the same or a new one.
+
+    Example::
+
+        @app.route('/')
+        def index():
+            @after_this_request
+            def add_header(response):
+                response.headers['X-Foo'] = 'Parachute'
+                return response
+            return 'Hello World!'
+
+    This is more useful if a function other than the view function wants to
+    modify a response.  For instance think of a decorator that wants to add
+    some headers without converting the return value into a response object.
+
+    .. versionadded:: 0.9
+    """
+    _request_ctx_stack.top._after_request_functions.append(f)
+    return f
+
+
 def has_request_context():
     """If you have code that wants to test if a request context is there or
     not this function can be used.  For instance, you may want to take advantage
@@ -51,6 +79,57 @@ def has_request_context():
     return _request_ctx_stack.top is not None
 
 
+def has_app_context():
+    """Works like :func:`has_request_context` but for the application
+    context.  You can also just do a boolean check on the
+    :data:`current_app` object instead.
+
+    .. versionadded:: 0.9
+    """
+    return _app_ctx_stack.top is not None
+
+
+class AppContext(object):
+    """The application context binds an application object implicitly
+    to the current thread or greenlet, similar to how the
+    :class:`RequestContext` binds request information.  The application
+    context is also implicitly created if a request context is created
+    but the application is not on top of the individual application
+    context.
+    """
+
+    def __init__(self, app):
+        self.app = app
+        self.url_adapter = app.create_url_adapter(None)
+
+        # Like request context, app contexts can be pushed multiple times
+        # but there a basic "refcount" is enough to track them.
+        self._refcnt = 0
+
+    def push(self):
+        """Binds the app context to the current context."""
+        self._refcnt += 1
+        _app_ctx_stack.push(self)
+
+    def pop(self, exc=None):
+        """Pops the app context."""
+        self._refcnt -= 1
+        if self._refcnt <= 0:
+            if exc is None:
+                exc = sys.exc_info()[1]
+            self.app.do_teardown_appcontext(exc)
+        rv = _app_ctx_stack.pop()
+        assert rv is self, 'Popped wrong app context.  (%r instead of %r)' \
+            % (rv, self)
+
+    def __enter__(self):
+        self.push()
+        return self
+
+    def __exit__(self, exc_type, exc_value, tb):
+        self.pop(exc_value)
+
+
 class RequestContext(object):
     """The request context contains all request relevant information.  It is
     created at the beginning of the request and pushed to the
@@ -85,17 +164,28 @@ class RequestContext(object):
         self.app = app
         self.request = app.request_class(environ)
         self.url_adapter = app.create_url_adapter(self.request)
-        self.g = _RequestGlobals()
+        self.g = app.request_globals_class()
         self.flashes = None
         self.session = None
 
+        # Request contexts can be pushed multiple times and interleaved with
+        # other request contexts.  Now only if the last level is popped we
+        # get rid of them.  Additionally if an application context is missing
+        # one is created implicitly so for each level we add this information
+        self._implicit_app_ctx_stack = []
+
         # indicator if the context was preserved.  Next time another context
         # is pushed the preserved context is popped.
         self.preserved = False
 
+        # Functions that should be executed after the request on the response
+        # object.  These will be called before the regular "after_request"
+        # functions.
+        self._after_request_functions = []
+
         self.match_request()
 
-        # XXX: Support for deprecated functionality.  This is doing away with
+        # XXX: Support for deprecated functionality.  This is going away with
         # Flask 1.0
         blueprint = self.request.blueprint
         if blueprint is not None:
@@ -130,6 +220,16 @@ class RequestContext(object):
         if top is not None and top.preserved:
             top.pop()
 
+        # Before we push the request context we have to ensure that there
+        # is an application context.
+        app_ctx = _app_ctx_stack.top
+        if app_ctx is None or app_ctx.app != self.app:
+            app_ctx = self.app.app_context()
+            app_ctx.push()
+            self._implicit_app_ctx_stack.append(app_ctx)
+        else:
+            self._implicit_app_ctx_stack.append(None)
+
         _request_ctx_stack.push(self)
 
         # Open the session at the moment that the request context is
@@ -139,20 +239,36 @@ class RequestContext(object):
         if self.session is None:
             self.session = self.app.make_null_session()
 
-    def pop(self):
+    def pop(self, exc=None):
         """Pops the request context and unbinds it by doing that.  This will
         also trigger the execution of functions registered by the
         :meth:`~flask.Flask.teardown_request` decorator.
+
+        .. versionchanged:: 0.9
+           Added the `exc` argument.
         """
-        self.preserved = False
-        self.app.do_teardown_request()
+        app_ctx = self._implicit_app_ctx_stack.pop()
+
+        clear_request = False
+        if not self._implicit_app_ctx_stack:
+            self.preserved = False
+            if exc is None:
+                exc = sys.exc_info()[1]
+            self.app.do_teardown_request(exc)
+            clear_request = True
+
         rv = _request_ctx_stack.pop()
         assert rv is self, 'Popped wrong request context.  (%r instead of %r)' \
             % (rv, self)
 
         # get rid of circular dependencies at the end of the request
         # so that we don't require the GC to be active.
-        rv.request.environ['werkzeug.request'] = None
+        if clear_request:
+            rv.request.environ['werkzeug.request'] = None
+
+        # Get rid of the app as well if necessary.
+        if app_ctx is not None:
+            app_ctx.pop(exc)
 
     def __enter__(self):
         self.push()
@@ -168,7 +284,7 @@ class RequestContext(object):
            (tb is not None and self.app.preserve_context_on_exception):
             self.preserved = True
         else:
-            self.pop()
+            self.pop(exc_value)
 
     def __repr__(self):
         return '<%s \'%s\' [%s] of %s>' % (

libs/flask/exceptions.py

@@ -0,0 +1,49 @@
+# -*- coding: utf-8 -*-
+"""
+    flask.exceptions
+    ~~~~~~~~~~~~
+
+    Flask specific additions to :class:`~werkzeug.exceptions.HTTPException`
+
+    :copyright: (c) 2011 by Armin Ronacher.
+    :license: BSD, see LICENSE for more details.
+"""
+from werkzeug.exceptions import HTTPException, BadRequest
+from .helpers import json
+
+
+class JSONHTTPException(HTTPException):
+    """A base class for HTTP exceptions with ``Content-Type:
+    application/json``.
+
+    The ``description`` attribute of this class must set to a string (*not* an
+    HTML string) which describes the error.
+
+    """
+
+    def get_body(self, environ):
+        """Overrides :meth:`werkzeug.exceptions.HTTPException.get_body` to
+        return the description of this error in JSON format instead of HTML.
+
+        """
+        return json.dumps(dict(description=self.get_description(environ)))
+
+    def get_headers(self, environ):
+        """Returns a list of headers including ``Content-Type:
+        application/json``.
+
+        """
+        return [('Content-Type', 'application/json')]
+
+
+class JSONBadRequest(JSONHTTPException, BadRequest):
+    """Represents an HTTP ``400 Bad Request`` error whose body contains an
+    error message in JSON format instead of HTML format (as in the superclass).
+
+    """
+
+    #: The description of the error which occurred as a string.
+    description = (
+        'The browser (or proxy) sent a request that this server could not '
+        'understand.'
+    )

libs/flask/globals.py

@@ -20,9 +20,17 @@ def _lookup_object(name):
     return getattr(top, name)
 
 
+def _find_app():
+    top = _app_ctx_stack.top
+    if top is None:
+        raise RuntimeError('working outside of application context')
+    return top.app
+
+
 # context locals
 _request_ctx_stack = LocalStack()
-current_app = LocalProxy(partial(_lookup_object, 'app'))
+_app_ctx_stack = LocalStack()
+current_app = LocalProxy(_find_app)
 request = LocalProxy(partial(_lookup_object, 'request'))
 session = LocalProxy(partial(_lookup_object, 'session'))
 g = LocalProxy(partial(_lookup_object, 'g'))

libs/flask/helpers.py

@@ -11,7 +11,6 @@
 
 from __future__ import with_statement
 
-import imp
 import os
 import sys
 import pkgutil
@@ -20,7 +19,9 @@ import mimetypes
 from time import time
 from zlib import adler32
 from threading import RLock
+from werkzeug.routing import BuildError
 from werkzeug.urls import url_quote
+from functools import update_wrapper
 
 # try to load the best simplejson implementation available.  If JSON
 # is not installed, we add a failing class.
@@ -50,7 +51,8 @@ except ImportError:
 
 from jinja2 import FileSystemLoader
 
-from .globals import session, _request_ctx_stack, current_app, request
+from .globals import session, _request_ctx_stack, _app_ctx_stack, \
+     current_app, request
 
 
 def _assert_have_json():
@@ -59,7 +61,7 @@ def _assert_have_json():
         raise RuntimeError('simplejson not installed')
 
 
-# figure out if simplejson escapes slashes.  This behaviour was changed
+# figure out if simplejson escapes slashes.  This behavior was changed
 # from one version to another without reason.
 if not json_available or '\\/' not in json.dumps('/'):
 
@@ -91,6 +93,78 @@ def _endpoint_from_view_func(view_func):
     return view_func.__name__
 
 
+def stream_with_context(generator_or_function):
+    """Request contexts disappear when the response is started on the server.
+    This is done for efficiency reasons and to make it less likely to encounter
+    memory leaks with badly written WSGI middlewares.  The downside is that if
+    you are using streamed responses, the generator cannot access request bound
+    information any more.
+
+    This function however can help you keep the context around for longer::
+
+        from flask import stream_with_context, request, Response
+
+        @app.route('/stream')
+        def streamed_response():
+            @stream_with_context
+            def generate():
+                yield 'Hello '
+                yield request.args['name']
+                yield '!'
+            return Response(generate())
+
+    Alternatively it can also be used around a specific generator:
+
+        from flask import stream_with_context, request, Response
+
+        @app.route('/stream')
+        def streamed_response():
+            def generate():
+                yield 'Hello '
+                yield request.args['name']
+                yield '!'
+            return Response(stream_with_context(generate()))
+
+    .. versionadded:: 0.9
+    """
+    try:
+        gen = iter(generator_or_function)
+    except TypeError:
+        def decorator(*args, **kwargs):
+            gen = generator_or_function()
+            return stream_with_context(gen)
+        return update_wrapper(decorator, generator_or_function)
+
+    def generator():
+        ctx = _request_ctx_stack.top
+        if ctx is None:
+            raise RuntimeError('Attempted to stream with context but '
+                'there was no context in the first place to keep around.')
+        with ctx:
+            # Dummy sentinel.  Has to be inside the context block or we're
+            # not actually keeping the context around.
+            yield None
+
+            # The try/finally is here so that if someone passes a WSGI level
+            # iterator in we're still running the cleanup logic.  Generators
+            # don't need that because they are closed on their destruction
+            # automatically.
+            try:
+                for item in gen:
+                    yield item
+            finally:
+                if hasattr(gen, 'close'):
+                    gen.close()
+
+    # The trick is to start the generator.  Then the code execution runs until
+    # the first dummy None is yielded at which point the context was already
+    # pushed.  This item is discarded.  Then when the iteration continues the
+    # real generator is executed.
+    wrapped_g = generator()
+    wrapped_g.next()
+    return wrapped_g
+
+
 def jsonify(*args, **kwargs):
     """Creates a :class:`~flask.Response` with the JSON representation of
     the given arguments with an `application/json` mimetype.  The arguments
@@ -188,36 +262,106 @@ def url_for(endpoint, **values):
 
     For more information, head over to the :ref:`Quickstart <url-building>`.
 
+    To integrate applications, :class:`Flask` has a hook to intercept URL build
+    errors through :attr:`Flask.build_error_handler`.  The `url_for` function
+    results in a :exc:`~werkzeug.routing.BuildError` when the current app does
+    not have a URL for the given endpoint and values.  When it does, the
+    :data:`~flask.current_app` calls its :attr:`~Flask.build_error_handler` if
+    it is not `None`, which can return a string to use as the result of
+    `url_for` (instead of `url_for`'s default to raise the
+    :exc:`~werkzeug.routing.BuildError` exception) or re-raise the exception.
+    An example::
+
+        def external_url_handler(error, endpoint, **values):
+            "Looks up an external URL when `url_for` cannot build a URL."
+            # This is an example of hooking the build_error_handler.
+            # Here, lookup_url is some utility function you've built
+            # which looks up the endpoint in some external URL registry.
+            url = lookup_url(endpoint, **values)
+            if url is None:
+                # External lookup did not have a URL.
+                # Re-raise the BuildError, in context of original traceback.
+                exc_type, exc_value, tb = sys.exc_info()
+                if exc_value is error:
+                    raise exc_type, exc_value, tb
+                else:
+                    raise error
+            # url_for will use this result, instead of raising BuildError.
+            return url
+
+        app.build_error_handler = external_url_handler
+
+    Here, `error` is the instance of :exc:`~werkzeug.routing.BuildError`, and
+    `endpoint` and `**values` are the arguments passed into `url_for`.  Note
+    that this is for building URLs outside the current application, and not for
+    handling 404 NotFound errors.
+
     .. versionadded:: 0.9
        The `_anchor` and `_method` parameters were added.
 
+    .. versionadded:: 0.9
+       Calls :meth:`Flask.handle_build_error` on
+       :exc:`~werkzeug.routing.BuildError`.
+
     :param endpoint: the endpoint of the URL (name of the function)
     :param values: the variable arguments of the URL rule
     :param _external: if set to `True`, an absolute URL is generated.
     :param _anchor: if provided this is added as anchor to the URL.
     :param _method: if provided this explicitly specifies an HTTP method.
     """
-    ctx = _request_ctx_stack.top
-    blueprint_name = request.blueprint
-    if not ctx.request._is_old_module:
-        if endpoint[:1] == '.':
-            if blueprint_name is not None:
-                endpoint = blueprint_name + endpoint
-            else:
+    appctx = _app_ctx_stack.top
+    reqctx = _request_ctx_stack.top
+    if appctx is None:
+        raise RuntimeError('Attempted to generate a URL with the application '
+                           'context being pushed.  This has to be executed ')
+
+    # If request specific information is available we have some extra
+    # features that support "relative" urls.
+    if reqctx is not None:
+        url_adapter = reqctx.url_adapter
+        blueprint_name = request.blueprint
+        if not reqctx.request._is_old_module:
+            if endpoint[:1] == '.':
+                if blueprint_name is not None:
+                    endpoint = blueprint_name + endpoint
+                else:
+                    endpoint = endpoint[1:]
+        else:
+            # TODO: get rid of this deprecated functionality in 1.0
+            if '.' not in endpoint:
+                if blueprint_name is not None:
+                    endpoint = blueprint_name + '.' + endpoint
+            elif endpoint.startswith('.'):
                 endpoint = endpoint[1:]
+        external = values.pop('_external', False)
+
+    # Otherwise go with the url adapter from the appctx and make
+    # the urls external by default.
     else:
-        # TODO: get rid of this deprecated functionality in 1.0
-        if '.' not in endpoint:
-            if blueprint_name is not None:
-                endpoint = blueprint_name + '.' + endpoint
-        elif endpoint.startswith('.'):
-            endpoint = endpoint[1:]
-    external = values.pop('_external', False)
+        url_adapter = appctx.url_adapter
+        if url_adapter is None:
+            raise RuntimeError('Application was not able to create a URL '
+                               'adapter for request independent URL generation. '
+                               'You might be able to fix this by setting '
+                               'the SERVER_NAME config variable.')
+        external = values.pop('_external', True)
+
     anchor = values.pop('_anchor', None)
     method = values.pop('_method', None)
-    ctx.app.inject_url_defaults(endpoint, values)
-    rv = ctx.url_adapter.build(endpoint, values, method=method,
+    appctx.app.inject_url_defaults(endpoint, values)
+    try:
+        rv = url_adapter.build(endpoint, values, method=method,
                                force_external=external)
+    except BuildError, error:
+        # We need to inject the values again so that the app callback can
+        # deal with that sort of stuff.
+        values['_external'] = external
+        values['_anchor'] = anchor
+        values['_method'] = method
+        return appctx.app.handle_url_build_error(error, endpoint, values)
+
+    rv = url_adapter.build(endpoint, values, method=method,
+                           force_external=external)
     if anchor is not None:
         rv += '#' + url_quote(anchor)
     return rv
@@ -261,7 +405,16 @@ def flash(message, category='message'):
                      messages and ``'warning'`` for warnings.  However any
                      kind of string can be used as category.
     """
-    session.setdefault('_flashes', []).append((category, message))
+    # Original implementation:
+    #
+    #     session.setdefault('_flashes', []).append((category, message))
+    #
+    # This assumed that changes made to mutable structures in the session are
+    # are always in sync with the sess on object, which is not true for session
+    # implementations that use external storage for keeping their keys/values.
+    flashes = session.get('_flashes', [])
+    flashes.append((category, message))
+    session['_flashes'] = flashes
 
 
 def get_flashed_messages(with_categories=False, category_filter=[]):
@@ -305,7 +458,7 @@ def get_flashed_messages(with_categories=False, category_filter=[]):
 
 def send_file(filename_or_fp, mimetype=None, as_attachment=False,
               attachment_filename=None, add_etags=True,
-              cache_timeout=60 * 60 * 12, conditional=False):
+              cache_timeout=None, conditional=False):
     """Sends the contents of a file to the client.  This will use the
     most efficient method available and configured.  By default it will
     try to use the WSGI server's file_wrapper support.  Alternatively
@@ -330,7 +483,7 @@ def send_file(filename_or_fp, mimetype=None, as_attachment=False,
 
     .. versionadded:: 0.5
        The `add_etags`, `cache_timeout` and `conditional` parameters were
-       added.  The default behaviour is now to attach etags.
+       added.  The default behavior is now to attach etags.
 
     .. versionchanged:: 0.7
        mimetype guessing and etag support for file objects was
@@ -338,6 +491,9 @@ def send_file(filename_or_fp, mimetype=None, as_attachment=False,
        able to, otherwise attach an etag yourself.  This functionality
        will be removed in Flask 1.0
 
+    .. versionchanged:: 0.9
+       cache_timeout pulls its default from application config, when None.
+
     :param filename_or_fp: the filename of the file to send.  This is
                            relative to the :attr:`~Flask.root_path` if a
                            relative path is specified.
@@ -354,7 +510,11 @@ def send_file(filename_or_fp, mimetype=None, as_attachment=False,
                                 differs from the file's filename.
     :param add_etags: set to `False` to disable attaching of etags.
     :param conditional: set to `True` to enable conditional responses.
-    :param cache_timeout: the timeout in seconds for the headers.
+
+    :param cache_timeout: the timeout in seconds for the headers. When `None`
+                          (default), this value is set by
+                          :meth:`~Flask.get_send_file_max_age` of
+                          :data:`~flask.current_app`.
     """
     mtime = None
     if isinstance(filename_or_fp, basestring):
@@ -365,7 +525,7 @@ def send_file(filename_or_fp, mimetype=None, as_attachment=False,
         file = filename_or_fp
         filename = getattr(file, 'name', None)
 
-        # XXX: this behaviour is now deprecated because it was unreliable.
+        # XXX: this behavior is now deprecated because it was unreliable.
         # removed in Flask 1.0
         if not attachment_filename and not mimetype \
            and isinstance(filename, basestring):
@@ -376,7 +536,7 @@ def send_file(filename_or_fp, mimetype=None, as_attachment=False,
         if add_etags:
             warn(DeprecationWarning('In future flask releases etags will no '
                 'longer be generated for file objects passed to the send_file '
-                'function because this behaviour was unreliable.  Pass '
+                'function because this behavior was unreliable.  Pass '
                 'filenames instead if possible, otherwise attach an etag '
                 'yourself based on another value'), stacklevel=2)
 
@@ -418,7 +578,9 @@ def send_file(filename_or_fp, mimetype=None, as_attachment=False,
         rv.last_modified = int(mtime)
 
     rv.cache_control.public = True
-    if cache_timeout:
+    if cache_timeout is None:
+        cache_timeout = current_app.get_send_file_max_age(filename)
+    if cache_timeout is not None:
         rv.cache_control.max_age = cache_timeout
         rv.expires = int(time() + cache_timeout)
 
@@ -495,7 +657,8 @@ def send_from_directory(directory, filename, **options):
     filename = safe_join(directory, filename)
     if not os.path.isfile(filename):
         raise NotFound()
-    return send_file(filename, conditional=True, **options)
+    options.setdefault('conditional', True)
+    return send_file(filename, **options)
 
 
 def get_root_path(import_name):
@@ -504,17 +667,29 @@ def get_root_path(import_name):
 
     Not to be confused with the package path returned by :func:`find_package`.
     """
+    # Module already imported and has a file attribute.  Use that first.
+    mod = sys.modules.get(import_name)
+    if mod is not None and hasattr(mod, '__file__'):
+        return os.path.dirname(os.path.abspath(mod.__file__))
+
+    # Next attempt: check the loader.
     loader = pkgutil.get_loader(import_name)
+
+    # Loader does not exist or we're referring to an unloaded main module
+    # or a main module without path (interactive sessions), go with the
+    # current working directory.
     if loader is None or import_name == '__main__':
-        # import name is not found, or interactive/main module
         return os.getcwd()
+
     # For .egg, zipimporter does not have get_filename until Python 2.7.
+    # Some other loaders might exhibit the same behavior.
     if hasattr(loader, 'get_filename'):
         filepath = loader.get_filename(import_name)
     else:
         # Fall back to imports.
         __import__(import_name)
         filepath = sys.modules[import_name].__file__
+
     # filepath is import_name.py for a module, or __init__.py for a package.
     return os.path.dirname(os.path.abspath(filepath))
 
@@ -651,6 +826,32 @@ class _PackageBoundObject(object):
             return FileSystemLoader(os.path.join(self.root_path,
                                                  self.template_folder))
 
+    def get_send_file_max_age(self, filename):
+        """Provides default cache_timeout for the :func:`send_file` functions.
+
+        By default, this function returns ``SEND_FILE_MAX_AGE_DEFAULT`` from
+        the configuration of :data:`~flask.current_app`.
+
+        Static file functions such as :func:`send_from_directory` use this
+        function, and :func:`send_file` calls this function on
+        :data:`~flask.current_app` when the given cache_timeout is `None`. If a
+        cache_timeout is given in :func:`send_file`, that timeout is used;
+        otherwise, this method is called.
+
+        This allows subclasses to change the behavior when sending files based
+        on the filename.  For example, to set the cache timeout for .js files
+        to 60 seconds::
+
+            class MyFlask(flask.Flask):
+                def get_send_file_max_age(self, name):
+                    if name.lower().endswith('.js'):
+                        return 60
+                    return flask.Flask.get_send_file_max_age(self, name)
+
+        .. versionadded:: 0.9
+        """
+        return current_app.config['SEND_FILE_MAX_AGE_DEFAULT']
+
     def send_static_file(self, filename):
         """Function used internally to send static files from the static
         folder to the browser.
@@ -659,7 +860,11 @@ class _PackageBoundObject(object):
         """
         if not self.has_static_folder:
             raise RuntimeError('No static folder for this object')
-        return send_from_directory(self.static_folder, filename)
+        # Ensure get_send_file_max_age is called in all cases.
+        # Here, we ensure get_send_file_max_age is called for Blueprints.
+        cache_timeout = self.get_send_file_max_age(filename)
+        return send_from_directory(self.static_folder, filename,
+                                   cache_timeout=cache_timeout)
 
     def open_resource(self, resource, mode='rb'):
         """Opens a resource from the application's resource folder.  To see

libs/flask/signals.py

@@ -49,3 +49,4 @@ request_started = _signals.signal('request-started')
 request_finished = _signals.signal('request-finished')
 request_tearing_down = _signals.signal('request-tearing-down')
 got_request_exception = _signals.signal('got-request-exception')
+appcontext_tearing_down = _signals.signal('appcontext-tearing-down')

libs/flask/templating.py

@@ -109,17 +109,19 @@ def _render(template, context, app):
     return rv
 
 
-def render_template(template_name, **context):
+def render_template(template_name_or_list, **context):
     """Renders a template from the template folder with the given
     context.
 
-    :param template_name: the name of the template to be rendered
+    :param template_name_or_list: the name of the template to be
+                                  rendered, or an iterable with template names
+                                  the first one existing will be rendered
     :param context: the variables that should be available in the
                     context of the template.
     """
     ctx = _request_ctx_stack.top
     ctx.app.update_template_context(context)
-    return _render(ctx.app.jinja_env.get_template(template_name),
+    return _render(ctx.app.jinja_env.get_or_select_template(template_name_or_list),
                    context, ctx.app)
 
 

libs/flask/views.py

@@ -107,7 +107,7 @@ class MethodViewType(type):
         rv = type.__new__(cls, name, bases, d)
         if 'methods' not in d:
             methods = set(rv.methods or [])
-            for key, value in d.iteritems():
+            for key in d:
                 if key in http_method_funcs:
                     methods.add(key.upper())
             # if we have no method at all in there we don't want to

libs/flask/wrappers.py

@@ -10,9 +10,9 @@
 """
 
 from werkzeug.wrappers import Request as RequestBase, Response as ResponseBase
-from werkzeug.exceptions import BadRequest
 from werkzeug.utils import cached_property
 
+from .exceptions import JSONBadRequest
 from .debughelpers import attach_enctype_error_multidict
 from .helpers import json, _assert_have_json
 from .globals import _request_ctx_stack
@@ -108,12 +108,22 @@ class Request(RequestBase):
 
     def on_json_loading_failed(self, e):
         """Called if decoding of the JSON data failed.  The return value of
-        this method is used by :attr:`json` when an error ocurred.  The
-        default implementation raises a :class:`~werkzeug.exceptions.BadRequest`.
+        this method is used by :attr:`json` when an error ocurred.  The default
+        implementation raises a :class:`JSONBadRequest`, which is a subclass of
+        :class:`~werkzeug.exceptions.BadRequest` which sets the
+        ``Content-Type`` to ``application/json`` and provides a JSON-formatted
+        error description::
+
+            {"description": "The browser (or proxy) sent a request that \
+                             this server could not understand."}
+
+        .. versionchanged:: 0.9
+           Return a :class:`JSONBadRequest` instead of a
+           :class:`~werkzeug.exceptions.BadRequest` by default.
 
         .. versionadded:: 0.8
         """
-        raise BadRequest()
+        raise JSONBadRequest()
 
     def _load_form_data(self):
         RequestBase._load_form_data(self)