orbit-oss/flask
4
4
Fork 2
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

rewrite extension docs

Browse source 
remove old extension patterns
remove flask.ext from api docs
This commit is contained in:
David Lord 2018-02-28 07:52:03 -08:00
parent cc6c618f4d
commit 4462cc57c8
No known key found for this signature in database
GPG key ID: 7A1C87E3F5BC42A8
3 changed files with 43 additions and 130 deletions
Download patch file Download diff file Expand all files Collapse all files

75
docs/extensions.rst
View file

@ -1,58 +1,53 @@
.. _extensions:
Flask Extensions
================
Extensions
==========
Extensions are extra packages that add functionality to a Flask
application. For example, an extension might add support for sending
email or connecting to a database. Some extensions add entire new
frameworks to help build certain types of applications, like a ReST API.
Flask extensions extend the functionality of Flask in various different
ways. For instance they add support for databases and other common tasks.
Finding Extensions
------------------
Flask extensions are listed on the `Flask Extension Registry`_ and can be
downloaded with :command:`easy_install` or :command:`pip`. If you add a Flask extension
as dependency to your :file:`requirements.txt` or :file:`setup.py` file they are
usually installed with a simple command or when your application installs.
Flask extensions are usually named "Flask-Foo" or "Foo-Flask". Many
extensions are listed in the `Extension Registry`_, which can be updated
by extension developers. You can also search PyPI for packages tagged
with `Framework :: Flask <pypi_>`_.
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 should be always
importable from ``flask_foo``::
Consult each extension's documentation for installation, configuration,
and usage instructions. Generally, extensions pull their own
configuration from :attr:`app.config <flask.Flask.config>` and are
passed an application instance during initialization. For example,
an extension caled "Flask-Foo" might be used like this::
from flask_foo import Foo
foo = Foo()
app = Flask(__name__)
app.config.update(
FOO_BAR='baz',
FOO_SPAM='eggs',
)
foo.init_app(app)
import flask_foo
Building Extensions
-------------------
While `Flask Extension Registry`_ contains many Flask extensions, you may not find
an extension that fits your need. If this is the case, you can always create your own.
Consider reading :ref:`extension-dev` to develop your own Flask extension.
Flask Before 0.8
----------------
If you are using Flask 0.7 or earlier the :data:`flask.ext` package will not
exist, instead you have to import from ``flaskext.foo`` or ``flask_foo``
depending on how the extension is distributed. If you want to develop an
application that supports Flask 0.7 or earlier you should still import
from the :data:`flask.ext` package. We provide you with a compatibility
module that provides this package for older versions of Flask. You can
download it from GitHub: `flaskext_compat.py`_
And here is how you can use it::
import flaskext_compat
flaskext_compat.activate()
from flask.ext import foo
Once the ``flaskext_compat`` module is activated the :data:`flask.ext` will
exist and you can start importing from there.
While the `Extension Registry`_ 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
extension.
.. _Flask Extension Registry: http://flask.pocoo.org/extensions/
.. _flaskext_compat.py: https://raw.githubusercontent.com/pallets/flask/master/scripts/flaskext_compat.py
.. _Extension Registry: http://flask.pocoo.org/extensions/
.. _pypi: https://pypi.python.org/pypi?:action=browse&c=585