Merge branch 'master' of github.com:mitsuhiko/flask

docs/patterns/appfactories.rst

@@ -54,20 +54,38 @@ get access to the application with the config?  Use
 
 Here we look up the name of a template in the config.
 
-Extension objects are not initially bound to an application. Using
-``db.init_app``, the app gets configured for the extension. No
-application-specific state is stored on the extension object, so one extension
-object can be used for multiple apps. For more information about the design of
-extensions refer to :doc:`/extensiondev`.
+Factories & Extensions
+----------------------
 
-Your `model.py` might look like this when using `Flask-SQLAlchemy
-<http://pythonhosted.org/Flask-SQLAlchemy/>`_::
+It's preferable to create your extensions and app factories so that the
+extension object does not initially get bound to the application.
+
+Using `Flask-SQLAlchemy <http://pythonhosted.org/Flask-SQLAlchemy/>`_, 
+as an example, you should **not** do::
+    
+    def create_app(config_filename):
+        app = Flask(__name__)
+        app.config.from_pyfile(config_filename)
+
+        db = SQLAlchemy(app)
+
+But, rather, in model.py (or equivalent)::
 
-    from flask.ext.sqlalchemy import SQLAlchemy
-    # no app object passed! Instead we use use db.init_app in the factory.
     db = SQLAlchemy()
     
-    # create some models
+and in your application.py (or equivalent)::
+
+    def create_app(config_filename):
+        app = Flask(__name__)
+        app.config.from_pyfile(config_filename)
+
+        from yourapplication.model import db
+        db.init_app(app)
+
+
+Using this design pattern, no application-specific state is stored on the
+extension object, so one extension object can be used for multiple apps. 
+For more information about the design of extensions refer to :doc:`/extensiondev`.
 
 Using Applications
 ------------------