Merge flask framework and other stuff from master

1 files changed, 447 insertions, 0 deletions

diff --git a/python/flask/blueprints.py b/python/flask/blueprints.py
new file mode 100644
index 0000000..c2158fe
--- /dev/null
+++ b/python/flask/blueprints.py
@@ -0,0 +1,447 @@
+# -*- coding: utf-8 -*-
+"""
+    flask.blueprints
+    ~~~~~~~~~~~~~~~~
+
+    Blueprints are the recommended way to implement larger or more
+    pluggable applications in Flask 0.7 and later.
+
+    :copyright: © 2010 by the Pallets team.
+    :license: BSD, see LICENSE for more details.
+"""
+from functools import update_wrapper
+
+from .helpers import _PackageBoundObject, _endpoint_from_view_func
+
+
+class BlueprintSetupState(object):
+    """Temporary holder object for registering a blueprint with the
+    application.  An instance of this class is created by the
+    :meth:`~flask.Blueprint.make_setup_state` method and later passed
+    to all register callback functions.
+    """
+
+    def __init__(self, blueprint, app, options, first_registration):
+        #: a reference to the current application
+        self.app = app
+
+        #: a reference to the blueprint that created this setup state.
+        self.blueprint = blueprint
+
+        #: a dictionary with all options that were passed to the
+        #: :meth:`~flask.Flask.register_blueprint` method.
+        self.options = options
+
+        #: as blueprints can be registered multiple times with the
+        #: application and not everything wants to be registered
+        #: multiple times on it, this attribute can be used to figure
+        #: out if the blueprint was registered in the past already.
+        self.first_registration = first_registration
+
+        subdomain = self.options.get('subdomain')
+        if subdomain is None:
+            subdomain = self.blueprint.subdomain
+
+        #: The subdomain that the blueprint should be active for, ``None``
+        #: otherwise.
+        self.subdomain = subdomain
+
+        url_prefix = self.options.get('url_prefix')
+        if url_prefix is None:
+            url_prefix = self.blueprint.url_prefix
+        #: The prefix that should be used for all URLs defined on the
+        #: blueprint.
+        self.url_prefix = url_prefix
+
+        #: A dictionary with URL defaults that is added to each and every
+        #: URL that was defined with the blueprint.
+        self.url_defaults = dict(self.blueprint.url_values_defaults)
+        self.url_defaults.update(self.options.get('url_defaults', ()))
+
+    def add_url_rule(self, rule, endpoint=None, view_func=None, **options):
+        """A helper method to register a rule (and optionally a view function)
+        to the application.  The endpoint is automatically prefixed with the
+        blueprint's name.
+        """
+        if self.url_prefix is not None:
+            if rule:
+                rule = '/'.join((
+                    self.url_prefix.rstrip('/'), rule.lstrip('/')))
+            else:
+                rule = self.url_prefix
+        options.setdefault('subdomain', self.subdomain)
+        if endpoint is None:
+            endpoint = _endpoint_from_view_func(view_func)
+        defaults = self.url_defaults
+        if 'defaults' in options:
+            defaults = dict(defaults, **options.pop('defaults'))
+        self.app.add_url_rule(rule, '%s.%s' % (self.blueprint.name, endpoint),
+                              view_func, defaults=defaults, **options)
+
+
+class Blueprint(_PackageBoundObject):
+    """Represents a blueprint.  A blueprint is an object that records
+    functions that will be called with the
+    :class:`~flask.blueprints.BlueprintSetupState` later to register functions
+    or other things on the main application.  See :ref:`blueprints` for more
+    information.
+
+    .. versionadded:: 0.7
+    """
+
+    warn_on_modifications = False
+    _got_registered_once = False
+
+    #: Blueprint local JSON decoder class to use.
+    #: Set to ``None`` to use the app's :class:`~flask.app.Flask.json_encoder`.
+    json_encoder = None
+    #: Blueprint local JSON decoder class to use.
+    #: Set to ``None`` to use the app's :class:`~flask.app.Flask.json_decoder`.
+    json_decoder = None
+
+    # TODO remove the next three attrs when Sphinx :inherited-members: works
+    # https://github.com/sphinx-doc/sphinx/issues/741
+
+    #: The name of the package or module that this app belongs to. Do not
+    #: change this once it is set by the constructor.
+    import_name = None
+
+    #: Location of the template files to be added to the template lookup.
+    #: ``None`` if templates should not be added.
+    template_folder = None
+
+    #: Absolute path to the package on the filesystem. Used to look up
+    #: resources contained in the package.
+    root_path = None
+
+    def __init__(self, name, import_name, static_folder=None,
+                 static_url_path=None, template_folder=None,
+                 url_prefix=None, subdomain=None, url_defaults=None,
+                 root_path=None):
+        _PackageBoundObject.__init__(self, import_name, template_folder,
+                                     root_path=root_path)
+        self.name = name
+        self.url_prefix = url_prefix
+        self.subdomain = subdomain
+        self.static_folder = static_folder
+        self.static_url_path = static_url_path
+        self.deferred_functions = []
+        if url_defaults is None:
+            url_defaults = {}
+        self.url_values_defaults = url_defaults
+
+    def record(self, func):
+        """Registers a function that is called when the blueprint is
+        registered on the application.  This function is called with the
+        state as argument as returned by the :meth:`make_setup_state`
+        method.
+        """
+        if self._got_registered_once and self.warn_on_modifications:
+            from warnings import warn
+            warn(Warning('The blueprint was already registered once '
+                         'but is getting modified now.  These changes '
+                         'will not show up.'))
+        self.deferred_functions.append(func)
+
+    def record_once(self, func):
+        """Works like :meth:`record` but wraps the function in another
+        function that will ensure the function is only called once.  If the
+        blueprint is registered a second time on the application, the
+        function passed is not called.
+        """
+        def wrapper(state):
+            if state.first_registration:
+                func(state)
+        return self.record(update_wrapper(wrapper, func))
+
+    def make_setup_state(self, app, options, first_registration=False):
+        """Creates an instance of :meth:`~flask.blueprints.BlueprintSetupState`
+        object that is later passed to the register callback functions.
+        Subclasses can override this to return a subclass of the setup state.
+        """
+        return BlueprintSetupState(self, app, options, first_registration)
+
+    def register(self, app, options, first_registration=False):
+        """Called by :meth:`Flask.register_blueprint` to register all views
+        and callbacks registered on the blueprint with the application. Creates
+        a :class:`.BlueprintSetupState` and calls each :meth:`record` callback
+        with it.
+
+        :param app: The application this blueprint is being registered with.
+        :param options: Keyword arguments forwarded from
+            :meth:`~Flask.register_blueprint`.
+        :param first_registration: Whether this is the first time this
+            blueprint has been registered on the application.
+        """
+        self._got_registered_once = True
+        state = self.make_setup_state(app, options, first_registration)
+
+        if self.has_static_folder:
+            state.add_url_rule(
+                self.static_url_path + '/<path:filename>',
+                view_func=self.send_static_file, endpoint='static'
+            )
+
+        for deferred in self.deferred_functions:
+            deferred(state)
+
+    def route(self, rule, **options):
+        """Like :meth:`Flask.route` but for a blueprint.  The endpoint for the
+        :func:`url_for` function is prefixed with the name of the blueprint.
+        """
+        def decorator(f):
+            endpoint = options.pop("endpoint", f.__name__)
+            self.add_url_rule(rule, endpoint, f, **options)
+            return f
+        return decorator
+
+    def add_url_rule(self, rule, endpoint=None, view_func=None, **options):
+        """Like :meth:`Flask.add_url_rule` but for a blueprint.  The endpoint for
+        the :func:`url_for` function is prefixed with the name of the blueprint.
+        """
+        if endpoint:
+            assert '.' not in endpoint, "Blueprint endpoints should not contain dots"
+        if view_func and hasattr(view_func, '__name__'):
+            assert '.' not in view_func.__name__, "Blueprint view function name should not contain dots"
+        self.record(lambda s:
+            s.add_url_rule(rule, endpoint, view_func, **options))
+
+    def endpoint(self, endpoint):
+        """Like :meth:`Flask.endpoint` but for a blueprint.  This does not
+        prefix the endpoint with the blueprint name, this has to be done
+        explicitly by the user of this method.  If the endpoint is prefixed
+        with a `.` it will be registered to the current blueprint, otherwise
+        it's an application independent endpoint.
+        """
+        def decorator(f):
+            def register_endpoint(state):
+                state.app.view_functions[endpoint] = f
+            self.record_once(register_endpoint)
+            return f
+        return decorator
+
+    def app_template_filter(self, name=None):
+        """Register a custom template filter, available application wide.  Like
+        :meth:`Flask.template_filter` but for a blueprint.
+
+        :param name: the optional name of the filter, otherwise the
+                     function name will be used.
+        """
+        def decorator(f):
+            self.add_app_template_filter(f, name=name)
+            return f
+        return decorator
+
+    def add_app_template_filter(self, f, name=None):
+        """Register a custom template filter, available application wide.  Like
+        :meth:`Flask.add_template_filter` but for a blueprint.  Works exactly
+        like the :meth:`app_template_filter` decorator.
+
+        :param name: the optional name of the filter, otherwise the
+                     function name will be used.
+        """
+        def register_template(state):
+            state.app.jinja_env.filters[name or f.__name__] = f
+        self.record_once(register_template)
+
+    def app_template_test(self, name=None):
+        """Register a custom template test, available application wide.  Like
+        :meth:`Flask.template_test` but for a blueprint.
+
+        .. versionadded:: 0.10
+
+        :param name: the optional name of the test, otherwise the
+                     function name will be used.
+        """
+        def decorator(f):
+            self.add_app_template_test(f, name=name)
+            return f
+        return decorator
+
+    def add_app_template_test(self, f, name=None):
+        """Register a custom template test, available application wide.  Like
+        :meth:`Flask.add_template_test` but for a blueprint.  Works exactly
+        like the :meth:`app_template_test` decorator.
+
+        .. versionadded:: 0.10
+
+        :param name: the optional name of the test, otherwise the
+                     function name will be used.
+        """
+        def register_template(state):
+            state.app.jinja_env.tests[name or f.__name__] = f
+        self.record_once(register_template)
+
+    def app_template_global(self, name=None):
+        """Register a custom template global, available application wide.  Like
+        :meth:`Flask.template_global` but for a blueprint.
+
+        .. versionadded:: 0.10
+
+        :param name: the optional name of the global, otherwise the
+                     function name will be used.
+        """
+        def decorator(f):
+            self.add_app_template_global(f, name=name)
+            return f
+        return decorator
+
+    def add_app_template_global(self, f, name=None):
+        """Register a custom template global, available application wide.  Like
+        :meth:`Flask.add_template_global` but for a blueprint.  Works exactly
+        like the :meth:`app_template_global` decorator.
+
+        .. versionadded:: 0.10
+
+        :param name: the optional name of the global, otherwise the
+                     function name will be used.
+        """
+        def register_template(state):
+            state.app.jinja_env.globals[name or f.__name__] = f
+        self.record_once(register_template)
+
+    def before_request(self, f):
+        """Like :meth:`Flask.before_request` but for a blueprint.  This function
+        is only executed before each request that is handled by a function of
+        that blueprint.
+        """
+        self.record_once(lambda s: s.app.before_request_funcs
+            .setdefault(self.name, []).append(f))
+        return f
+
+    def before_app_request(self, f):
+        """Like :meth:`Flask.before_request`.  Such a function is executed
+        before each request, even if outside of a blueprint.
+        """
+        self.record_once(lambda s: s.app.before_request_funcs
+            .setdefault(None, []).append(f))
+        return f
+
+    def before_app_first_request(self, f):
+        """Like :meth:`Flask.before_first_request`.  Such a function is
+        executed before the first request to the application.
+        """
+        self.record_once(lambda s: s.app.before_first_request_funcs.append(f))
+        return f
+
+    def after_request(self, f):
+        """Like :meth:`Flask.after_request` but for a blueprint.  This function
+        is only executed after each request that is handled by a function of
+        that blueprint.
+        """
+        self.record_once(lambda s: s.app.after_request_funcs
+            .setdefault(self.name, []).append(f))
+        return f
+
+    def after_app_request(self, f):
+        """Like :meth:`Flask.after_request` but for a blueprint.  Such a function
+        is executed after each request, even if outside of the blueprint.
+        """
+        self.record_once(lambda s: s.app.after_request_funcs
+            .setdefault(None, []).append(f))
+        return f
+
+    def teardown_request(self, f):
+        """Like :meth:`Flask.teardown_request` but for a blueprint.  This
+        function is only executed when tearing down requests handled by a
+        function of that blueprint.  Teardown request functions are executed
+        when the request context is popped, even when no actual request was
+        performed.
+        """
+        self.record_once(lambda s: s.app.teardown_request_funcs
+            .setdefault(self.name, []).append(f))
+        return f
+
+    def teardown_app_request(self, f):
+        """Like :meth:`Flask.teardown_request` but for a blueprint.  Such a
+        function is executed when tearing down each request, even if outside of
+        the blueprint.
+        """
+        self.record_once(lambda s: s.app.teardown_request_funcs
+            .setdefault(None, []).append(f))
+        return f
+
+    def context_processor(self, f):
+        """Like :meth:`Flask.context_processor` but for a blueprint.  This
+        function is only executed for requests handled by a blueprint.
+        """
+        self.record_once(lambda s: s.app.template_context_processors
+            .setdefault(self.name, []).append(f))
+        return f
+
+    def app_context_processor(self, f):
+        """Like :meth:`Flask.context_processor` but for a blueprint.  Such a
+        function is executed each request, even if outside of the blueprint.
+        """
+        self.record_once(lambda s: s.app.template_context_processors
+            .setdefault(None, []).append(f))
+        return f
+
+    def app_errorhandler(self, code):
+        """Like :meth:`Flask.errorhandler` but for a blueprint.  This
+        handler is used for all requests, even if outside of the blueprint.
+        """
+        def decorator(f):
+            self.record_once(lambda s: s.app.errorhandler(code)(f))
+            return f
+        return decorator
+
+    def url_value_preprocessor(self, f):
+        """Registers a function as URL value preprocessor for this
+        blueprint.  It's called before the view functions are called and
+        can modify the url values provided.
+        """
+        self.record_once(lambda s: s.app.url_value_preprocessors
+            .setdefault(self.name, []).append(f))
+        return f
+
+    def url_defaults(self, f):
+        """Callback function for URL defaults for this blueprint.  It's called
+        with the endpoint and values and should update the values passed
+        in place.
+        """
+        self.record_once(lambda s: s.app.url_default_functions
+            .setdefault(self.name, []).append(f))
+        return f
+
+    def app_url_value_preprocessor(self, f):
+        """Same as :meth:`url_value_preprocessor` but application wide.
+        """
+        self.record_once(lambda s: s.app.url_value_preprocessors
+            .setdefault(None, []).append(f))
+        return f
+
+    def app_url_defaults(self, f):
+        """Same as :meth:`url_defaults` but application wide.
+        """
+        self.record_once(lambda s: s.app.url_default_functions
+            .setdefault(None, []).append(f))
+        return f
+
+    def errorhandler(self, code_or_exception):
+        """Registers an error handler that becomes active for this blueprint
+        only.  Please be aware that routing does not happen local to a
+        blueprint so an error handler for 404 usually is not handled by
+        a blueprint unless it is caused inside a view function.  Another
+        special case is the 500 internal server error which is always looked
+        up from the application.
+
+        Otherwise works as the :meth:`~flask.Flask.errorhandler` decorator
+        of the :class:`~flask.Flask` object.
+        """
+        def decorator(f):
+            self.record_once(lambda s: s.app._register_error_handler(
+                self.name, code_or_exception, f))
+            return f
+        return decorator
+
+    def register_error_handler(self, code_or_exception, f):
+        """Non-decorator version of the :meth:`errorhandler` error attach
+        function, akin to the :meth:`~flask.Flask.register_error_handler`
+        application-wide function of the :class:`~flask.Flask` object but
+        for error handlers limited to this blueprint.
+
+        .. versionadded:: 0.11
+        """
+        self.record_once(lambda s: s.app._register_error_handler(
+            self.name, code_or_exception, f))