"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "docs/extensiondev.rst" between
flask-1.1.1.tar.gz and flask-1.1.2.tar.gz

About: Flask is a lightweight Python WSGI web application framework.

extensiondev.rst  (flask-1.1.1):extensiondev.rst  (flask-1.1.2)
.. _extension-dev:
Flask Extension Development Flask Extension Development
=========================== ===========================
Flask, being a microframework, often requires some repetitive steps to get Flask, being a microframework, often requires some repetitive steps to get
a third party library working. Many such extensions are already available a third party library working. Many such extensions are already available
on `PyPI <https://pypi.org/search/?c=Framework+%3A%3A+Flask>`_. on `PyPI`_.
If you want to create your own Flask extension for something that does not If you want to create your own Flask extension for something that does not
exist yet, this guide to extension development will help you get your exist yet, this guide to extension development will help you get your
extension running in no time and to feel like users would expect your extension running in no time and to feel like users would expect your
extension to behave. extension to behave.
.. _Flask Extension Registry: http://flask.pocoo.org/extensions/
Anatomy of an Extension Anatomy of an Extension
----------------------- -----------------------
Extensions are all located in a package called ``flask_something`` Extensions are all located in a package called ``flask_something``
where "something" is the name of the library you want to bridge. So for where "something" is the name of the library you want to bridge. So for
example if you plan to add support for a library named `simplexml` to example if you plan to add support for a library named `simplexml` to
Flask, you would name your extension's package ``flask_simplexml``. Flask, you would name your extension's package ``flask_simplexml``.
The name of the actual extension (the human readable name) however would The name of the actual extension (the human readable name) however would
be something like "Flask-SimpleXML". Make sure to include the name be something like "Flask-SimpleXML". Make sure to include the name
skipping to change at line 273 skipping to change at line 269
In the example above, before every request, a ``sqlite3_db`` variable is In the example above, before every request, a ``sqlite3_db`` variable is
assigned to ``_app_ctx_stack.top``. In a view function, this variable is assigned to ``_app_ctx_stack.top``. In a view function, this variable is
accessible using the ``connection`` property of ``SQLite3``. During the accessible using the ``connection`` property of ``SQLite3``. During the
teardown of a request, the ``sqlite3_db`` connection is closed. By using teardown of a request, the ``sqlite3_db`` connection is closed. By using
this pattern, the *same* connection to the sqlite3 database is accessible this pattern, the *same* connection to the sqlite3 database is accessible
to anything that needs it for the duration of the request. to anything that needs it for the duration of the request.
Learn from Others Learn from Others
----------------- -----------------
This documentation only touches the bare minimum for extension This documentation only touches the bare minimum for extension development.
development. If you want to learn more, it's a very good idea to check If you want to learn more, it's a very good idea to check out existing extension
out existing extensions on the `Flask Extension Registry`_. If you feel s
lost there is still the `mailinglist`_ and the `IRC channel`_ to get some on the `PyPI`_. If you feel lost there is still the `mailinglist`_ and the
ideas for nice looking APIs. Especially if you do something nobody before `Discord server`_ to get some ideas for nice looking APIs. Especially if you do
you did, it might be a very good idea to get some more input. This not only something nobody before you did, it might be a very good idea to get some more
generates useful feedback on what people might want from an extension, but input. This not only generates useful feedback on what people might want from
also avoids having multiple developers working in isolation on pretty much the an extension, but also avoids having multiple developers working in isolation
same problem. on pretty much the same problem.
Remember: good API design is hard, so introduce your project on the Remember: good API design is hard, so introduce your project on the
mailing list, and let other developers give you a helping hand with mailing list, and let other developers give you a helping hand with
designing the API. designing the API.
The best Flask extensions are extensions that share common idioms for the The best Flask extensions are extensions that share common idioms for the
API. And this can only work if collaboration happens early. API. And this can only work if collaboration happens early.
Approved Extensions Approved Extensions
------------------- -------------------
Flask also has the concept of approved extensions. Approved extensions Flask previously had the concept of approved extensions. These came with
are tested as part of Flask itself to ensure extensions do not break on some vetting of support and compatibility. While this list became too
new releases. These approved extensions are listed on the `Flask difficult to maintain over time, the guidelines are still relevant to
Extension Registry`_ and marked appropriately. If you want your own all extensions maintained and developed today, as they help the Flask
extension to be approved you have to follow these guidelines: ecosystem remain consistent and compatible.
0. An approved Flask extension requires a maintainer. In the event an 0. An approved Flask extension requires a maintainer. In the event an
extension author would like to move beyond the project, the project should extension author would like to move beyond the project, the project
find a new maintainer including full source hosting transition and PyPI should find a new maintainer and transfer access to the repository,
access. If no maintainer is available, give access to the Flask core team. documentation, PyPI, and any other services. If no maintainer
1. An approved Flask extension must provide exactly one package or module is available, give access to the Pallets core team.
named ``flask_extensionname``. 1. The naming scheme is *Flask-ExtensionName* or *ExtensionName-Flask*.
2. It must ship a testing suite that can either be invoked with ``make test`` It must provide exactly one package or module named
or ``python setup.py test``. For test suites invoked with ``make ``flask_extension_name``.
test`` the extension has to ensure that all dependencies for the test 2. The extension must be BSD or MIT licensed. It must be open source
are installed automatically. If tests are invoked with ``python setup.py and publicly available.
test``, test dependencies can be specified in the :file:`setup.py` file. 3. The extension's API must have the following characteristics:
The test suite also has to be part of the distribution.
3. APIs of approved extensions will be checked for the following - It must support multiple applications running in the same Python
characteristics: process. Use ``current_app`` instead of ``self.app``, store
configuration and state per application instance.
- an approved extension has to support multiple applications - It must be possible to use the factory pattern for creating
running in the same Python process. applications. Use the ``ext.init_app()`` pattern.
- it must be possible to use the factory pattern for creating
applications. 4. From a clone of the repository, an extension with its dependencies
must be installable with ``pip install -e .``.
4. The license must be BSD/MIT/WTFPL licensed. 5. It must ship a testing suite that can be invoked with ``tox -e py``
5. The naming scheme for official extensions is *Flask-ExtensionName* or or ``pytest``. If not using ``tox``, the test dependencies should be
*ExtensionName-Flask*. specified in a ``requirements.txt`` file. The tests must be part of
6. Approved extensions must define all their dependencies in the the sdist distribution.
:file:`setup.py` file unless a dependency cannot be met because it is not 6. The documentation must use the ``flask`` theme from the
available on PyPI. `Official Pallets Themes`_. A link to the documentation or project
7. The documentation must use the ``flask`` theme from the website must be in the PyPI metadata or the readme.
`Official Pallets Themes`_. 7. For maximum compatibility, the extension should support the same
8. The setup.py description (and thus the PyPI description) has to versions of Python that Flask supports. 3.6+ is recommended as of
link to the documentation, website (if there is one) and there 2020. Use ``python_requires=">= 3.6"`` in ``setup.py`` to indicate
must be a link to automatically install the development version supported versions.
(``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.
.. _PyPI: https://pypi.org/search/?c=Framework+%3A%3A+Flask
.. _OAuth extension: https://pythonhosted.org/Flask-OAuth/ .. _OAuth extension: https://pythonhosted.org/Flask-OAuth/
.. _mailinglist: http://flask.pocoo.org/mailinglist/ .. _mailinglist: https://mail.python.org/mailman/listinfo/flask
.. _IRC channel: http://flask.pocoo.org/community/irc/ .. _Discord server: https://discord.gg/t6rrQZH
.. _Official Pallets Themes: https://pypi.org/project/Pallets-Sphinx-Themes/ .. _Official Pallets Themes: https://pypi.org/project/Pallets-Sphinx-Themes/
 End of changes. 8 change blocks. 
55 lines changed or deleted 48 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)