Merge remote-tracking branch 'origin/2.1.x'
This commit is contained in:
David Lord
commit
a25d234cdd
10 changed files with 30 additions and 136 deletions
1
.gitignore
vendored
1
.gitignore
vendored
|
|
@ -11,7 +11,6 @@ dist/
|
|||
build/
|
||||
*.egg
|
||||
*.egg-info/
|
||||
_mailinglist
|
||||
.tox/
|
||||
.cache/
|
||||
.pytest_cache/
|
||||
|
|
|
|||
|
|
@ -14,11 +14,10 @@ own code:
|
|||
|
||||
- The ``#questions`` channel on our Discord chat:
|
||||
https://discord.gg/pallets
|
||||
- The mailing list flask@python.org for long term discussion or larger
|
||||
issues.
|
||||
- Ask on `Stack Overflow`_. Search with Google first using:
|
||||
``site:stackoverflow.com flask {search term, exception message, etc.}``
|
||||
- Ask on our `GitHub Discussions`_.
|
||||
- Ask on our `GitHub Discussions`_ for long term discussion or larger
|
||||
questions.
|
||||
|
||||
.. _Stack Overflow: https://stackoverflow.com/questions/tagged/flask?tab=Frequent
|
||||
.. _GitHub Discussions: https://github.com/pallets/flask/discussions
|
||||
|
|
@ -98,21 +97,20 @@ First time setup
|
|||
|
||||
- Create a virtualenv.
|
||||
|
||||
.. tabs::
|
||||
|
||||
.. group-tab:: Linux/macOS
|
||||
- Linux/macOS
|
||||
|
||||
.. code-block:: text
|
||||
.. code-block:: text
|
||||
|
||||
$ python3 -m venv env
|
||||
$ . env/bin/activate
|
||||
$ python3 -m venv env
|
||||
$ . env/bin/activate
|
||||
|
||||
.. group-tab:: Windows
|
||||
- Windows
|
||||
|
||||
.. code-block:: text
|
||||
.. code-block:: text
|
||||
|
||||
> py -3 -m venv env
|
||||
> env\Scripts\activate
|
||||
> py -3 -m venv env
|
||||
> env\Scripts\activate
|
||||
|
||||
- Upgrade pip and setuptools.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,100 +0,0 @@
|
|||
Becoming Big
|
||||
============
|
||||
|
||||
Here are your options when growing your codebase or scaling your application.
|
||||
|
||||
Read the Source.
|
||||
----------------
|
||||
|
||||
Flask started in part to demonstrate how to build your own framework on top of
|
||||
existing well-used tools Werkzeug (WSGI) and Jinja (templating), and as it
|
||||
developed, it became useful to a wide audience. As you grow your codebase,
|
||||
don't just use Flask -- understand it. Read the source. Flask's code is
|
||||
written to be read; its documentation is published so you can use its internal
|
||||
APIs. Flask sticks to documented APIs in upstream libraries, and documents its
|
||||
internal utilities so that you can find the hook points needed for your
|
||||
project.
|
||||
|
||||
Hook. Extend.
|
||||
-------------
|
||||
|
||||
The :doc:`/api` docs are full of available overrides, hook points, and
|
||||
:doc:`/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.
|
||||
---------
|
||||
|
||||
The :class:`~flask.Flask` class has many methods designed for subclassing. You
|
||||
can quickly add or customize behavior by subclassing :class:`~flask.Flask` (see
|
||||
the linked method docs) and using that subclass wherever you instantiate an
|
||||
application class. This works well with :doc:`/patterns/appfactories`.
|
||||
See :doc:`/patterns/subclassing` for an example.
|
||||
|
||||
Wrap with middleware.
|
||||
---------------------
|
||||
|
||||
The :doc:`/patterns/appdispatch` pattern shows in detail how to apply middleware. You
|
||||
can introduce WSGI middleware to wrap your Flask instances and introduce fixes
|
||||
and changes at the layer between your Flask application and your HTTP
|
||||
server. Werkzeug includes several `middlewares
|
||||
<https://werkzeug.palletsprojects.com/middleware/>`_.
|
||||
|
||||
Fork.
|
||||
-----
|
||||
|
||||
If none of the above options work, fork Flask. The majority of code of Flask
|
||||
is within Werkzeug and Jinja2. These libraries do the majority of the work.
|
||||
Flask is just the paste that glues those together. For every project there is
|
||||
the point where the underlying framework gets in the way (due to assumptions
|
||||
the original developers had). This is natural because if this would not be the
|
||||
case, the framework would be a very complex system to begin with which causes a
|
||||
steep learning curve and a lot of user frustration.
|
||||
|
||||
This is not unique to Flask. Many people use patched and modified
|
||||
versions of their framework to counter shortcomings. This idea is also
|
||||
reflected in the license of Flask. You don't have to contribute any
|
||||
changes back if you decide to modify the framework.
|
||||
|
||||
The downside of forking is of course that Flask extensions will most
|
||||
likely break because the new framework has a different import name.
|
||||
Furthermore integrating upstream changes can be a complex process,
|
||||
depending on the number of changes. Because of that, forking should be
|
||||
the very last resort.
|
||||
|
||||
Scale like a pro.
|
||||
-----------------
|
||||
|
||||
For many web applications the complexity of the code is less an issue than
|
||||
the scaling for the number of users or data entries expected. Flask by
|
||||
itself is only limited in terms of scaling by your application code, the
|
||||
data store you want to use and the Python implementation and webserver you
|
||||
are running on.
|
||||
|
||||
Scaling well means for example that if you double the amount of servers
|
||||
you get about twice the performance. Scaling bad means that if you add a
|
||||
new server the application won't perform any better or would not even
|
||||
support a second server.
|
||||
|
||||
There is only one limiting factor regarding scaling in Flask which are
|
||||
the context local proxies. They depend on context which in Flask is
|
||||
defined as being either a thread, process or greenlet. If your server
|
||||
uses some kind of concurrency that is not based on threads or greenlets,
|
||||
Flask will no longer be able to support these global proxies. However the
|
||||
majority of servers are using either threads, greenlets or separate
|
||||
processes to achieve concurrency which are all methods well supported by
|
||||
the underlying Werkzeug library.
|
||||
|
||||
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 Discord server. The best way for
|
||||
the Flask and Flask extension developers to improve the tools for larger
|
||||
applications is getting feedback from users.
|
||||
|
|
@ -299,9 +299,7 @@ used for public variables, such as ``FLASK_APP``, while :file:`.env` should not
|
|||
be committed to your repository so that it can set private variables.
|
||||
|
||||
Directories are scanned upwards from the directory you call ``flask``
|
||||
from to locate the files. The current working directory will be set to the
|
||||
location of the file, with the assumption that that is the top level project
|
||||
directory.
|
||||
from to locate the files.
|
||||
|
||||
The files are only loaded by the ``flask`` command or calling
|
||||
:meth:`~Flask.run`. If you would like to load these files when running in
|
||||
|
|
|
|||
|
|
@ -167,9 +167,6 @@ large applications harder to maintain. However Flask is just not designed
|
|||
for large applications or asynchronous servers. Flask wants to make it
|
||||
quick and easy to write a traditional web application.
|
||||
|
||||
Also see the :doc:`/becomingbig` section of the documentation for some
|
||||
inspiration for larger applications based on Flask.
|
||||
|
||||
|
||||
Async/await and ASGI support
|
||||
----------------------------
|
||||
|
|
|
|||
|
|
@ -271,16 +271,16 @@ 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
|
||||
`Discord server`_ to get some ideas for nice looking APIs. Especially if you do
|
||||
on `PyPI`_. If you feel lost there is `Discord Chat`_ or
|
||||
`GitHub Discussions`_ 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
|
||||
on pretty much the same problem.
|
||||
|
||||
Remember: good API design is hard, so introduce your project on the
|
||||
mailing list, and let other developers give you a helping hand with
|
||||
designing the API.
|
||||
Remember: good API design is hard, so introduce your project on
|
||||
`Discord Chat`_ or `GitHub Discussions`_, and let other developers give
|
||||
you a helping hand with designing the API.
|
||||
|
||||
The best Flask extensions are extensions that share common idioms for the
|
||||
API. And this can only work if collaboration happens early.
|
||||
|
|
@ -327,6 +327,6 @@ ecosystem remain consistent and compatible.
|
|||
indicate supported versions.
|
||||
|
||||
.. _PyPI: https://pypi.org/search/?c=Framework+%3A%3A+Flask
|
||||
.. _mailinglist: https://mail.python.org/mailman/listinfo/flask
|
||||
.. _Discord server: https://discord.gg/pallets
|
||||
.. _Discord Chat: https://discord.gg/pallets
|
||||
.. _GitHub Discussions: https://github.com/pallets/flask/discussions
|
||||
.. _Official Pallets Themes: https://pypi.org/project/Pallets-Sphinx-Themes/
|
||||
|
|
|
|||
|
|
@ -47,7 +47,7 @@ SQLAlchemy or another database tool, introduce non-relational data persistence
|
|||
as appropriate, and take advantage of framework-agnostic tools built for WSGI,
|
||||
the Python web interface.
|
||||
|
||||
Flask includes many hooks to customize its behavior. Should you need more
|
||||
customization, the Flask class is built for subclassing. If you are interested
|
||||
in that, check out the :doc:`becomingbig` chapter. If you are curious about
|
||||
the Flask design principles, head over to the section about :doc:`design`.
|
||||
Flask includes many hooks to customize its behavior. Should you need
|
||||
more customization, the Flask class is built for subclassing. If you are
|
||||
curious about the Flask design principles, head over to the section
|
||||
about :doc:`design`.
|
||||
|
|
|
|||
|
|
@ -58,7 +58,6 @@ instructions for web development with Flask.
|
|||
shell
|
||||
patterns/index
|
||||
deploying/index
|
||||
becomingbig
|
||||
async-await
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -173,10 +173,6 @@ You should then end up with something like that::
|
|||
ensuring the module is imported and we are doing that at the bottom of
|
||||
the file.
|
||||
|
||||
There are still some problems with that approach but if you want to use
|
||||
decorators there is no way around that. Check out the
|
||||
:doc:`/becomingbig` section for some inspiration how to deal with that.
|
||||
|
||||
|
||||
Working with Blueprints
|
||||
-----------------------
|
||||
|
|
|
|||
|
|
@ -9,6 +9,8 @@ from functools import update_wrapper
|
|||
from operator import attrgetter
|
||||
from threading import Lock
|
||||
from threading import Thread
|
||||
from typing import Any
|
||||
from typing import TYPE_CHECKING
|
||||
|
||||
import click
|
||||
from werkzeug.utils import import_string
|
||||
|
|
@ -36,7 +38,12 @@ else:
|
|||
# We technically have importlib.metadata on 3.8+,
|
||||
# but the API changed in 3.10, so use the backport
|
||||
# for consistency.
|
||||
import importlib_metadata as metadata # type: ignore
|
||||
if TYPE_CHECKING:
|
||||
metadata: Any
|
||||
else:
|
||||
# we do this to avoid a version dependent mypy error
|
||||
# because importlib_metadata is not installed in python3.10+
|
||||
import importlib_metadata as metadata
|
||||
|
||||
|
||||
class NoAppException(click.UsageError):
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue