API — Flask Documentation (3.1.x)

This part of the documentation covers all the interfaces of Flask. For parts where Flask depends on external libraries, we document the most important right here and provide links to the canonical documentation.
The flask object implements a WSGI application and acts as the central object. It is passed the name of the module or package of the application. Once it is created it will act as a central registry for the view functions, the URL rules, template configuration and much more.
The name of the package is used to resolve resources from inside the package or the folder the module is contained in depending on if the package parameter resolves to an actual python package (a folder with an __init__.py file inside) or a standard module (just a .py file).
For more information about resource loading, see open_resource().
Usually you create a Flask instance in your main module or in the __init__.py file of your package like this:
About the First Parameter
The idea of the first parameter is to give Flask an idea of what belongs to your application. This name is used to find resources on the filesystem, can be used by extensions to improve debugging information and a lot more.
So it’s important what you provide there. If you are using a single module, __name__ is always the correct value. If you however are using a package, it’s usually recommended to hardcode the name of your package there.
For example if your application is defined in yourapplication/app.py you should create it with one of the two versions below:
Why is that? The application will work even with __name__, thanks to how resources are looked up. However it will make debugging more painful. Certain extensions can make assumptions based on the import name of your application. For example the Flask-SQLAlchemy extension will look for the code in your application that triggered an SQL query in debug mode. If the import name is not properly set up, that debugging information is lost. (For example it would only pick up SQL queries in yourapplication.app and not yourapplication.views.frontend)
Added in version 1.0: The host_matching and static_host parameters were added.
Added in version 1.0: The subdomain_matching parameter was added. Subdomain matching needs to be enabled manually now. Setting SERVER_NAME does not implicitly enable it.
Added in version 0.11: The root_path parameter was added.
Added in version 0.8: The instance_path and instance_relative_config parameters were added.
Added in version 0.7: The static_url_path, static_folder, and template_folder parameters were added.
import_name (str) – the name of the application package
static_url_path (str | None) – can be used to specify a different path for the static files on the web. Defaults to the name of the static_folder folder.
static_folder (str | os.PathLike[str] | None) – The folder with static files that is served at static_url_path. Relative to the application root_path or an absolute path. Defaults to 'static'.
static_host (str | None) – the host to use when adding the static route. Defaults to None. Required when using host_matching=True with a static_folder configured.
host_matching (bool) – set url_map.host_matching attribute. Defaults to False.
subdomain_matching (bool) – consider the subdomain relative to SERVER_NAME when matching routes. Defaults to False.
template_folder (str | os.PathLike[str] | None) – the folder that contains the templates that should be used by the application. Defaults to 'templates' folder in the root path of the application.
instance_path (str | None) – An alternative instance path for the application. By default the folder 'instance' next to the package or module is assumed to be the instance path.
instance_relative_config (bool) – if set to True relative filenames for loading the config are assumed to be relative to the instance path instead of the application root.
root_path (str | None) – The path to the root of the application files. This should only be set manually when it can’t be detected automatically, such as for namespace packages.
the session interface to use. By default an instance of SecureCookieSessionInterface is used here.
Added in version 0.8.
The Click command group for registering CLI commands for this object. The commands are available from the flask command once the application has been discovered and blueprints have been registered.
Used by send_file() to determine the max_age cache value for a given file path if it wasn’t passed.
By default, this returns SEND_FILE_MAX_AGE_DEFAULT from the configuration of current_app. This defaults to None, which tells the browser to use conditional requests instead of a timed cache, which is usually preferable.
Note this is a duplicate of the same method in the Flask class.
Changed in version 2.0: The default configuration is None instead of 12 hours.
Added in version 0.9.
filename (str | None)
The view function used to serve files from static_folder. A route is automatically registered for this view at static_url_path if static_folder is set.
Note this is a duplicate of the same method in the Flask class.
Added in version 0.5.
Open a resource file relative to root_path for reading.
For example, if the file schema.sql is next to the file app.py where the Flask app is defined, it can be opened with:
resource (str) – Path to the resource relative to root_path.