update patterns, snippets, extensions docs

Author: davidism

docs/appcontext.rst

@@ -144,7 +144,7 @@ If you're writing an extension, :data:`g` should be reserved for user
 code. You may store internal data on the context itself, but be sure to
 use a sufficiently unique name. The current context is accessed with
 :data:`_app_ctx_stack.top <_app_ctx_stack>`. For more information see
-:doc:`extensiondev`.
+:doc:`/extensiondev`.
 
 
 Events and Signals

docs/becomingbig.rst

@@ -21,13 +21,13 @@ Hook. Extend.
 -------------
 
 The :ref:`api` docs are full of available overrides, hook points, and
-:ref:`signals`. You can provide custom classes for things like the request and
-response objects.  Dig deeper on the APIs you use, and look for the
-customizations which are available out of the box in a Flask release.  Look for
-ways in which your project can be refactored into a collection of utilities and
-Flask extensions.  Explore the many `extensions
-<http://flask.pocoo.org/extensions/>`_ in the community, and look for patterns to
-build your own extensions if you do not find the tools you need.
+:ref:`signals`. You can provide custom classes for things like the
+request and response objects. Dig deeper on the APIs you use, and look
+for the customizations which are available out of the box in a Flask
+release. Look for ways in which your project can be refactored into a
+collection of utilities and Flask extensions. Explore the many
+:doc:`/extensions` in the community, and look for patterns to build your
+own extensions if you do not find the tools you need.
 
 Subclass.
 ---------
@@ -96,6 +96,6 @@ Discuss with the community.
 
 The Flask developers keep the framework accessible to users with codebases big
 and small. If you find an obstacle in your way, caused by Flask, don't hesitate
-to contact the developers on the mailing list or IRC channel.  The best way for
+to contact the developers on the mailing list or Discord server.  The best way for
 the Flask and Flask extension developers to improve the tools for larger
 applications is getting feedback from users.

docs/extensiondev.rst

@@ -1,5 +1,3 @@
-.. _extension-dev:
-
 Flask Extension Development
 ===========================
 
@@ -276,7 +274,7 @@ Learn from Others
 This documentation only touches the bare minimum for extension development.
 If you want to learn more, it's a very good idea to check out existing extensions
 on the `PyPI`_.  If you feel lost there is still the `mailinglist`_ and the
-`IRC channel`_ to get some ideas for nice looking APIs.  Especially if you do
+`Discord server`_ to get some ideas for nice looking APIs.  Especially if you do
 something nobody before you did, it might be a very good idea to get some more
 input.  This not only generates useful feedback on what people might want from
 an extension, but also avoids having multiple developers working in isolation
@@ -292,50 +290,45 @@ API.  And this can only work if collaboration happens early.
 Approved Extensions
 -------------------
 
-Flask also has the concept of approved extensions.  Approved extensions
-are tested as part of Flask itself to ensure extensions do not break on
-new releases.  If you want your own extension to be approved you have to
-follow these guidelines:
+Flask previously had the concept of approved extensions. These came with
+some vetting of support and compatibility. While this list became too
+difficult to maintain over time, the guidelines are still relevant to
+all extensions maintained and developed today, as they help the Flask
+ecosystem remain consistent and compatible.
 
 0.  An approved Flask extension requires a maintainer. In the event an
-    extension author would like to move beyond the project, the project should
-    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``.
-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
-    are installed automatically.  If tests are invoked with ``python setup.py
-    test``, test dependencies can be specified in the :file:`setup.py` file.  The
-    test suite also has to be part of the distribution.
-3.  APIs of approved extensions will be checked for the following
-    characteristics:
-
-   -   an approved extension has to support multiple applications
-       running in the same Python process.
-   -   it must be possible to use the factory pattern for creating
-       applications.
-
-4.  The license must be BSD/MIT/WTFPL licensed.
-5.  The naming scheme for official extensions is *Flask-ExtensionName* or
-    *ExtensionName-Flask*.
-6.  Approved extensions must define all their dependencies in the
-    :file:`setup.py` file unless a dependency cannot be met because it is not
-    available on PyPI.
-7.  The documentation must use the ``flask`` theme from the
-    `Official Pallets Themes`_.
-8.  The setup.py description (and thus the PyPI description) has to
-    link to the documentation, website (if there is one) and there
-    must be a link to automatically install the development version
-    (``PackageName==dev``).
-9. The ``zip_safe`` flag in the setup script must be set to ``False``,
-   even if the extension would be safe for zipping.
-10. An extension currently has to support Python 3.4 and newer and 2.7.
+    extension author would like to move beyond the project, the project
+    should find a new maintainer and transfer access to the repository,
+    documentation, PyPI, and any other services. If no maintainer
+    is available, give access to the Pallets core team.
+1.  The naming scheme is *Flask-ExtensionName* or *ExtensionName-Flask*.
+    It must provide exactly one package or module named
+    ``flask_extension_name``.
+2.  The extension must be BSD or MIT licensed. It must be open source
+    and publicly available.
+3.  The extension's API must have the following characteristics:
+
+    -   It must support multiple applications running in the same Python
+        process. Use ``current_app`` instead of ``self.app``, store
+        configuration and state per application instance.
+    -   It must be possible to use the factory pattern for creating
+        applications. Use the ``ext.init_app()`` pattern.
+
+4.  From a clone of the repository, an extension with its dependencies
+    must be installable with ``pip install -e .``.
+5.  It must ship a testing suite that can be invoked with ``tox -e py``
+    or ``pytest``. If not using ``tox``, the test dependencies should be
+    specified in a ``requirements.txt`` file. The tests must be part of
+    the sdist distribution.
+6.  The documentation must use the ``flask`` theme from the
+    `Official Pallets Themes`_. A link to the documentation or project
+    website must be in the PyPI metadata or the readme.
+7.  The active versions of Python should be supported. As of 2020 this
+    means Python 3.5 and newer.
 
 
 .. _PyPI: https://pypi.org/search/?c=Framework+%3A%3A+Flask
 .. _OAuth extension: https://pythonhosted.org/Flask-OAuth/
-.. _mailinglist: http://flask.pocoo.org/mailinglist/
-.. _IRC channel: http://flask.pocoo.org/community/irc/
+.. _mailinglist: https://mail.python.org/mailman/listinfo/flask
+.. _Discord server: https://discord.gg/t6rrQZH
 .. _Official Pallets Themes: https://pypi.org/project/Pallets-Sphinx-Themes/

docs/extensions.rst

@@ -43,7 +43,7 @@ Building Extensions
 
 While the `PyPI <pypi_>`_ contains many Flask extensions, you may
 not find an extension that fits your need. If this is the case, you can
-create your own. Read :ref:`extension-dev` to develop your own Flask
+create your own. Read :doc:`/extensiondev` to develop your own Flask
 extension.
 
 

docs/patterns/appdispatch.rst

@@ -62,12 +62,12 @@ dispatched based on prefix.
 For example you could have your main application run on ``/`` and your
 backend interface on ``/backend``::
 
-    from werkzeug.wsgi import DispatcherMiddleware
+    from werkzeug.middleware.dispatcher import DispatcherMiddleware
     from frontend_app import application as frontend
     from backend_app import application as backend
 
     application = DispatcherMiddleware(frontend, {
-        '/backend':     backend
+        '/backend': backend
     })
 
 

docs/patterns/fileuploads.rst

@@ -121,7 +121,7 @@ Alternatively you can register `uploaded_file` as `build_only` rule and
 use the :class:`~werkzeug.wsgi.SharedDataMiddleware`.  This also works with
 older versions of Flask::
 
-    from werkzeug import SharedDataMiddleware
+    from werkzeug.middleware.shared_data import SharedDataMiddleware
     app.add_url_rule('/uploads/<filename>', 'uploaded_file',
                      build_only=True)
     app.wsgi_app = SharedDataMiddleware(app.wsgi_app, {

docs/patterns/index.rst

@@ -3,15 +3,16 @@
 Patterns for Flask
 ==================
 
-Certain things are common enough that the chances are high you will find
-them in most web applications.  For example quite a lot of applications
-are using relational databases and user authentication.  In that case,
-chances are they will open a database connection at the beginning of the
-request and get the information of the currently logged in user.  At the
-end of the request, the database connection is closed again.
+Certain features and interactions are common enough that you will find
+them in most web applications. For example, many applications use a
+relational database and user authentication. They will open a database
+connection at the beginning of the request and get the information for
+the logged in user. At the end of the request, the database connection
+is closed.
 
-There are more user contributed snippets and patterns in the `Flask
-Snippet Archives <http://flask.pocoo.org/snippets/>`_.
+These types of patterns may be a bit outside the scope of Flask itself,
+but Flask makes it easy to implement them. Some common patterns are
+collected in the following pages.
 
 .. toctree::
    :maxdepth: 2

docs/patterns/lazyloading.rst

@@ -58,7 +58,7 @@ loaded upfront.  The trick is to actually load the view function as needed.
 This can be accomplished with a helper class that behaves just like a
 function but internally imports the real function on first use::
 
-    from werkzeug import import_string, cached_property
+    from werkzeug.utils import import_string, cached_property
 
     class LazyView(object):
 

docs/quickstart.rst

@@ -824,16 +824,22 @@ docs for more information.
 
 Read more on :ref:`application-errors`.
 
-Hooking in WSGI Middlewares
----------------------------
+Hooking in WSGI Middleware
+--------------------------
 
-If you want to add a WSGI middleware to your application you can wrap the
-internal WSGI application.  For example if you want to use one of the
-middlewares from the Werkzeug package to work around bugs in lighttpd, you
-can do it like this::
+To add WSGI middleware to your Flask application, wrap the application's
+``wsgi_app`` attribute. For example, to apply Werkzeug's
+:class:`~werkzeug.middlware.proxy_fix.ProxyFix` middleware for running
+behind Nginx:
 
-    from werkzeug.contrib.fixers import LighttpdCGIRootFix
-    app.wsgi_app = LighttpdCGIRootFix(app.wsgi_app)
+.. code-block:: python
+
+    from werkzeug.middleware.proxy_fix import ProxyFix
+    app.wsgi_app = ProxyFix(app.wsgi_app)
+
+Wrapping ``app.wsgi_app`` instead of ``app`` means that ``app`` still
+points at your Flask application, not at the middleware, so you can
+continue to use and configure ``app`` directly.
 
 Using Flask Extensions
 ----------------------