diff --git a/docs/appcontext.rst b/docs/appcontext.rst index 12f08ff2..40a075e4 100644 --- a/docs/appcontext.rst +++ b/docs/appcontext.rst @@ -82,7 +82,9 @@ moves between threads and it will not be shared between requests. As such it is the perfect place to store database connection information and other things. The internal stack object is called :data:`flask._app_ctx_stack`. Extensions are free to store additional information on the topmost level, -assuming they pick a sufficiently unique name. +assuming they pick a sufficiently unique name and should put there +information there, instead on the :data:`flask.g` object which is reserved +for user code. For more information about that, see :ref:`extension-dev`. @@ -107,19 +109,19 @@ and a ``teardown_X()`` function that is registered as teardown handler. This is an example that connects to a database:: import sqlite3 - from flask import _app_ctx_stack + from flask import g def get_db(): - top = _app_ctx_stack.top - if not hasattr(top, 'database'): - top.database = connect_to_database() - return top.database + db = getattr(g, '_database', None) + if db is None: + db = g._database = connect_to_database() + return db @app.teardown_appcontext def teardown_db(exception): - top = _app_ctx_stack.top - if hasattr(top, 'database'): - top.database.close() + db = getattr(g, '_database', None) + if db is not None: + db.close() The first time ``get_db()`` is called the connection will be established. To make this implicit a :class:`~werkzeug.local.LocalProxy` can be used:: diff --git a/docs/patterns/sqlite3.rst b/docs/patterns/sqlite3.rst index e625d15b..f2e7eef3 100644 --- a/docs/patterns/sqlite3.rst +++ b/docs/patterns/sqlite3.rst @@ -10,21 +10,21 @@ easily. Here is a simple example of how you can use SQLite 3 with Flask:: import sqlite3 - from flask import _app_ctx_stack + from flask import g DATABASE = '/path/to/database.db' def get_db(): - top = _app_ctx_stack.top - if not hasattr(top, 'sqlite_db'): - top.sqlite_db = sqlite3.connect(DATABASE) - return top.sqlite_db + db = getattr(g, '_database', None) + if db is None: + db = g._database = connect_to_database() + return db @app.teardown_appcontext def close_connection(exception): - top = _app_ctx_stack.top - if hasattr(top, 'sqlite_db'): - top.sqlite_db.close() + db = getattr(g, '_database', None) + if db is not None: + db.close() All the application needs to do in order to now use the database is having an active application context (which is always true if there is an request @@ -33,6 +33,10 @@ in flight) or to create an application context itself. At that point the Whenever the context is destroyed the database connection will be terminated. +Note: if you use Flask 0.9 or older you need to use +``flask._app_ctx_stack.top`` instead of ``g`` as the :data:`flask.g` +object was bound to the request and not application context. + Example:: @app.route('/') diff --git a/docs/tutorial/dbcon.rst b/docs/tutorial/dbcon.rst index 99391a27..7042e680 100644 --- a/docs/tutorial/dbcon.rst +++ b/docs/tutorial/dbcon.rst @@ -18,7 +18,9 @@ decorators:: @app.teardown_request def teardown_request(exception): - g.db.close() + db = getattr(g, 'db', None) + if db is not None: + db.close() Functions marked with :meth:`~flask.Flask.before_request` are called before a request and passed no arguments. Functions marked with @@ -38,6 +40,9 @@ things on other objects because this would not work with threaded environments. That special :data:`~flask.g` object does some magic behind the scenes to ensure it does the right thing. +For an even better way to handle such resources see the :ref:`slite3` +documentation. + Continue to :ref:`tutorial-views`. .. hint:: Where do I put this code?