From 3ab318a7ddca819e13d6d161b008b62b6583453e Mon Sep 17 00:00:00 2001 From: Armin Ronacher Date: Thu, 1 Jul 2010 12:56:34 +0200 Subject: [PATCH] Explained Flask constructor better. This fixes #70 --- docs/quickstart.rst | 7 ++++++- flask.py | 28 ++++++++++++++++++++++++++++ 2 files changed, 34 insertions(+), 1 deletion(-) diff --git a/docs/quickstart.rst b/docs/quickstart.rst index fd9b02c2..a4858f1c 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -38,7 +38,12 @@ see your hello world greeting. So what did that code do? 1. first we imported the :class:`~flask.Flask` class. An instance of this - class will be our WSGI application. + class will be our WSGI application. The first argument is the name of + the application's module. If you are using a single module (like here) + you should use `__name__` because depending on if it's started as + application or imported as module the name will be different + (``'__main__'`` versus the actual import name). For more information + on that, have a look at the :class:`~flask.Flask` documentation. 2. next we create an instance of it. We pass it the name of the module / package. This is needed so that Flask knows where it should look for templates, static files and so on. diff --git a/flask.py b/flask.py index d2a0298c..90867fcc 100644 --- a/flask.py +++ b/flask.py @@ -806,6 +806,34 @@ class Flask(_PackageBoundObject): from flask import Flask app = Flask(__name__) + + .. admonition:: About the First Parameter + + The idea of the first parameter is to give Flask an idea what + belongs to your application. This name is used to find resources + on the file system, 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:: + + app = Flask('yourapplication') + app = Flask(__name__.split('.')[0]) + + 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 `yourapplicaiton.app` and not + `yourapplication.views.frontend`) """ #: The class that is used for request objects. See :class:`~flask.Request`