Add docs on deprecation of flask.ext

pallets · untitaker · Apr 2, 2016 · Jun 6, 2015 · Jun 6, 2015 · Jun 19, 2015
commit 005a49d969e2e4ebcd23cfd8347a6f2d331e1778
diff --git a/docs/extensiondev.rst b/docs/extensiondev.rst
@@ -360,8 +360,7 @@ extension to be approved you have to follow these guidelines:
     find a new maintainer including full source hosting transition and PyPI
     access.  If no maintainer is available, give access to the Flask core team.
 1.  An approved Flask extension must provide exactly one package or module
-    named ``flask_extensionname``.  They might also reside inside a
-    ``flaskext`` namespace packages though this is discouraged now.
+    named ``flask_extensionname``.
 2.  It must ship a testing suite that can either be invoked with ``make test``
     or ``python setup.py test``.  For test suites invoked with ``make
     test`` the extension has to ensure that all dependencies for the test
@@ -399,20 +398,19 @@ extension to be approved you have to follow these guidelines:
 Extension Import Transition
 ---------------------------
 
-For a while we recommended using namespace packages for Flask extensions.
-This turned out to be problematic in practice because many different
-competing namespace package systems exist and pip would automatically
-switch between different systems and this caused a lot of problems for
-users.
+In early versions of Flask we recommended using namespace packages for Flask
+extensions, of the form ``flaskext.foo``. This turned out to be problematic in
+practice because it meant that multiple ``flaskext`` packages coexist.
+Consequently we have recommended to name extensions ``flask_foo`` over
+``flaskext.foo`` for a long time.
 
-Instead we now recommend naming packages ``flask_foo`` instead of the now
-deprecated ``flaskext.foo``.  Flask 0.8 introduces a redirect import
-system that lets uses import from ``flask.ext.foo`` and it will try
-``flask_foo`` first and if that fails ``flaskext.foo``.
+Flask 0.8 introduced a redirect import system as a compatibility aid for app
+developers: Importing ``flask.ext.foo`` would try ``flask_foo`` and
+``flaskext.foo`` in that order.
 
-Flask extensions should urge users to import from ``flask.ext.foo``
-instead of ``flask_foo`` or ``flaskext_foo`` so that extensions can
-transition to the new package name without affecting users.
+As of Flask 1.0, most Flask extensions have transitioned to the new naming
+schema. The ``flask.ext.foo`` compatibility alias is still in Flask 1.0 but is
+now deprecated -- you should use ``flask_foo``.
 
 
 .. _OAuth extension: http://pythonhosted.org/Flask-OAuth/

diff --git a/docs/extensions.rst b/docs/extensions.rst
@@ -18,10 +18,10 @@ Using Extensions
 Extensions typically have documentation that goes along that shows how to
 use it.  There are no general rules in how extensions are supposed to
 behave but they are imported from common locations.  If you have an
-extension called ``Flask-Foo`` or ``Foo-Flask`` it will be always
-importable from ``flask.ext.foo``::
+extension called ``Flask-Foo`` or ``Foo-Flask`` it should be always
+importable from ``flask_foo``::
 
-    from flask.ext import foo
+    import flask_foo
 
 Flask Before 0.8
 ----------------
@@ -44,5 +44,6 @@ And here is how you can use it::
 Once the ``flaskext_compat`` module is activated the :data:`flask.ext` will
 exist and you can start importing from there.
 
+
 .. _Flask Extension Registry: http://flask.pocoo.org/extensions/
 .. _flaskext_compat.py: https://raw.githubusercontent.com/mitsuhiko/flask/master/scripts/flaskext_compat.py
diff --git a/docs/upgrading.rst b/docs/upgrading.rst
@@ -48,7 +48,16 @@ of :func:`~flask.templating.render_template`.
     and therefore was replaced with the intended behavior of registering
     handlers only using exception classes and HTTP error codes.
 
-    Trying to register a handler on an instance now raises :exc:`ValueError`.
+Trying to register a handler on an instance now raises :exc:`ValueError`.
+
+Extension imports of the form ``flask.ext.foo`` are deprecated, you should use
+``flask_foo``.
+
+The old form still works, but Flask will issue a
+``flask.exthook.ExtDeprecationWarning`` for each extension you import the old
+way. We also provide a migration utility called `flask-ext-migrate
+<https://github.com/pocoo/flask-ext-migrate>`_ that is supposed to
+automatically rewrite your imports for this.
 
 .. _upgrading-to-010: