diff --git a/.gitignore b/.gitignore index e50a290e..e6713351 100644 --- a/.gitignore +++ b/.gitignore @@ -11,7 +11,6 @@ dist/ build/ *.egg *.egg-info/ -_mailinglist .tox/ .cache/ .pytest_cache/ diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index a3c8b851..d5e3a3f7 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -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. diff --git a/docs/becomingbig.rst b/docs/becomingbig.rst deleted file mode 100644 index 5e7a88e0..00000000 --- a/docs/becomingbig.rst +++ /dev/null @@ -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 -`_. - -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. diff --git a/docs/cli.rst b/docs/cli.rst index 4b40307e..3be3aaa6 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -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 diff --git a/docs/design.rst b/docs/design.rst index 5d57063e..a5ef2568 100644 --- a/docs/design.rst +++ b/docs/design.rst @@ -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 ---------------------------- diff --git a/docs/extensiondev.rst b/docs/extensiondev.rst index dbaf62cb..34b118ce 100644 --- a/docs/extensiondev.rst +++ b/docs/extensiondev.rst @@ -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/ diff --git a/docs/foreword.rst b/docs/foreword.rst index 6a6d17f9..28b272d7 100644 --- a/docs/foreword.rst +++ b/docs/foreword.rst @@ -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`. diff --git a/docs/index.rst b/docs/index.rst index 6ff62529..c0066e8c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -58,7 +58,6 @@ instructions for web development with Flask. shell patterns/index deploying/index - becomingbig async-await diff --git a/docs/patterns/packages.rst b/docs/patterns/packages.rst index 7c3a34cf..a30ef3cb 100644 --- a/docs/patterns/packages.rst +++ b/docs/patterns/packages.rst @@ -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 ----------------------- diff --git a/src/flask/cli.py b/src/flask/cli.py index 36c4f1b6..efcc0f99 100644 --- a/src/flask/cli.py +++ b/src/flask/cli.py @@ -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):