flask.app.Flask

Undocumented

Undocumented

Register a custom template global function. Works exactly like the template_global decorator.

Register a custom template test. Works exactly like the template_test decorator.

Register a rule for routing incoming requests and building URLs. The route decorator is a shortcut to call this with the view_func argument. These are equivalent:

@app.route("/")
def index():
    ...

def index():
    ...

app.add_url_rule("/", view_func=index)

See :ref:`url-route-registrations`.

The endpoint name for the route defaults to the name of the view function if the endpoint parameter isn't passed. An error will be raised if a function has already been registered for the endpoint.

The methods parameter defaults to ["GET"]. HEAD is always added automatically, and OPTIONS is added automatically by default.

view_func does not necessarily need to be passed, but if the rule should participate in routing an endpoint name must be associated with a view function at some point with the endpoint decorator.

app.add_url_rule("/", endpoint="index")

@app.endpoint("index")
def index():
    ...

If view_func has a required_methods attribute, those methods are added to the passed and automatic methods. If it has a provide_automatic_methods attribute, it is used as the default if the parameter is not passed.

Create an ~flask.ctx.AppContext. Use as a with block to push the context, which will make current_app point at this application.

An application context is automatically pushed by RequestContext.push() when handling a request, and when running a CLI command. Use this to manually create a context outside of these situations.

with app.app_context():
    init_db()

See :doc:`/appcontext`.

Return a sync function that will run the coroutine function.

result = app.async_to_sync(func)(*args, **kwargs)

Override this method to change how the app converts async code to be synchronously callable.

Tries to locate the instance path if it was not provided to the constructor of the application class. It will basically calculate the path to a folder named instance next to your main file or the package.

Registers a function to be run before the first request to this instance of the application.

The function will be called without any arguments and its return value is ignored.

Creates the loader for the Jinja2 environment. Can be used to override just the loader and keeping the rest unchanged. It's discouraged to override this function. Instead one should override the jinja_loader function instead.

The global loader dispatches between the loaders of the application and the individual blueprints.

Create the Jinja environment based on jinja_options and the various Jinja-related methods of the app. Changing jinja_options after this will have no effect. Also adds Flask-related globals and filters to the environment.

Creates a URL adapter for the given request. The URL adapter is created at a point where the request context is not yet set up so the request is passed explicitly.

Undocumented

Does the request dispatching. Matches the URL and returns the return value of the view or error handler. This does not have to be a response object. In order to convert the return value to a proper response object, call make_response.

Called right before the application context is popped.

When handling a request, the application context is popped after the request context. See do_teardown_request.

This calls all functions decorated with teardown_appcontext. Then the appcontext_tearing_down signal is sent.

This is called by AppContext.pop().

Called after the request is dispatched and the response is returned, right before the request context is popped.

This calls all functions decorated with teardown_request, and Blueprint.teardown_request if a blueprint handled the request. Finally, the request_tearing_down signal is sent.

This is called by RequestContext.pop(), which may be delayed during testing to maintain access to resources.

Ensure that the function is synchronous for WSGI workers. Plain def functions are returned as-is. async def functions are wrapped to run and wait for the response.

Override this method to change how the app runs async views.

Given the return value from a view function this finalizes the request by converting it into a response and invoking the postprocessing functions. This is invoked for both normal request dispatching as well as error handlers.

Because this means that it might be called as a result of a failure a special safe mode is available which can be enabled with the from_error_handler flag. If enabled, failures in response processing will be logged and otherwise ignored.

Dispatches the request and on top of that performs request pre and postprocessing as well as HTTP exception catching and error handling.

Handle an exception that did not have an error handler associated with it, or that was raised from an error handler. This always causes a 500 InternalServerError.

Always sends the got_request_exception signal.

If propagate_exceptions is True, such as in debug mode, the error will be re-raised so that the debugger can display it. Otherwise, the original exception is logged, and an ~werkzeug.exceptions.InternalServerError is returned.

If an error handler is registered for InternalServerError or 500, it will be used. For consistency, the handler will always receive the InternalServerError. The original unhandled exception is available as e.original_exception.

Handles an HTTP exception. By default this will invoke the registered error handlers and fall back to returning the exception as response.

This method is called whenever an exception occurs that should be handled. A special case is ~werkzeug .exceptions.HTTPException which is forwarded to the handle_http_exception method. This function will either return a response value or reraise the exception with the same traceback.

Injects the URL defaults for the given endpoint directly into the values dictionary passed. This is used internally and automatically called on URL building.

Iterates over all blueprints by the order they were registered.

Logs an exception. This is called by handle_exception if debugging is disabled and right before the handler is called. The default implementation logs the exception as error on the logger.

Used to create the config attribute by the Flask constructor. The instance_relative parameter is passed in from the constructor of Flask (there named instance_relative_config) and indicates if the config should be relative to the instance path or the root path of the application.

This method is called to create the default OPTIONS response. This can be changed through subclassing to change the default behavior of OPTIONS responses.

Convert the return value from a view function to an instance of response_class.

Returns the shell context for an interactive shell for this application. This runs all the registered shell context processors.

Called before the request is dispatched. Calls url_value_preprocessors registered with the app and the current blueprint (if any). Then calls before_request_funcs registered with the app and the blueprint.

If any before_request handler returns a non-None value, the value is handled as if it was the return value from the view, and further request handling is stopped.

Can be overridden in order to modify the response object before it's sent to the WSGI server. By default this will call all the after_request decorated functions.

Register a ~flask.Blueprint on the application. Keyword arguments passed to this method will override the defaults set on the blueprint.

Calls the blueprint's ~flask.Blueprint.register method after recording the blueprint in the application's blueprints.

Create a ~flask.ctx.RequestContext representing a WSGI environment. Use a with block to push the context, which will make request point at this request.

See :doc:`/reqcontext`.

Typically you should not call this from your own code. A request context is automatically pushed by the wsgi_app when handling a request. Use test_request_context to create an environment and context instead of this method.

Runs the application on a local development server.

Do not use run() in a production setting. It is not intended to meet security and performance requirements for a production server. Instead, see :doc:`/deploying/index` for WSGI server recommendations.

If the debug flag is set the server will automatically reload for code changes and show a debugger in case an exception happened.

If you want to run the application in debug mode, but disable the code execution on the interactive debugger, you can pass use_evalex=False as parameter. This will keep the debugger's traceback screen active, but disable code execution.

It is not recommended to use this function for development with automatic reloading as this is badly supported. Instead you should be using the :command:`flask` command line script's run support.

Returns True if autoescaping should be active for the given template name. If no template name is given, returns True.

Registers a shell context processor function.

This is called to figure out if an error should be ignored or not as far as the teardown system is concerned. If this function returns True then the teardown handlers will not be passed the error.

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 unhandled exception it will be passed an error object. If an errorhandler is registered, it will handle the exception and the teardown will not receive it.

The return values of teardown functions are ignored.

A decorator that is used to register custom template filter. You can specify a name for the filter, otherwise the function name will be used. Example:

@app.template_filter()
def reverse(s):
    return s[::-1]

A decorator that is used to register a custom template global function. You can specify a name for the global function, otherwise the function name will be used. Example:

@app.template_global()
def double(n):
    return 2 * n

A decorator that is used to register custom template test. You can specify a name for the test, otherwise the function name will be used. Example:

@app.template_test()
def is_prime(n):
    if n == 2:
        return True
    for i in range(2, int(math.ceil(math.sqrt(n))) + 1):
        if n % i == 0:
            return False
    return True

Undocumented

Create a CLI runner for testing CLI commands. See :ref:`testing-cli`.

Returns an instance of test_cli_runner_class, by default ~flask.testing.FlaskCliRunner. The Flask app object is passed as the first argument.

Creates a test client for this application. For information about unit testing head over to :doc:`/testing`.

Note that if you are testing for assertions or exceptions in your application code, you must set app.testing = True in order for the exceptions to propagate to the test client. Otherwise, the exception will be handled by the application (not visible to the test client) and the only indication of an AssertionError or other exception will be a 500 status code response to the test client. See the testing attribute. For example:

app.testing = True
client = app.test_client()

The test client can be used in a with block to defer the closing down of the context until the end of the with block. This is useful if you want to access the context locals for testing:

with app.test_client() as c:
    rv = c.get('/?vodka=42')
    assert request.args['vodka'] == '42'

Additionally, you may pass optional keyword arguments that will then be passed to the application's test_client_class constructor. For example:

from flask.testing import FlaskClient

class CustomClient(FlaskClient):
    def __init__(self, *args, **kwargs):
        self._authentication = kwargs.pop("authentication")
        super(CustomClient,self).__init__( *args, **kwargs)

app.test_client_class = CustomClient
client = app.test_client(authentication='Basic ....')

See ~flask.testing.FlaskClient for more information.

Create a ~flask.ctx.RequestContext for a WSGI environment created from the given values. This is mostly useful during testing, where you may want to run a function that uses request data without dispatching a full request.

See :doc:`/reqcontext`.

Use a with block to push the context, which will make request point at the request for the created environment.

with test_request_context(...):
    generate_report()

When using the shell, it may be easier to push and pop the context manually to avoid indentation.

ctx = app.test_request_context(...)
ctx.push()
...
ctx.pop()

Takes the same arguments as Werkzeug's ~werkzeug.test.EnvironBuilder, with some defaults from the application. See the linked Werkzeug docs for most of the available arguments. Flask-specific behavior is listed here.

Checks if an HTTP exception should be trapped or not. By default this will return False for all exceptions except for a bad request key error if TRAP_BAD_REQUEST_ERRORS is set to True. It also returns True if TRAP_HTTP_EXCEPTIONS is set to True.

This is called for all HTTP exceptions raised by a view function. If it returns True for any exception the error handler for this exception is not called and it shows up as regular exception in the traceback. This is helpful for debugging implicitly raised HTTP exceptions.

The actual WSGI application. This is not implemented in __call__ so that middlewares can be applied without losing a reference to the app object. Instead of doing this:

app = MyMiddleware(app)

It's a better idea to do this instead:

app.wsgi_app = MyMiddleware(app.wsgi_app)

Then you still have the original application object around and can continue to call methods on it.