diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml index 733676b4..7ad21db9 100644 --- a/.github/workflows/tests.yaml +++ b/.github/workflows/tests.yaml @@ -36,7 +36,7 @@ jobs: - {name: 'Pallets Development Versions', python: '3.7', os: ubuntu-latest, tox: py-dev} - {name: Typing, python: '3.10', os: ubuntu-latest, tox: typing} steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 - uses: actions/setup-python@v3 with: python-version: ${{ matrix.python }} 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/.pre-commit-config.yaml b/.pre-commit-config.yaml index fa395c57..e5a89e66 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -3,7 +3,7 @@ ci: autoupdate_schedule: monthly repos: - repo: https://github.com/asottile/pyupgrade - rev: v2.32.0 + rev: v2.32.1 hooks: - id: pyupgrade args: ["--py36-plus"] diff --git a/CHANGES.rst b/CHANGES.rst index 0e4bebfa..ce85e673 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,5 +1,43 @@ .. currentmodule:: flask +Version 2.2.0 +------------- + +Unreleased + +- Add new customization points to the ``Flask`` app object for many + previously global behaviors. + + - ``flask.url_for`` will call ``app.url_for``. :issue:`4568` + - ``flask.abort`` will call ``app.aborter``. + ``Flask.aborter_class`` and ``Flask.make_aborter`` can be used + to customize this aborter. :issue:`4567` + - ``flask.redirect`` will call ``app.redirect``. :issue:`4569` + +- Refactor ``register_error_handler`` to consolidate error checking. + Rewrite some error messages to be more consistent. :issue:`4559` +- Use Blueprint decorators and functions intended for setup after + registering the blueprint will show a warning. In the next version, + this will become an error just like the application setup methods. + :issue:`4571` +- ``before_first_request`` is deprecated. Run setup code when creating + the application instead. :issue:`4605` +- Added the ``View.init_every_request`` class attribute. If a view + subclass sets this to ``False``, the view will not create a new + instance on every request. :issue:`2520`. + +Version 2.1.3 +------------- + +Unreleased + +- Inline some optional imports that are only used for certain CLI + commands. :pr:`4606` +- Relax type annotation for ``after_request`` functions. :issue:`4600` +- ``instance_path`` for namespace packages uses the path closest to + the imported submodule. :issue:`4600` + + Version 2.1.2 ------------- @@ -998,8 +1036,7 @@ Released 2011-09-29, codename Rakija earlier feedback when users forget to import view code ahead of time. - Added the ability to register callbacks that are only triggered once - at the beginning of the first request. - (:meth:`Flask.before_first_request`) + at the beginning of the first request. (``before_first_request``) - Malformed JSON data will now trigger a bad request HTTP exception instead of a value error which usually would result in a 500 internal server error if not handled. This is a backwards 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/celery.rst b/docs/patterns/celery.rst index 38a9a025..228a04a8 100644 --- a/docs/patterns/celery.rst +++ b/docs/patterns/celery.rst @@ -34,17 +34,15 @@ Celery without any reconfiguration with Flask, it becomes a bit nicer by subclassing tasks and adding support for Flask's application contexts and hooking it up with the Flask configuration. -This is all that is necessary to properly integrate Celery with Flask:: +This is all that is necessary to integrate Celery with Flask: + +.. code-block:: python from celery import Celery def make_celery(app): - celery = Celery( - app.import_name, - backend=app.config['CELERY_RESULT_BACKEND'], - broker=app.config['CELERY_BROKER_URL'] - ) - celery.conf.update(app.config) + celery = Celery(app.import_name) + celery.conf.update(app.config["CELERY_CONFIG"]) class ContextTask(celery.Task): def __call__(self, *args, **kwargs): @@ -59,6 +57,12 @@ from the application config, updates the rest of the Celery config from the Flask config and then creates a subclass of the task that wraps the task execution in an application context. +.. note:: + Celery 5.x deprecated uppercase configuration keys, and 6.x will + remove them. See their official `migration guide`_. + +.. _migration guide: https://docs.celeryproject.org/en/stable/userguide/configuration.html#conf-old-settings-map. + An example task --------------- @@ -69,10 +73,10 @@ application using the factory from above, and then use it to define the task. :: from flask import Flask flask_app = Flask(__name__) - flask_app.config.update( - CELERY_BROKER_URL='redis://localhost:6379', - CELERY_RESULT_BACKEND='redis://localhost:6379' - ) + flask_app.config.update(CELERY_CONFIG={ + 'broker_url': 'redis://localhost:6379', + 'result_backend': 'redis://localhost:6379', + }) celery = make_celery(flask_app) @celery.task() 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/docs/testing.rst b/docs/testing.rst index 6f9d6ee1..8545bd39 100644 --- a/docs/testing.rst +++ b/docs/testing.rst @@ -92,7 +92,7 @@ The ``client`` has methods that match the common HTTP request methods, such as ``client.get()`` and ``client.post()``. They take many arguments for building the request; you can find the full documentation in :class:`~werkzeug.test.EnvironBuilder`. Typically you'll use ``path``, -``query``, ``headers``, and ``data`` or ``json``. +``query_string``, ``headers``, and ``data`` or ``json``. To make a request, call the method the request should use with the path to the route to test. A :class:`~werkzeug.test.TestResponse` is returned @@ -108,9 +108,9 @@ provides ``response.text``, or use ``response.get_data(as_text=True)``. assert b"

Hello, World!

" in response.data -Pass a dict ``query={"key": "value", ...}`` to set arguments in the -query string (after the ``?`` in the URL). Pass a dict ``headers={}`` -to set request headers. +Pass a dict ``query_string={"key": "value", ...}`` to set arguments in +the query string (after the ``?`` in the URL). Pass a dict +``headers={}`` to set request headers. To send a request body in a POST or PUT request, pass a value to ``data``. If raw bytes are passed, that exact body is used. Usually, diff --git a/docs/tutorial/install.rst b/docs/tutorial/install.rst index 3d7d7c60..9e808f14 100644 --- a/docs/tutorial/install.rst +++ b/docs/tutorial/install.rst @@ -67,10 +67,12 @@ This tells Python to copy everything in the ``static`` and ``templates`` directories, and the ``schema.sql`` file, but to exclude all bytecode files. -See the `official packaging guide`_ for another explanation of the files +See the official `Packaging tutorial `_ and +`detailed guide `_ for more explanation of the files and options used. -.. _official packaging guide: https://packaging.python.org/tutorials/packaging-projects/ +.. _packaging tutorial: https://packaging.python.org/tutorials/packaging-projects/ +.. _packaging guide: https://packaging.python.org/guides/distributing-packages-using-setuptools/ Install the Project diff --git a/docs/views.rst b/docs/views.rst index 63d26c5c..b7c5ba20 100644 --- a/docs/views.rst +++ b/docs/views.rst @@ -1,235 +1,319 @@ -Pluggable Views -=============== +Class-based Views +================= -.. versionadded:: 0.7 +.. currentmodule:: flask.views -Flask 0.7 introduces pluggable views inspired by the generic views from -Django which are based on classes instead of functions. The main -intention is that you can replace parts of the implementations and this -way have customizable pluggable views. +This page introduces using the :class:`View` and :class:`MethodView` +classes to write class-based views. -Basic Principle ---------------- +A class-based view is a class that acts as a view function. Because it +is a class, different instances of the class can be created with +different arguments, to change the behavior of the view. This is also +known as generic, reusable, or pluggable views. -Consider you have a function that loads a list of objects from the -database and renders into a template:: +An example of where this is useful is defining a class that creates an +API based on the database model it is initialized with. - @app.route('/users/') - def show_users(page): +For more complex API behavior and customization, look into the various +API extensions for Flask. + + +Basic Reusable View +------------------- + +Let's walk through an example converting a view function to a view +class. We start with a view function that queries a list of users then +renders a template to show the list. + +.. code-block:: python + + @app.route("/users/") + def user_list(): users = User.query.all() - return render_template('users.html', users=users) + return render_template("users.html", users=users) -This is simple and flexible, but if you want to provide this view in a -generic fashion that can be adapted to other models and templates as well -you might want more flexibility. This is where pluggable class-based -views come into place. As the first step to convert this into a class -based view you would do this:: +This works for the user model, but let's say you also had more models +that needed list pages. You'd need to write another view function for +each model, even though the only thing that would change is the model +and template name. +Instead, you can write a :class:`View` subclass that will query a model +and render a template. As the first step, we'll convert the view to a +class without any customization. + +.. code-block:: python from flask.views import View - class ShowUsers(View): - + class UserList(View): def dispatch_request(self): users = User.query.all() - return render_template('users.html', objects=users) + return render_template("users.html", objects=users) - app.add_url_rule('/users/', view_func=ShowUsers.as_view('show_users')) + app.add_url_rule("/users/", view_func=UserList.as_view("user_list")) -As you can see what you have to do is to create a subclass of -:class:`flask.views.View` and implement -:meth:`~flask.views.View.dispatch_request`. Then we have to convert that -class into an actual view function by using the -:meth:`~flask.views.View.as_view` class method. The string you pass to -that function is the name of the endpoint that view will then have. But -this by itself is not helpful, so let's refactor the code a bit:: +The :meth:`View.dispatch_request` method is the equivalent of the view +function. Calling :meth:`View.as_view` method will create a view +function that can be registered on the app with its +:meth:`~flask.Flask.add_url_rule` method. The first argument to +``as_view`` is the name to use to refer to the view with +:func:`~flask.url_for`. +.. note:: - from flask.views import View + You can't decorate the class with ``@app.route()`` the way you'd + do with a basic view function. + +Next, we need to be able to register the same view class for different +models and templates, to make it more useful than the original function. +The class will take two arguments, the model and template, and store +them on ``self``. Then ``dispatch_request`` can reference these instead +of hard-coded values. + +.. code-block:: python class ListView(View): - - def get_template_name(self): - raise NotImplementedError() - - def render_template(self, context): - return render_template(self.get_template_name(), **context) + def __init__(self, model, template): + self.model = model + self.template = template def dispatch_request(self): - context = {'objects': self.get_objects()} - return self.render_template(context) + items = self.model.query.all() + return render_template(self.template, items=items) - class UserView(ListView): +Remember, we create the view function with ``View.as_view()`` instead of +creating the class directly. Any extra arguments passed to ``as_view`` +are then passed when creating the class. Now we can register the same +view to handle multiple models. - def get_template_name(self): - return 'users.html' +.. code-block:: python - def get_objects(self): - return User.query.all() + app.add_url_rule( + "/users/", + view_func=ListView.as_view("user_list", User, "users.html"), + ) + app.add_url_rule( + "/stories/", + view_func=ListView.as_view("story_list", Story, "stories.html"), + ) -This of course is not that helpful for such a small example, but it's good -enough to explain the basic principle. When you have a class-based view -the question comes up what ``self`` points to. The way this works is that -whenever the request is dispatched a new instance of the class is created -and the :meth:`~flask.views.View.dispatch_request` method is called with -the parameters from the URL rule. The class itself is instantiated with -the parameters passed to the :meth:`~flask.views.View.as_view` function. -For instance you can write a class like this:: - class RenderTemplateView(View): - def __init__(self, template_name): - self.template_name = template_name +URL Variables +------------- + +Any variables captured by the URL are passed as keyword arguments to the +``dispatch_request`` method, as they would be for a regular view +function. + +.. code-block:: python + + class DetailView(View): + def __init__(self, model): + self.model = model + self.template = f"{model.__name__.lower()}/detail.html" + + def dispatch_request(self, id) + item = self.model.query.get_or_404(id) + return render_template(self.template, item=item) + + app.add_url_rule("/users/", view_func=DetailView.as_view("user_detail")) + + +View Lifetime and ``self`` +-------------------------- + +By default, a new instance of the view class is created every time a +request is handled. This means that it is safe to write other data to +``self`` during the request, since the next request will not see it, +unlike other forms of global state. + +However, if your view class needs to do a lot of complex initialization, +doing it for every request is unnecessary and can be inefficient. To +avoid this, set :attr:`View.init_every_request` to ``False``, which will +only create one instance of the class and use it for every request. In +this case, writing to ``self`` is not safe. If you need to store data +during the request, use :data:`~flask.g` instead. + +In the ``ListView`` example, nothing writes to ``self`` during the +request, so it is more efficient to create a single instance. + +.. code-block:: python + + class ListView(View): + init_every_request = False + + def __init__(self, model, template): + self.model = model + self.template = template + def dispatch_request(self): - return render_template(self.template_name) + items = self.model.query.all() + return render_template(self.template, items=items) -And then you can register it like this:: +Different instances will still be created each for each ``as_view`` +call, but not for each request to those views. + + +View Decorators +--------------- + +The view class itself is not the view function. View decorators need to +be applied to the view function returned by ``as_view``, not the class +itself. Set :attr:`View.decorators` to a list of decorators to apply. + +.. code-block:: python + + class UserList(View): + decorators = [cache(minutes=2), login_required] + + app.add_url_rule('/users/', view_func=UserList.as_view()) + +If you didn't set ``decorators``, you could apply them manually instead. +This is equivalent to: + +.. code-block:: python + + view = UserList.as_view("users_list") + view = cache(minutes=2)(view) + view = login_required(view) + app.add_url_rule('/users/', view_func=view) + +Keep in mind that order matters. If you're used to ``@decorator`` style, +this is equivalent to: + +.. code-block:: python + + @app.route("/users/") + @login_required + @cache(minutes=2) + def user_list(): + ... - app.add_url_rule('/about', view_func=RenderTemplateView.as_view( - 'about_page', template_name='about.html')) Method Hints ------------ -Pluggable views are attached to the application like a regular function by -either using :func:`~flask.Flask.route` or better -:meth:`~flask.Flask.add_url_rule`. That however also means that you would -have to provide the names of the HTTP methods the view supports when you -attach this. In order to move that information to the class you can -provide a :attr:`~flask.views.View.methods` attribute that has this -information:: +A common pattern is to register a view with ``methods=["GET", "POST"]``, +then check ``request.method == "POST"`` to decide what to do. Setting +:attr:`View.methods` is equivalent to passing the list of methods to +``add_url_rule`` or ``route``. + +.. code-block:: python class MyView(View): - methods = ['GET', 'POST'] + methods = ["GET", "POST"] def dispatch_request(self): - if request.method == 'POST': + if request.method == "POST": ... ... - app.add_url_rule('/myview', view_func=MyView.as_view('myview')) + app.add_url_rule('/my-view', view_func=MyView.as_view('my-view')) -Method Based Dispatching ------------------------- +This is equivalent to the following, except further subclasses can +inherit or change the methods. -For RESTful APIs it's especially helpful to execute a different function -for each HTTP method. With the :class:`flask.views.MethodView` you can -easily do that. Each HTTP method maps to a method of the class with the -same name (just in lowercase):: +.. code-block:: python + + app.add_url_rule( + "/my-view", + view_func=MyView.as_view("my-view"), + methods=["GET", "POST"], + ) + + +Method Dispatching and APIs +--------------------------- + +For APIs it can be helpful to use a different function for each HTTP +method. :class:`MethodView` extends the basic :class:`View` to dispatch +to different methods of the class based on the request method. Each HTTP +method maps to a method of the class with the same (lowercase) name. + +:class:`MethodView` automatically sets :attr:`View.methods` based on the +methods defined by the class. It even knows how to handle subclasses +that override or define other methods. + +We can make a generic ``ItemAPI`` class that provides get (detail), +patch (edit), and delete methods for a given model. A ``GroupAPI`` can +provide get (list) and post (create) methods. + +.. code-block:: python from flask.views import MethodView - class UserAPI(MethodView): + class ItemAPI(MethodView): + init_every_request = False + + def __init__(self, model): + self.model + self.validator = generate_validator(model) + + def _get_item(self, id): + return self.model.query.get_or_404(id) + + def get(self, id): + user = self._get_item(id) + return jsonify(item.to_json()) + + def patch(self, id): + item = self._get_item(id) + errors = self.validator.validate(item, request.json) + + if errors: + return jsonify(errors), 400 + + item.update_from_json(request.json) + db.session.commit() + return jsonify(item.to_json()) + + def delete(self, id): + item = self._get_item(id) + db.session.delete(item) + db.session.commit() + return "", 204 + + class GroupAPI(MethodView): + init_every_request = False + + def __init__(self, model): + self.model = model + self.validator = generate_validator(model, create=True) def get(self): - users = User.query.all() - ... + items = self.model.query.all() + return jsonify([item.to_json() for item in items]) def post(self): - user = User.from_form_data(request.form) - ... + errors = self.validator.validate(request.json) - app.add_url_rule('/users/', view_func=UserAPI.as_view('users')) + if errors: + return jsonify(errors), 400 -That way you also don't have to provide the -:attr:`~flask.views.View.methods` attribute. It's automatically set based -on the methods defined in the class. + db.session.add(self.model.from_json(request.json)) + db.session.commit() + return jsonify(item.to_json()) -Decorating Views ----------------- + def register_api(app, model, url): + app.add_url_rule(f"/{name}/", view_func=ItemAPI(f"{name}-item", model)) + app.add_url_rule(f"/{name}/", view_func=GroupAPI(f"{name}-group", model)) -Since the view class itself is not the view function that is added to the -routing system it does not make much sense to decorate the class itself. -Instead you either have to decorate the return value of -:meth:`~flask.views.View.as_view` by hand:: + register_api(app, User, "users") + register_api(app, Story, "stories") - def user_required(f): - """Checks whether user is logged in or raises error 401.""" - def decorator(*args, **kwargs): - if not g.user: - abort(401) - return f(*args, **kwargs) - return decorator +This produces the following views, a standard REST API! - view = user_required(UserAPI.as_view('users')) - app.add_url_rule('/users/', view_func=view) - -Starting with Flask 0.8 there is also an alternative way where you can -specify a list of decorators to apply in the class declaration:: - - class UserAPI(MethodView): - decorators = [user_required] - -Due to the implicit self from the caller's perspective you cannot use -regular view decorators on the individual methods of the view however, -keep this in mind. - -Method Views for APIs ---------------------- - -Web APIs are often working very closely with HTTP verbs so it makes a lot -of sense to implement such an API based on the -:class:`~flask.views.MethodView`. That said, you will notice that the API -will require different URL rules that go to the same method view most of -the time. For instance consider that you are exposing a user object on -the web: - -=============== =============== ====================================== -URL Method Description ---------------- --------------- -------------------------------------- -``/users/`` ``GET`` Gives a list of all users -``/users/`` ``POST`` Creates a new user -``/users/`` ``GET`` Shows a single user -``/users/`` ``PUT`` Updates a single user -``/users/`` ``DELETE`` Deletes a single user -=============== =============== ====================================== - -So how would you go about doing that with the -:class:`~flask.views.MethodView`? The trick is to take advantage of the -fact that you can provide multiple rules to the same view. - -Let's assume for the moment the view would look like this:: - - class UserAPI(MethodView): - - def get(self, user_id): - if user_id is None: - # return a list of users - pass - else: - # expose a single user - pass - - def post(self): - # create a new user - pass - - def delete(self, user_id): - # delete a single user - pass - - def put(self, user_id): - # update a single user - pass - -So how do we hook this up with the routing system? By adding two rules -and explicitly mentioning the methods for each:: - - user_view = UserAPI.as_view('user_api') - app.add_url_rule('/users/', defaults={'user_id': None}, - view_func=user_view, methods=['GET',]) - app.add_url_rule('/users/', view_func=user_view, methods=['POST',]) - app.add_url_rule('/users/', view_func=user_view, - methods=['GET', 'PUT', 'DELETE']) - -If you have a lot of APIs that look similar you can refactor that -registration code:: - - def register_api(view, endpoint, url, pk='id', pk_type='int'): - view_func = view.as_view(endpoint) - app.add_url_rule(url, defaults={pk: None}, - view_func=view_func, methods=['GET',]) - app.add_url_rule(url, view_func=view_func, methods=['POST',]) - app.add_url_rule(f'{url}<{pk_type}:{pk}>', view_func=view_func, - methods=['GET', 'PUT', 'DELETE']) - - register_api(UserAPI, 'user_api', '/users/', pk='user_id') +================= ========== =================== +URL Method Description +----------------- ---------- ------------------- +``/users/`` ``GET`` List all users +``/users/`` ``POST`` Create a new user +``/users/`` ``GET`` Show a single user +``/users/`` ``PATCH`` Update a user +``/users/`` ``DELETE`` Delete a user +``/stories/`` ``GET`` List all stories +``/stories/`` ``POST`` Create a new story +``/stories/`` ``GET`` Show a single story +``/stories/`` ``PATCH`` Update a story +``/stories/`` ``DELETE`` Delete a story +================= ========== =================== diff --git a/requirements/dev.txt b/requirements/dev.txt index 36999074..3667056d 100644 --- a/requirements/dev.txt +++ b/requirements/dev.txt @@ -10,19 +10,19 @@ -r typing.txt cfgv==3.3.1 # via pre-commit -click==8.1.2 +click==8.1.3 # via # pip-compile-multi # pip-tools distlib==0.3.4 # via virtualenv -filelock==3.6.0 +filelock==3.7.1 # via # tox # virtualenv greenlet==1.1.2 ; python_version < "3.11" # via -r requirements/tests.in -identify==2.5.0 +identify==2.5.1 # via pre-commit nodeenv==1.6.0 # via pre-commit @@ -30,11 +30,11 @@ pep517==0.12.0 # via pip-tools pip-compile-multi==2.4.5 # via -r requirements/dev.in -pip-tools==6.6.0 +pip-tools==6.6.2 # via pip-compile-multi platformdirs==2.5.2 # via virtualenv -pre-commit==2.18.1 +pre-commit==2.19.0 # via -r requirements/dev.in pyyaml==6.0 # via pre-commit diff --git a/requirements/docs.txt b/requirements/docs.txt index 963d81e9..f94d30b8 100644 --- a/requirements/docs.txt +++ b/requirements/docs.txt @@ -9,7 +9,7 @@ alabaster==0.7.12 # via sphinx babel==2.10.1 # via sphinx -certifi==2021.10.8 +certifi==2022.5.18.1 # via requests charset-normalizer==2.0.12 # via requests @@ -21,7 +21,7 @@ idna==3.3 # via requests imagesize==1.3.0 # via sphinx -jinja2==3.1.1 +jinja2==3.1.2 # via sphinx markupsafe==2.1.1 # via jinja2 @@ -35,7 +35,7 @@ pygments==2.12.0 # via # sphinx # sphinx-tabs -pyparsing==3.0.8 +pyparsing==3.0.9 # via packaging pytz==2022.1 # via babel diff --git a/requirements/tests.txt b/requirements/tests.txt index 7833cabd..7a3f89d7 100644 --- a/requirements/tests.txt +++ b/requirements/tests.txt @@ -5,7 +5,7 @@ # # pip-compile-multi # -asgiref==3.5.0 +asgiref==3.5.2 # via -r requirements/tests.in attrs==21.4.0 # via pytest @@ -21,7 +21,7 @@ pluggy==1.0.0 # via pytest py==1.11.0 # via pytest -pyparsing==3.0.8 +pyparsing==3.0.9 # via packaging pytest==7.1.2 # via -r requirements/tests.in diff --git a/requirements/typing.txt b/requirements/typing.txt index f1aa5284..2e17dfb6 100644 --- a/requirements/typing.txt +++ b/requirements/typing.txt @@ -7,9 +7,9 @@ # cffi==1.15.0 # via cryptography -cryptography==37.0.1 +cryptography==37.0.2 # via -r requirements/typing.in -mypy==0.950 +mypy==0.960 # via -r requirements/typing.in mypy-extensions==0.4.3 # via mypy @@ -17,11 +17,11 @@ pycparser==2.21 # via cffi tomli==2.0.1 # via mypy -types-contextvars==2.4.5 +types-contextvars==2.4.6 # via -r requirements/typing.in types-dataclasses==0.6.5 # via -r requirements/typing.in -types-setuptools==57.4.14 +types-setuptools==57.4.17 # via -r requirements/typing.in typing-extensions==4.2.0 # via mypy diff --git a/setup.cfg b/setup.cfg index 31a590a4..e858d13a 100644 --- a/setup.cfg +++ b/setup.cfg @@ -87,7 +87,7 @@ per-file-ignores = src/flask/__init__.py: F401 [mypy] -files = src/flask +files = src/flask, tests/typing python_version = 3.7 show_error_codes = True allow_redefinition = True @@ -116,3 +116,6 @@ ignore_missing_imports = True [mypy-cryptography.*] ignore_missing_imports = True + +[mypy-importlib_metadata] +ignore_missing_imports = True diff --git a/src/flask/__init__.py b/src/flask/__init__.py index f684f57a..bc93e0a3 100644 --- a/src/flask/__init__.py +++ b/src/flask/__init__.py @@ -1,7 +1,5 @@ from markupsafe import escape from markupsafe import Markup -from werkzeug.exceptions import abort as abort -from werkzeug.utils import redirect as redirect from . import json as json from .app import Flask as Flask @@ -19,10 +17,12 @@ from .globals import current_app as current_app from .globals import g as g from .globals import request as request from .globals import session as session +from .helpers import abort as abort from .helpers import flash as flash from .helpers import get_flashed_messages as get_flashed_messages from .helpers import get_template_attribute as get_template_attribute from .helpers import make_response as make_response +from .helpers import redirect as redirect from .helpers import send_file as send_file from .helpers import send_from_directory as send_from_directory from .helpers import stream_with_context as stream_with_context @@ -42,4 +42,4 @@ from .signals import template_rendered as template_rendered from .templating import render_template as render_template from .templating import render_template_string as render_template_string -__version__ = "2.1.2" +__version__ = "2.2.0.dev0" diff --git a/src/flask/app.py b/src/flask/app.py index 348bc7f7..65e95623 100644 --- a/src/flask/app.py +++ b/src/flask/app.py @@ -12,6 +12,7 @@ from types import TracebackType from werkzeug.datastructures import Headers from werkzeug.datastructures import ImmutableDict +from werkzeug.exceptions import Aborter from werkzeug.exceptions import BadRequest from werkzeug.exceptions import BadRequestKeyError from werkzeug.exceptions import HTTPException @@ -22,15 +23,19 @@ from werkzeug.routing import MapAdapter from werkzeug.routing import RequestRedirect from werkzeug.routing import RoutingException from werkzeug.routing import Rule +from werkzeug.urls import url_quote +from werkzeug.utils import redirect as _wz_redirect from werkzeug.wrappers import Response as BaseResponse from . import cli from . import json +from . import typing as ft from .config import Config from .config import ConfigAttribute from .ctx import _AppCtxGlobals from .ctx import AppContext from .ctx import RequestContext +from .globals import _app_ctx_stack from .globals import _request_ctx_stack from .globals import g from .globals import request @@ -41,7 +46,6 @@ from .helpers import get_env from .helpers import get_flashed_messages from .helpers import get_load_dotenv from .helpers import locked_cached_property -from .helpers import url_for from .json import jsonify from .logging import create_logger from .scaffold import _endpoint_from_view_func @@ -58,21 +62,14 @@ from .signals import request_started from .signals import request_tearing_down from .templating import DispatchingJinjaLoader from .templating import Environment -from .typing import BeforeFirstRequestCallable -from .typing import ResponseReturnValue -from .typing import TeardownCallable -from .typing import TemplateFilterCallable -from .typing import TemplateGlobalCallable -from .typing import TemplateTestCallable from .wrappers import Request from .wrappers import Response -if t.TYPE_CHECKING: +if t.TYPE_CHECKING: # pragma: no cover import typing_extensions as te from .blueprints import Blueprint from .testing import FlaskClient from .testing import FlaskCliRunner - from .typing import ErrorHandlerCallable if sys.version_info >= (3, 8): iscoroutinefunction = inspect.iscoroutinefunction @@ -200,6 +197,16 @@ class Flask(Scaffold): #: :class:`~flask.Response` for more information. response_class = Response + #: The class of the object assigned to :attr:`aborter`, created by + #: :meth:`create_aborter`. That object is called by + #: :func:`flask.abort` to raise HTTP errors, and can be + #: called directly as well. + #: + #: Defaults to :class:`werkzeug.exceptions.Aborter`. + #: + #: .. versionadded:: 2.2 + aborter_class = Aborter + #: The class that is used for the Jinja environment. #: #: .. versionadded:: 0.11 @@ -420,23 +427,36 @@ class Flask(Scaffold): #: to load a config from files. self.config = self.make_config(instance_relative_config) - #: A list of functions that are called when :meth:`url_for` raises a - #: :exc:`~werkzeug.routing.BuildError`. Each function registered here - #: is called with `error`, `endpoint` and `values`. If a function - #: returns ``None`` or raises a :exc:`BuildError` the next function is - #: tried. + #: An instance of :attr:`aborter_class` created by + #: :meth:`make_aborter`. This is called by :func:`flask.abort` + #: to raise HTTP errors, and can be called directly as well. + #: + #: .. versionadded:: 2.2 + #: Moved from ``flask.abort``, which calls this object. + self.aborter = self.make_aborter() + + #: A list of functions that are called by + #: :meth:`handle_url_build_error` when :meth:`.url_for` raises a + #: :exc:`~werkzeug.routing.BuildError`. Each function is called + #: with ``error``, ``endpoint`` and ``values``. If a function + #: returns ``None`` or raises a ``BuildError``, it is skipped. + #: Otherwise, its return value is returned by ``url_for``. #: #: .. versionadded:: 0.9 self.url_build_error_handlers: t.List[ - t.Callable[[Exception, str, dict], str] + t.Callable[[Exception, str, t.Dict[str, t.Any]], str] ] = [] #: A list of functions that will be called at the beginning of the #: first request to this instance. To register a function, use the #: :meth:`before_first_request` decorator. #: + #: .. deprecated:: 2.2 + #: Will be removed in Flask 2.3. Run setup code when + #: creating the application instead. + #: #: .. versionadded:: 0.8 - self.before_first_request_funcs: t.List[BeforeFirstRequestCallable] = [] + self.before_first_request_funcs: t.List[ft.BeforeFirstRequestCallable] = [] #: A list of functions that are called when the application context #: is destroyed. Since the application context is also torn down @@ -444,7 +464,7 @@ class Flask(Scaffold): #: from databases. #: #: .. versionadded:: 0.9 - self.teardown_appcontext_funcs: t.List[TeardownCallable] = [] + self.teardown_appcontext_funcs: t.List[ft.TeardownCallable] = [] #: A list of shell context processor functions that should be run #: when a shell context is created. @@ -519,8 +539,17 @@ class Flask(Scaffold): # the app's commands to another CLI tool. self.cli.name = self.name - def _is_setup_finished(self) -> bool: - return self.debug and self._got_first_request + def _check_setup_finished(self, f_name: str) -> None: + if self._got_first_request: + raise AssertionError( + f"The setup method '{f_name}' can no longer be called" + " on the application. It has already handled its first" + " request, any changes will not be applied" + " consistently.\n" + "Make sure all imports, decorators, functions, etc." + " needed to set up the application are done before" + " running it." + ) @locked_cached_property def name(self) -> str: # type: ignore @@ -627,6 +656,18 @@ class Flask(Scaffold): defaults["DEBUG"] = get_debug_flag() return self.config_class(root_path, defaults) + def make_aborter(self) -> Aborter: + """Create the object to assign to :attr:`aborter`. That object + is called by :func:`flask.abort` to raise HTTP errors, and can + be called directly as well. + + By default, this creates an instance of :attr:`aborter_class`, + which defaults to :class:`werkzeug.exceptions.Aborter`. + + .. versionadded:: 2.2 + """ + return self.aborter_class() + def auto_find_instance_path(self) -> str: """Tries to locate the instance path if it was not provided to the constructor of the application class. It will basically calculate @@ -693,7 +734,7 @@ class Flask(Scaffold): rv = self.jinja_environment(self, **options) rv.globals.update( - url_for=url_for, + url_for=self.url_for, get_flashed_messages=get_flashed_messages, config=self.config, # request, session and g are normally added with the @@ -1039,7 +1080,7 @@ class Flask(Scaffold): self, rule: str, endpoint: t.Optional[str] = None, - view_func: t.Optional[t.Callable] = None, + view_func: t.Optional[ft.ViewCallable] = None, provide_automatic_options: t.Optional[bool] = None, **options: t.Any, ) -> None: @@ -1096,7 +1137,7 @@ class Flask(Scaffold): @setupmethod def template_filter( self, name: t.Optional[str] = None - ) -> t.Callable[[TemplateFilterCallable], TemplateFilterCallable]: + ) -> t.Callable[[ft.TemplateFilterCallable], ft.TemplateFilterCallable]: """A decorator that is used to register custom template filter. You can specify a name for the filter, otherwise the function name will be used. Example:: @@ -1109,7 +1150,7 @@ class Flask(Scaffold): function name will be used. """ - def decorator(f: TemplateFilterCallable) -> TemplateFilterCallable: + def decorator(f: ft.TemplateFilterCallable) -> ft.TemplateFilterCallable: self.add_template_filter(f, name=name) return f @@ -1117,7 +1158,7 @@ class Flask(Scaffold): @setupmethod def add_template_filter( - self, f: TemplateFilterCallable, name: t.Optional[str] = None + self, f: ft.TemplateFilterCallable, name: t.Optional[str] = None ) -> None: """Register a custom template filter. Works exactly like the :meth:`template_filter` decorator. @@ -1130,7 +1171,7 @@ class Flask(Scaffold): @setupmethod def template_test( self, name: t.Optional[str] = None - ) -> t.Callable[[TemplateTestCallable], TemplateTestCallable]: + ) -> t.Callable[[ft.TemplateTestCallable], ft.TemplateTestCallable]: """A decorator that is used to register custom template test. You can specify a name for the test, otherwise the function name will be used. Example:: @@ -1150,7 +1191,7 @@ class Flask(Scaffold): function name will be used. """ - def decorator(f: TemplateTestCallable) -> TemplateTestCallable: + def decorator(f: ft.TemplateTestCallable) -> ft.TemplateTestCallable: self.add_template_test(f, name=name) return f @@ -1158,7 +1199,7 @@ class Flask(Scaffold): @setupmethod def add_template_test( - self, f: TemplateTestCallable, name: t.Optional[str] = None + self, f: ft.TemplateTestCallable, name: t.Optional[str] = None ) -> None: """Register a custom template test. Works exactly like the :meth:`template_test` decorator. @@ -1173,7 +1214,7 @@ class Flask(Scaffold): @setupmethod def template_global( self, name: t.Optional[str] = None - ) -> t.Callable[[TemplateGlobalCallable], TemplateGlobalCallable]: + ) -> t.Callable[[ft.TemplateGlobalCallable], ft.TemplateGlobalCallable]: """A decorator that is used to register a custom template global function. You can specify a name for the global function, otherwise the function name will be used. Example:: @@ -1188,7 +1229,7 @@ class Flask(Scaffold): function name will be used. """ - def decorator(f: TemplateGlobalCallable) -> TemplateGlobalCallable: + def decorator(f: ft.TemplateGlobalCallable) -> ft.TemplateGlobalCallable: self.add_template_global(f, name=name) return f @@ -1196,7 +1237,7 @@ class Flask(Scaffold): @setupmethod def add_template_global( - self, f: TemplateGlobalCallable, name: t.Optional[str] = None + self, f: ft.TemplateGlobalCallable, name: t.Optional[str] = None ) -> None: """Register a custom template global function. Works exactly like the :meth:`template_global` decorator. @@ -1210,21 +1251,34 @@ class Flask(Scaffold): @setupmethod def before_first_request( - self, f: BeforeFirstRequestCallable - ) -> BeforeFirstRequestCallable: + self, f: ft.BeforeFirstRequestCallable + ) -> ft.BeforeFirstRequestCallable: """Registers a function to be run before the first request to this instance of the application. The function will be called without any arguments and its return value is ignored. + .. deprecated:: 2.2 + Will be removed in Flask 2.3. Run setup code when creating + the application instead. + .. versionadded:: 0.8 """ + import warnings + + warnings.warn( + "'before_first_request' is deprecated and will be removed" + " in Flask 2.3. Run setup code while creating the" + " application instead.", + DeprecationWarning, + stacklevel=2, + ) self.before_first_request_funcs.append(f) return f @setupmethod - def teardown_appcontext(self, f: TeardownCallable) -> TeardownCallable: + def teardown_appcontext(self, f: ft.TeardownCallable) -> ft.TeardownCallable: """Registers a function to be called when the application context ends. These functions are typically also called when the request context is popped. @@ -1265,7 +1319,7 @@ class Flask(Scaffold): self.shell_context_processors.append(f) return f - def _find_error_handler(self, e: Exception) -> t.Optional["ErrorHandlerCallable"]: + def _find_error_handler(self, e: Exception) -> t.Optional[ft.ErrorHandlerCallable]: """Return a registered error handler for an exception in this order: blueprint handler for a specific code, app handler for a specific code, blueprint handler for an exception class, app handler for an exception @@ -1290,7 +1344,7 @@ class Flask(Scaffold): def handle_http_exception( self, e: HTTPException - ) -> t.Union[HTTPException, ResponseReturnValue]: + ) -> t.Union[HTTPException, ft.ResponseReturnValue]: """Handles an HTTP exception. By default this will invoke the registered error handlers and fall back to returning the exception as response. @@ -1360,7 +1414,7 @@ class Flask(Scaffold): def handle_user_exception( self, e: Exception - ) -> t.Union[HTTPException, ResponseReturnValue]: + ) -> t.Union[HTTPException, ft.ResponseReturnValue]: """This method is called whenever an exception occurs that should be handled. A special case is :class:`~werkzeug .exceptions.HTTPException` which is forwarded to the @@ -1430,7 +1484,7 @@ class Flask(Scaffold): raise e self.log_exception(exc_info) - server_error: t.Union[InternalServerError, ResponseReturnValue] + server_error: t.Union[InternalServerError, ft.ResponseReturnValue] server_error = InternalServerError(original_exception=e) handler = self._find_error_handler(server_error) @@ -1484,7 +1538,7 @@ class Flask(Scaffold): raise FormDataRoutingRedirect(request) - def dispatch_request(self) -> ResponseReturnValue: + def dispatch_request(self) -> ft.ResponseReturnValue: """Does the request dispatching. Matches the URL and returns the return value of the view or error handler. This does not have to be a response object. In order to convert the return value to a @@ -1515,7 +1569,17 @@ class Flask(Scaffold): .. versionadded:: 0.7 """ - self.try_trigger_before_first_request_functions() + # Run before_first_request functions if this is the thread's first request. + # Inlined to avoid a method call on subsequent requests. + # This is deprecated, will be removed in Flask 2.3. + if not self._got_first_request: + with self._before_request_lock: + if not self._got_first_request: + for func in self.before_first_request_funcs: + self.ensure_sync(func)() + + self._got_first_request = True + try: request_started.send(self) rv = self.preprocess_request() @@ -1527,7 +1591,7 @@ class Flask(Scaffold): def finalize_request( self, - rv: t.Union[ResponseReturnValue, HTTPException], + rv: t.Union[ft.ResponseReturnValue, HTTPException], from_error_handler: bool = False, ) -> Response: """Given the return value from a view function this finalizes @@ -1554,22 +1618,6 @@ class Flask(Scaffold): ) return response - def try_trigger_before_first_request_functions(self) -> None: - """Called before each request and will ensure that it triggers - the :attr:`before_first_request_funcs` and only exactly once per - application instance (which means process usually). - - :internal: - """ - if self._got_first_request: - return - with self._before_request_lock: - if self._got_first_request: - return - for func in self.before_first_request_funcs: - self.ensure_sync(func)() - self._got_first_request = True - def make_default_options_response(self) -> Response: """This method is called to create the default ``OPTIONS`` response. This can be changed through subclassing to change the default @@ -1630,7 +1678,145 @@ class Flask(Scaffold): return asgiref_async_to_sync(func) - def make_response(self, rv: ResponseReturnValue) -> Response: + def url_for( + self, + endpoint: str, + *, + _anchor: t.Optional[str] = None, + _method: t.Optional[str] = None, + _scheme: t.Optional[str] = None, + _external: t.Optional[bool] = None, + **values: t.Any, + ) -> str: + """Generate a URL to the given endpoint with the given values. + + This is called by :func:`flask.url_for`, and can be called + directly as well. + + An *endpoint* is the name of a URL rule, usually added with + :meth:`@app.route() `, and usually the same name as the + view function. A route defined in a :class:`~flask.Blueprint` + will prepend the blueprint's name separated by a ``.`` to the + endpoint. + + In some cases, such as email messages, you want URLs to include + the scheme and domain, like ``https://example.com/hello``. When + not in an active request, URLs will be external by default, but + this requires setting :data:`SERVER_NAME` so Flask knows what + domain to use. :data:`APPLICATION_ROOT` and + :data:`PREFERRED_URL_SCHEME` should also be configured as + needed. This config is only used when not in an active request. + + Functions can be decorated with :meth:`url_defaults` to modify + keyword arguments before the URL is built. + + If building fails for some reason, such as an unknown endpoint + or incorrect values, the app's :meth:`handle_url_build_error` + method is called. If that returns a string, that is returned, + otherwise a :exc:`~werkzeug.routing.BuildError` is raised. + + :param endpoint: The endpoint name associated with the URL to + generate. If this starts with a ``.``, the current blueprint + name (if any) will be used. + :param _anchor: If given, append this as ``#anchor`` to the URL. + :param _method: If given, generate the URL associated with this + method for the endpoint. + :param _scheme: If given, the URL will have this scheme if it + is external. + :param _external: If given, prefer the URL to be internal + (False) or require it to be external (True). External URLs + include the scheme and domain. When not in an active + request, URLs are external by default. + :param values: Values to use for the variable parts of the URL + rule. Unknown keys are appended as query string arguments, + like ``?a=b&c=d``. + + .. versionadded:: 2.2 + Moved from ``flask.url_for``, which calls this method. + """ + req_ctx = _request_ctx_stack.top + + if req_ctx is not None: + url_adapter = req_ctx.url_adapter + blueprint_name = req_ctx.request.blueprint + + # If the endpoint starts with "." and the request matches a + # blueprint, the endpoint is relative to the blueprint. + if endpoint[:1] == ".": + if blueprint_name is not None: + endpoint = f"{blueprint_name}{endpoint}" + else: + endpoint = endpoint[1:] + + # When in a request, generate a URL without scheme and + # domain by default, unless a scheme is given. + if _external is None: + _external = _scheme is not None + else: + app_ctx = _app_ctx_stack.top + + # If called by helpers.url_for, an app context is active, + # use its url_adapter. Otherwise, app.url_for was called + # directly, build an adapter. + if app_ctx is not None: + url_adapter = app_ctx.url_adapter + else: + url_adapter = self.create_url_adapter(None) + + if url_adapter is None: + raise RuntimeError( + "Unable to build URLs outside an active request" + " without 'SERVER_NAME' configured. Also configure" + " 'APPLICATION_ROOT' and 'PREFERRED_URL_SCHEME' as" + " needed." + ) + + # When outside a request, generate a URL with scheme and + # domain by default. + if _external is None: + _external = True + + # It is an error to set _scheme when _external=False, in order + # to avoid accidental insecure URLs. + if _scheme is not None and not _external: + raise ValueError("When specifying '_scheme', '_external' must be True.") + + self.inject_url_defaults(endpoint, values) + + try: + rv = url_adapter.build( + endpoint, + values, + method=_method, + url_scheme=_scheme, + force_external=_external, + ) + except BuildError as error: + values.update( + _anchor=_anchor, _method=_method, _scheme=_scheme, _external=_external + ) + return self.handle_url_build_error(error, endpoint, values) + + if _anchor is not None: + rv = f"{rv}#{url_quote(_anchor)}" + + return rv + + def redirect(self, location: str, code: int = 302) -> BaseResponse: + """Create a redirect response object. + + This is called by :func:`flask.redirect`, and can be called + directly as well. + + :param location: The URL to redirect to. + :param code: The status code for the redirect. + + .. versionadded:: 2.2 + Moved from ``flask.redirect``, which calls this method. + """ + return _wz_redirect(location, code=code, Response=self.response_class) + + def make_response(self, rv: ft.ResponseReturnValue) -> Response: """Convert the return value from a view function to an instance of :attr:`response_class`. @@ -1687,7 +1873,7 @@ class Flask(Scaffold): if isinstance(rv[1], (Headers, dict, tuple, list)): rv, headers = rv else: - rv, status = rv # type: ignore[misc] + rv, status = rv # type: ignore[assignment,misc] # other sized tuples are not allowed else: raise TypeError( @@ -1722,7 +1908,9 @@ class Flask(Scaffold): # evaluate a WSGI callable, or coerce a different response # class to the correct type try: - rv = self.response_class.force_type(rv, request.environ) # type: ignore # noqa: B950 + rv = self.response_class.force_type( + rv, request.environ # type: ignore[arg-type] + ) except TypeError as e: raise TypeError( f"{e}\nThe view function did not return a valid" @@ -1816,10 +2004,21 @@ class Flask(Scaffold): func(endpoint, values) def handle_url_build_error( - self, error: Exception, endpoint: str, values: dict + self, error: BuildError, endpoint: str, values: t.Dict[str, t.Any] ) -> str: - """Handle :class:`~werkzeug.routing.BuildError` on - :meth:`url_for`. + """Called by :meth:`.url_for` if a + :exc:`~werkzeug.routing.BuildError` was raised. If this returns + a value, it will be returned by ``url_for``, otherwise the error + will be re-raised. + + Each function in :attr:`url_build_error_handlers` is called with + ``error``, ``endpoint`` and ``values``. If a function returns + ``None`` or raises a ``BuildError``, it is skipped. Otherwise, + its return value is returned by ``url_for``. + + :param error: The active ``BuildError`` being handled. + :param endpoint: The endpoint being built. + :param values: The keyword arguments passed to ``url_for``. """ for handler in self.url_build_error_handlers: try: @@ -1838,7 +2037,7 @@ class Flask(Scaffold): raise error - def preprocess_request(self) -> t.Optional[ResponseReturnValue]: + def preprocess_request(self) -> t.Optional[ft.ResponseReturnValue]: """Called before the request is dispatched. Calls :attr:`url_value_preprocessors` registered with the app and the current blueprint (if any). Then calls :attr:`before_request_funcs` diff --git a/src/flask/blueprints.py b/src/flask/blueprints.py index 5d3b4e22..76b36067 100644 --- a/src/flask/blueprints.py +++ b/src/flask/blueprints.py @@ -3,23 +3,14 @@ import typing as t from collections import defaultdict from functools import update_wrapper +from . import typing as ft from .scaffold import _endpoint_from_view_func from .scaffold import _sentinel from .scaffold import Scaffold -from .typing import AfterRequestCallable -from .typing import BeforeFirstRequestCallable -from .typing import BeforeRequestCallable -from .typing import TeardownCallable -from .typing import TemplateContextProcessorCallable -from .typing import TemplateFilterCallable -from .typing import TemplateGlobalCallable -from .typing import TemplateTestCallable -from .typing import URLDefaultCallable -from .typing import URLValuePreprocessorCallable +from .scaffold import setupmethod -if t.TYPE_CHECKING: +if t.TYPE_CHECKING: # pragma: no cover from .app import Flask - from .typing import ErrorHandlerCallable DeferredSetupFunction = t.Callable[["BlueprintSetupState"], t.Callable] @@ -162,7 +153,6 @@ class Blueprint(Scaffold): .. versionadded:: 0.7 """ - warn_on_modifications = False _got_registered_once = False #: Blueprint local JSON encoder class to use. Set to ``None`` to use @@ -208,27 +198,33 @@ class Blueprint(Scaffold): self.cli_group = cli_group self._blueprints: t.List[t.Tuple["Blueprint", dict]] = [] - def _is_setup_finished(self) -> bool: - return self.warn_on_modifications and self._got_registered_once + def _check_setup_finished(self, f_name: str) -> None: + if self._got_registered_once: + import warnings + warnings.warn( + f"The setup method '{f_name}' can no longer be called on" + f" the blueprint '{self.name}'. It has already been" + " registered at least once, any changes will not be" + " applied consistently.\n" + "Make sure all imports, decorators, functions, etc." + " needed to set up the blueprint are done before" + " registering it.\n" + "This warning will become an exception in Flask 2.3.", + UserWarning, + stacklevel=3, + ) + + @setupmethod def record(self, func: t.Callable) -> None: """Registers a function that is called when the blueprint is registered on the application. This function is called with the state as argument as returned by the :meth:`make_setup_state` method. """ - if self._got_registered_once and self.warn_on_modifications: - from warnings import warn - - warn( - Warning( - "The blueprint was already registered once but is" - " getting modified now. These changes will not show" - " up." - ) - ) self.deferred_functions.append(func) + @setupmethod def record_once(self, func: t.Callable) -> None: """Works like :meth:`record` but wraps the function in another function that will ensure the function is only called once. If the @@ -251,6 +247,7 @@ class Blueprint(Scaffold): """ return BlueprintSetupState(self, app, options, first_registration) + @setupmethod def register_blueprint(self, blueprint: "Blueprint", **options: t.Any) -> None: """Register a :class:`~flask.Blueprint` on this blueprint. Keyword arguments passed to this method will override the defaults set @@ -390,11 +387,12 @@ class Blueprint(Scaffold): bp_options["name_prefix"] = name blueprint.register(app, bp_options) + @setupmethod def add_url_rule( self, rule: str, endpoint: t.Optional[str] = None, - view_func: t.Optional[t.Callable] = None, + view_func: t.Optional[ft.ViewCallable] = None, provide_automatic_options: t.Optional[bool] = None, **options: t.Any, ) -> None: @@ -417,9 +415,10 @@ class Blueprint(Scaffold): ) ) + @setupmethod def app_template_filter( self, name: t.Optional[str] = None - ) -> t.Callable[[TemplateFilterCallable], TemplateFilterCallable]: + ) -> t.Callable[[ft.TemplateFilterCallable], ft.TemplateFilterCallable]: """Register a custom template filter, available application wide. Like :meth:`Flask.template_filter` but for a blueprint. @@ -427,14 +426,15 @@ class Blueprint(Scaffold): function name will be used. """ - def decorator(f: TemplateFilterCallable) -> TemplateFilterCallable: + def decorator(f: ft.TemplateFilterCallable) -> ft.TemplateFilterCallable: self.add_app_template_filter(f, name=name) return f return decorator + @setupmethod def add_app_template_filter( - self, f: TemplateFilterCallable, name: t.Optional[str] = None + self, f: ft.TemplateFilterCallable, name: t.Optional[str] = None ) -> None: """Register a custom template filter, available application wide. Like :meth:`Flask.add_template_filter` but for a blueprint. Works exactly @@ -449,9 +449,10 @@ class Blueprint(Scaffold): self.record_once(register_template) + @setupmethod def app_template_test( self, name: t.Optional[str] = None - ) -> t.Callable[[TemplateTestCallable], TemplateTestCallable]: + ) -> t.Callable[[ft.TemplateTestCallable], ft.TemplateTestCallable]: """Register a custom template test, available application wide. Like :meth:`Flask.template_test` but for a blueprint. @@ -461,14 +462,15 @@ class Blueprint(Scaffold): function name will be used. """ - def decorator(f: TemplateTestCallable) -> TemplateTestCallable: + def decorator(f: ft.TemplateTestCallable) -> ft.TemplateTestCallable: self.add_app_template_test(f, name=name) return f return decorator + @setupmethod def add_app_template_test( - self, f: TemplateTestCallable, name: t.Optional[str] = None + self, f: ft.TemplateTestCallable, name: t.Optional[str] = None ) -> None: """Register a custom template test, available application wide. Like :meth:`Flask.add_template_test` but for a blueprint. Works exactly @@ -485,9 +487,10 @@ class Blueprint(Scaffold): self.record_once(register_template) + @setupmethod def app_template_global( self, name: t.Optional[str] = None - ) -> t.Callable[[TemplateGlobalCallable], TemplateGlobalCallable]: + ) -> t.Callable[[ft.TemplateGlobalCallable], ft.TemplateGlobalCallable]: """Register a custom template global, available application wide. Like :meth:`Flask.template_global` but for a blueprint. @@ -497,14 +500,15 @@ class Blueprint(Scaffold): function name will be used. """ - def decorator(f: TemplateGlobalCallable) -> TemplateGlobalCallable: + def decorator(f: ft.TemplateGlobalCallable) -> ft.TemplateGlobalCallable: self.add_app_template_global(f, name=name) return f return decorator + @setupmethod def add_app_template_global( - self, f: TemplateGlobalCallable, name: t.Optional[str] = None + self, f: ft.TemplateGlobalCallable, name: t.Optional[str] = None ) -> None: """Register a custom template global, available application wide. Like :meth:`Flask.add_template_global` but for a blueprint. Works exactly @@ -521,7 +525,10 @@ class Blueprint(Scaffold): self.record_once(register_template) - def before_app_request(self, f: BeforeRequestCallable) -> BeforeRequestCallable: + @setupmethod + def before_app_request( + self, f: ft.BeforeRequestCallable + ) -> ft.BeforeRequestCallable: """Like :meth:`Flask.before_request`. Such a function is executed before each request, even if outside of a blueprint. """ @@ -530,16 +537,30 @@ class Blueprint(Scaffold): ) return f + @setupmethod def before_app_first_request( - self, f: BeforeFirstRequestCallable - ) -> BeforeFirstRequestCallable: + self, f: ft.BeforeFirstRequestCallable + ) -> ft.BeforeFirstRequestCallable: """Like :meth:`Flask.before_first_request`. Such a function is executed before the first request to the application. + + .. deprecated:: 2.2 + Will be removed in Flask 2.3. Run setup code when creating + the application instead. """ + import warnings + + warnings.warn( + "'before_app_first_request' is deprecated and will be" + " removed in Flask 2.3. Use 'record_once' instead to run" + " setup code when registering the blueprint.", + DeprecationWarning, + stacklevel=2, + ) self.record_once(lambda s: s.app.before_first_request_funcs.append(f)) return f - def after_app_request(self, f: AfterRequestCallable) -> AfterRequestCallable: + def after_app_request(self, f: ft.AfterRequestCallable) -> ft.AfterRequestCallable: """Like :meth:`Flask.after_request` but for a blueprint. Such a function is executed after each request, even if outside of the blueprint. """ @@ -548,7 +569,8 @@ class Blueprint(Scaffold): ) return f - def teardown_app_request(self, f: TeardownCallable) -> TeardownCallable: + @setupmethod + def teardown_app_request(self, f: ft.TeardownCallable) -> ft.TeardownCallable: """Like :meth:`Flask.teardown_request` but for a blueprint. Such a function is executed when tearing down each request, even if outside of the blueprint. @@ -558,9 +580,10 @@ class Blueprint(Scaffold): ) return f + @setupmethod def app_context_processor( - self, f: TemplateContextProcessorCallable - ) -> TemplateContextProcessorCallable: + self, f: ft.TemplateContextProcessorCallable + ) -> ft.TemplateContextProcessorCallable: """Like :meth:`Flask.context_processor` but for a blueprint. Such a function is executed each request, even if outside of the blueprint. """ @@ -569,27 +592,32 @@ class Blueprint(Scaffold): ) return f - def app_errorhandler(self, code: t.Union[t.Type[Exception], int]) -> t.Callable: + @setupmethod + def app_errorhandler( + self, code: t.Union[t.Type[Exception], int] + ) -> t.Callable[[ft.ErrorHandlerDecorator], ft.ErrorHandlerDecorator]: """Like :meth:`Flask.errorhandler` but for a blueprint. This handler is used for all requests, even if outside of the blueprint. """ - def decorator(f: "ErrorHandlerCallable") -> "ErrorHandlerCallable": + def decorator(f: ft.ErrorHandlerDecorator) -> ft.ErrorHandlerDecorator: self.record_once(lambda s: s.app.errorhandler(code)(f)) return f return decorator + @setupmethod def app_url_value_preprocessor( - self, f: URLValuePreprocessorCallable - ) -> URLValuePreprocessorCallable: + self, f: ft.URLValuePreprocessorCallable + ) -> ft.URLValuePreprocessorCallable: """Same as :meth:`url_value_preprocessor` but application wide.""" self.record_once( lambda s: s.app.url_value_preprocessors.setdefault(None, []).append(f) ) return f - def app_url_defaults(self, f: URLDefaultCallable) -> URLDefaultCallable: + @setupmethod + def app_url_defaults(self, f: ft.URLDefaultCallable) -> ft.URLDefaultCallable: """Same as :meth:`url_defaults` but application wide.""" self.record_once( lambda s: s.app.url_default_functions.setdefault(None, []).append(f) diff --git a/src/flask/cli.py b/src/flask/cli.py index 36c4f1b6..77c1e25a 100644 --- a/src/flask/cli.py +++ b/src/flask/cli.py @@ -18,26 +18,6 @@ from .helpers import get_debug_flag from .helpers import get_env from .helpers import get_load_dotenv -try: - import dotenv -except ImportError: - dotenv = None - -try: - import ssl -except ImportError: - ssl = None # type: ignore - -if sys.version_info >= (3, 10): - from importlib import metadata -else: - # Use a backport on Python < 3.10. - # - # 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 - class NoAppException(click.UsageError): """Raised if an application cannot be found or loaded.""" @@ -513,6 +493,14 @@ class FlaskGroup(AppGroup): if self._loaded_plugin_commands: return + if sys.version_info >= (3, 10): + from importlib import metadata + else: + # Use a backport on Python < 3.10. 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 + for ep in metadata.entry_points(group="flask.commands"): self.add_command(ep.load(), ep.name) @@ -608,7 +596,9 @@ def load_dotenv(path=None): .. versionadded:: 1.0 """ - if dotenv is None: + try: + import dotenv + except ImportError: if path or os.path.isfile(".env") or os.path.isfile(".flaskenv"): click.secho( " * Tip: There are .env or .flaskenv files present." @@ -684,12 +674,14 @@ class CertParamType(click.ParamType): self.path_type = click.Path(exists=True, dir_okay=False, resolve_path=True) def convert(self, value, param, ctx): - if ssl is None: + try: + import ssl + except ImportError: raise click.BadParameter( 'Using "--cert" requires Python to be compiled with SSL support.', ctx, param, - ) + ) from None try: return self.path_type(value, param, ctx) @@ -722,7 +714,13 @@ def _validate_key(ctx, param, value): """ cert = ctx.params.get("cert") is_adhoc = cert == "adhoc" - is_context = ssl and isinstance(cert, ssl.SSLContext) + + try: + import ssl + except ImportError: + is_context = False + else: + is_context = isinstance(cert, ssl.SSLContext) if value is not None: if is_adhoc: diff --git a/src/flask/ctx.py b/src/flask/ctx.py index 3ed8fd3a..2b2ebb75 100644 --- a/src/flask/ctx.py +++ b/src/flask/ctx.py @@ -5,13 +5,13 @@ from types import TracebackType from werkzeug.exceptions import HTTPException +from . import typing as ft from .globals import _app_ctx_stack from .globals import _request_ctx_stack from .signals import appcontext_popped from .signals import appcontext_pushed -from .typing import AfterRequestCallable -if t.TYPE_CHECKING: +if t.TYPE_CHECKING: # pragma: no cover from .app import Flask from .sessions import SessionMixin from .wrappers import Request @@ -109,7 +109,7 @@ class _AppCtxGlobals: return object.__repr__(self) -def after_this_request(f: AfterRequestCallable) -> AfterRequestCallable: +def after_this_request(f: ft.AfterRequestCallable) -> ft.AfterRequestCallable: """Executes a function after this request. This is useful to modify response objects. The function is passed the response object and has to return the same or a new one. @@ -341,7 +341,7 @@ class RequestContext: # Functions that should be executed after the request on the response # object. These will be called before the regular "after_request" # functions. - self._after_request_functions: t.List[AfterRequestCallable] = [] + self._after_request_functions: t.List[ft.AfterRequestCallable] = [] @property def g(self) -> _AppCtxGlobals: diff --git a/src/flask/globals.py b/src/flask/globals.py index 6d91c75e..7824204f 100644 --- a/src/flask/globals.py +++ b/src/flask/globals.py @@ -4,7 +4,7 @@ from functools import partial from werkzeug.local import LocalProxy from werkzeug.local import LocalStack -if t.TYPE_CHECKING: +if t.TYPE_CHECKING: # pragma: no cover from .app import Flask from .ctx import _AppCtxGlobals from .sessions import SessionMixin diff --git a/src/flask/helpers.py b/src/flask/helpers.py index fe47500e..6928b203 100644 --- a/src/flask/helpers.py +++ b/src/flask/helpers.py @@ -10,18 +10,19 @@ from functools import update_wrapper from threading import RLock import werkzeug.utils -from werkzeug.routing import BuildError -from werkzeug.urls import url_quote +from werkzeug.exceptions import abort as _wz_abort +from werkzeug.utils import redirect as _wz_redirect -from .globals import _app_ctx_stack from .globals import _request_ctx_stack from .globals import current_app from .globals import request from .globals import session from .signals import message_flashed -if t.TYPE_CHECKING: +if t.TYPE_CHECKING: # pragma: no cover + from werkzeug.wrappers import Response as BaseResponse from .wrappers import Response + import typing_extensions as te def get_env() -> str: @@ -189,155 +190,107 @@ def make_response(*args: t.Any) -> "Response": return current_app.make_response(args) # type: ignore -def url_for(endpoint: str, **values: t.Any) -> str: - """Generates a URL to the given endpoint with the method provided. +def url_for( + endpoint: str, + *, + _anchor: t.Optional[str] = None, + _method: t.Optional[str] = None, + _scheme: t.Optional[str] = None, + _external: t.Optional[bool] = None, + **values: t.Any, +) -> str: + """Generate a URL to the given endpoint with the given values. - Variable arguments that are unknown to the target endpoint are appended - to the generated URL as query arguments. If the value of a query argument - is ``None``, the whole pair is skipped. In case blueprints are active - you can shortcut references to the same blueprint by prefixing the - local endpoint with a dot (``.``). + This requires an active request or application context, and calls + :meth:`current_app.url_for() `. See that method + for full documentation. - This will reference the index function local to the current blueprint:: + :param endpoint: The endpoint name associated with the URL to + generate. If this starts with a ``.``, the current blueprint + name (if any) will be used. + :param _anchor: If given, append this as ``#anchor`` to the URL. + :param _method: If given, generate the URL associated with this + method for the endpoint. + :param _scheme: If given, the URL will have this scheme if it is + external. + :param _external: If given, prefer the URL to be internal (False) or + require it to be external (True). External URLs include the + scheme and domain. When not in an active request, URLs are + external by default. + :param values: Values to use for the variable parts of the URL rule. + Unknown keys are appended as query string arguments, like + ``?a=b&c=d``. - url_for('.index') + .. versionchanged:: 2.2 + Calls ``current_app.url_for``, allowing an app to override the + behavior. - See :ref:`url-building`. + .. versionchanged:: 0.10 + The ``_scheme`` parameter was added. - Configuration values ``APPLICATION_ROOT`` and ``SERVER_NAME`` are only used when - generating URLs outside of a request context. + .. versionchanged:: 0.9 + The ``_anchor`` and ``_method`` parameters were added. - To integrate applications, :class:`Flask` has a hook to intercept URL build - errors through :attr:`Flask.url_build_error_handlers`. The `url_for` - function results in a :exc:`~werkzeug.routing.BuildError` when the current - app does not have a URL for the given endpoint and values. When it does, the - :data:`~flask.current_app` calls its :attr:`~Flask.url_build_error_handlers` if - it is not ``None``, which can return a string to use as the result of - `url_for` (instead of `url_for`'s default to raise the - :exc:`~werkzeug.routing.BuildError` exception) or re-raise the exception. - An example:: - - def external_url_handler(error, endpoint, values): - "Looks up an external URL when `url_for` cannot build a URL." - # This is an example of hooking the build_error_handler. - # Here, lookup_url is some utility function you've built - # which looks up the endpoint in some external URL registry. - url = lookup_url(endpoint, **values) - if url is None: - # External lookup did not have a URL. - # Re-raise the BuildError, in context of original traceback. - exc_type, exc_value, tb = sys.exc_info() - if exc_value is error: - raise exc_type(exc_value).with_traceback(tb) - else: - raise error - # url_for will use this result, instead of raising BuildError. - return url - - app.url_build_error_handlers.append(external_url_handler) - - Here, `error` is the instance of :exc:`~werkzeug.routing.BuildError`, and - `endpoint` and `values` are the arguments passed into `url_for`. Note - that this is for building URLs outside the current application, and not for - handling 404 NotFound errors. - - .. versionadded:: 0.10 - The `_scheme` parameter was added. - - .. versionadded:: 0.9 - The `_anchor` and `_method` parameters were added. - - .. versionadded:: 0.9 - Calls :meth:`Flask.handle_build_error` on - :exc:`~werkzeug.routing.BuildError`. - - :param endpoint: the endpoint of the URL (name of the function) - :param values: the variable arguments of the URL rule - :param _external: if set to ``True``, an absolute URL is generated. Server - address can be changed via ``SERVER_NAME`` configuration variable which - falls back to the `Host` header, then to the IP and port of the request. - :param _scheme: a string specifying the desired URL scheme. The `_external` - parameter must be set to ``True`` or a :exc:`ValueError` is raised. The default - behavior uses the same scheme as the current request, or - :data:`PREFERRED_URL_SCHEME` if no request context is available. - This also can be set to an empty string to build protocol-relative - URLs. - :param _anchor: if provided this is added as anchor to the URL. - :param _method: if provided this explicitly specifies an HTTP method. + .. versionchanged:: 0.9 + Calls ``app.handle_url_build_error`` on build errors. """ - appctx = _app_ctx_stack.top - reqctx = _request_ctx_stack.top + return current_app.url_for( + endpoint, + _anchor=_anchor, + _method=_method, + _scheme=_scheme, + _external=_external, + **values, + ) - if appctx is None: - raise RuntimeError( - "Attempted to generate a URL without the application context being" - " pushed. This has to be executed when application context is" - " available." - ) - # If request specific information is available we have some extra - # features that support "relative" URLs. - if reqctx is not None: - url_adapter = reqctx.url_adapter - blueprint_name = request.blueprint +def redirect( + location: str, code: int = 302, Response: t.Optional[t.Type["BaseResponse"]] = None +) -> "BaseResponse": + """Create a redirect response object. - if endpoint[:1] == ".": - if blueprint_name is not None: - endpoint = f"{blueprint_name}{endpoint}" - else: - endpoint = endpoint[1:] + If :data:`~flask.current_app` is available, it will use its + :meth:`~flask.Flask.redirect` method, otherwise it will use + :func:`werkzeug.utils.redirect`. - external = values.pop("_external", False) + :param location: The URL to redirect to. + :param code: The status code for the redirect. + :param Response: The response class to use. Not used when + ``current_app`` is active, which uses ``app.response_class``. - # Otherwise go with the url adapter from the appctx and make - # the URLs external by default. - else: - url_adapter = appctx.url_adapter + .. versionadded:: 2.2 + Calls ``current_app.redirect`` if available instead of always + using Werkzeug's default ``redirect``. + """ + if current_app: + return current_app.redirect(location, code=code) - if url_adapter is None: - raise RuntimeError( - "Application was not able to create a URL adapter for request" - " independent URL generation. You might be able to fix this by" - " setting the SERVER_NAME config variable." - ) + return _wz_redirect(location, code=code, Response=Response) - external = values.pop("_external", True) - anchor = values.pop("_anchor", None) - method = values.pop("_method", None) - scheme = values.pop("_scheme", None) - appctx.app.inject_url_defaults(endpoint, values) +def abort( # type: ignore[misc] + code: t.Union[int, "BaseResponse"], *args: t.Any, **kwargs: t.Any +) -> "te.NoReturn": + """Raise an :exc:`~werkzeug.exceptions.HTTPException` for the given + status code. - # This is not the best way to deal with this but currently the - # underlying Werkzeug router does not support overriding the scheme on - # a per build call basis. - old_scheme = None - if scheme is not None: - if not external: - raise ValueError("When specifying _scheme, _external must be True") - old_scheme = url_adapter.url_scheme - url_adapter.url_scheme = scheme + If :data:`~flask.current_app` is available, it will call its + :attr:`~flask.Flask.aborter` object, otherwise it will use + :func:`werkzeug.exceptions.abort`. - try: - try: - rv = url_adapter.build( - endpoint, values, method=method, force_external=external - ) - finally: - if old_scheme is not None: - url_adapter.url_scheme = old_scheme - except BuildError as error: - # We need to inject the values again so that the app callback can - # deal with that sort of stuff. - values["_external"] = external - values["_anchor"] = anchor - values["_method"] = method - values["_scheme"] = scheme - return appctx.app.handle_url_build_error(error, endpoint, values) + :param code: The status code for the exception, which must be + registered in ``app.aborter``. + :param args: Passed to the exception. + :param kwargs: Passed to the exception. - if anchor is not None: - rv += f"#{url_quote(anchor)}" - return rv + .. versionadded:: 2.2 + Calls ``current_app.aborter`` if available instead of always + using Werkzeug's default ``abort``. + """ + if current_app: + current_app.aborter(code, *args, **kwargs) + + _wz_abort(code, *args, **kwargs) def get_template_attribute(template_name: str, attribute: str) -> t.Any: diff --git a/src/flask/json/__init__.py b/src/flask/json/__init__.py index edc9793d..574e9e74 100644 --- a/src/flask/json/__init__.py +++ b/src/flask/json/__init__.py @@ -11,7 +11,7 @@ from werkzeug.http import http_date from ..globals import current_app from ..globals import request -if t.TYPE_CHECKING: +if t.TYPE_CHECKING: # pragma: no cover from ..app import Flask from ..wrappers import Response diff --git a/src/flask/logging.py b/src/flask/logging.py index 48a5b7ff..8981b820 100644 --- a/src/flask/logging.py +++ b/src/flask/logging.py @@ -6,7 +6,7 @@ from werkzeug.local import LocalProxy from .globals import request -if t.TYPE_CHECKING: +if t.TYPE_CHECKING: # pragma: no cover from .app import Flask diff --git a/src/flask/scaffold.py b/src/flask/scaffold.py index acf8708b..54d42d1d 100644 --- a/src/flask/scaffold.py +++ b/src/flask/scaffold.py @@ -1,5 +1,6 @@ import importlib.util import os +import pathlib import pkgutil import sys import typing as t @@ -12,23 +13,16 @@ from jinja2 import FileSystemLoader from werkzeug.exceptions import default_exceptions from werkzeug.exceptions import HTTPException +from . import typing as ft from .cli import AppGroup from .globals import current_app from .helpers import get_root_path from .helpers import locked_cached_property from .helpers import send_from_directory from .templating import _default_template_ctx_processor -from .typing import AfterRequestCallable -from .typing import AppOrBlueprintKey -from .typing import BeforeRequestCallable -from .typing import TeardownCallable -from .typing import TemplateContextProcessorCallable -from .typing import URLDefaultCallable -from .typing import URLValuePreprocessorCallable -if t.TYPE_CHECKING: +if t.TYPE_CHECKING: # pragma: no cover from .wrappers import Response - from .typing import ErrorHandlerCallable # a singleton sentinel value for parameter defaults _sentinel = object() @@ -37,22 +31,10 @@ F = t.TypeVar("F", bound=t.Callable[..., t.Any]) def setupmethod(f: F) -> F: - """Wraps a method so that it performs a check in debug mode if the - first request was already handled. - """ + f_name = f.__name__ def wrapper_func(self, *args: t.Any, **kwargs: t.Any) -> t.Any: - if self._is_setup_finished(): - raise AssertionError( - "A setup function was called after the first request " - "was handled. This usually indicates a bug in the" - " application where a module was not imported and" - " decorators or other functionality was called too" - " late.\nTo fix this make sure to import all your view" - " modules, database models, and everything related at a" - " central place before the application starts serving" - " requests." - ) + self._check_setup_finished(f_name) return f(self, *args, **kwargs) return t.cast(F, update_wrapper(wrapper_func, f)) @@ -130,7 +112,7 @@ class Scaffold: self.view_functions: t.Dict[str, t.Callable] = {} #: A data structure of registered error handlers, in the format - #: ``{scope: {code: {class: handler}}}```. The ``scope`` key is + #: ``{scope: {code: {class: handler}}}``. The ``scope`` key is #: the name of a blueprint the handlers are active for, or #: ``None`` for all requests. The ``code`` key is the HTTP #: status code for ``HTTPException``, or ``None`` for @@ -143,8 +125,8 @@ class Scaffold: #: This data structure is internal. It should not be modified #: directly and its format may change at any time. self.error_handler_spec: t.Dict[ - AppOrBlueprintKey, - t.Dict[t.Optional[int], t.Dict[t.Type[Exception], "ErrorHandlerCallable"]], + ft.AppOrBlueprintKey, + t.Dict[t.Optional[int], t.Dict[t.Type[Exception], ft.ErrorHandlerCallable]], ] = defaultdict(lambda: defaultdict(dict)) #: A data structure of functions to call at the beginning of @@ -158,7 +140,7 @@ class Scaffold: #: This data structure is internal. It should not be modified #: directly and its format may change at any time. self.before_request_funcs: t.Dict[ - AppOrBlueprintKey, t.List[BeforeRequestCallable] + ft.AppOrBlueprintKey, t.List[ft.BeforeRequestCallable] ] = defaultdict(list) #: A data structure of functions to call at the end of each @@ -172,7 +154,7 @@ class Scaffold: #: This data structure is internal. It should not be modified #: directly and its format may change at any time. self.after_request_funcs: t.Dict[ - AppOrBlueprintKey, t.List[AfterRequestCallable] + ft.AppOrBlueprintKey, t.List[ft.AfterRequestCallable] ] = defaultdict(list) #: A data structure of functions to call at the end of each @@ -187,7 +169,7 @@ class Scaffold: #: This data structure is internal. It should not be modified #: directly and its format may change at any time. self.teardown_request_funcs: t.Dict[ - AppOrBlueprintKey, t.List[TeardownCallable] + ft.AppOrBlueprintKey, t.List[ft.TeardownCallable] ] = defaultdict(list) #: A data structure of functions to call to pass extra context @@ -202,7 +184,7 @@ class Scaffold: #: This data structure is internal. It should not be modified #: directly and its format may change at any time. self.template_context_processors: t.Dict[ - AppOrBlueprintKey, t.List[TemplateContextProcessorCallable] + ft.AppOrBlueprintKey, t.List[ft.TemplateContextProcessorCallable] ] = defaultdict(list, {None: [_default_template_ctx_processor]}) #: A data structure of functions to call to modify the keyword @@ -217,8 +199,8 @@ class Scaffold: #: This data structure is internal. It should not be modified #: directly and its format may change at any time. self.url_value_preprocessors: t.Dict[ - AppOrBlueprintKey, - t.List[URLValuePreprocessorCallable], + ft.AppOrBlueprintKey, + t.List[ft.URLValuePreprocessorCallable], ] = defaultdict(list) #: A data structure of functions to call to modify the keyword @@ -233,13 +215,13 @@ class Scaffold: #: This data structure is internal. It should not be modified #: directly and its format may change at any time. self.url_default_functions: t.Dict[ - AppOrBlueprintKey, t.List[URLDefaultCallable] + ft.AppOrBlueprintKey, t.List[ft.URLDefaultCallable] ] = defaultdict(list) def __repr__(self) -> str: return f"<{type(self).__name__} {self.name!r}>" - def _is_setup_finished(self) -> bool: + def _check_setup_finished(self, f_name: str) -> None: raise NotImplementedError @property @@ -370,48 +352,66 @@ class Scaffold: method: str, rule: str, options: dict, - ) -> t.Callable[[F], F]: + ) -> t.Callable[[ft.RouteDecorator], ft.RouteDecorator]: if "methods" in options: raise TypeError("Use the 'route' decorator to use the 'methods' argument.") return self.route(rule, methods=[method], **options) - def get(self, rule: str, **options: t.Any) -> t.Callable[[F], F]: + @setupmethod + def get( + self, rule: str, **options: t.Any + ) -> t.Callable[[ft.RouteDecorator], ft.RouteDecorator]: """Shortcut for :meth:`route` with ``methods=["GET"]``. .. versionadded:: 2.0 """ return self._method_route("GET", rule, options) - def post(self, rule: str, **options: t.Any) -> t.Callable[[F], F]: + @setupmethod + def post( + self, rule: str, **options: t.Any + ) -> t.Callable[[ft.RouteDecorator], ft.RouteDecorator]: """Shortcut for :meth:`route` with ``methods=["POST"]``. .. versionadded:: 2.0 """ return self._method_route("POST", rule, options) - def put(self, rule: str, **options: t.Any) -> t.Callable[[F], F]: + @setupmethod + def put( + self, rule: str, **options: t.Any + ) -> t.Callable[[ft.RouteDecorator], ft.RouteDecorator]: """Shortcut for :meth:`route` with ``methods=["PUT"]``. .. versionadded:: 2.0 """ return self._method_route("PUT", rule, options) - def delete(self, rule: str, **options: t.Any) -> t.Callable[[F], F]: + @setupmethod + def delete( + self, rule: str, **options: t.Any + ) -> t.Callable[[ft.RouteDecorator], ft.RouteDecorator]: """Shortcut for :meth:`route` with ``methods=["DELETE"]``. .. versionadded:: 2.0 """ return self._method_route("DELETE", rule, options) - def patch(self, rule: str, **options: t.Any) -> t.Callable[[F], F]: + @setupmethod + def patch( + self, rule: str, **options: t.Any + ) -> t.Callable[[ft.RouteDecorator], ft.RouteDecorator]: """Shortcut for :meth:`route` with ``methods=["PATCH"]``. .. versionadded:: 2.0 """ return self._method_route("PATCH", rule, options) - def route(self, rule: str, **options: t.Any) -> t.Callable[[F], F]: + @setupmethod + def route( + self, rule: str, **options: t.Any + ) -> t.Callable[[ft.RouteDecorator], ft.RouteDecorator]: """Decorate a view function to register it with the given URL rule and options. Calls :meth:`add_url_rule`, which has more details about the implementation. @@ -435,7 +435,7 @@ class Scaffold: :class:`~werkzeug.routing.Rule` object. """ - def decorator(f: F) -> F: + def decorator(f: ft.RouteDecorator) -> ft.RouteDecorator: endpoint = options.pop("endpoint", None) self.add_url_rule(rule, endpoint, f, **options) return f @@ -447,7 +447,7 @@ class Scaffold: self, rule: str, endpoint: t.Optional[str] = None, - view_func: t.Optional[t.Callable] = None, + view_func: t.Optional[ft.ViewCallable] = None, provide_automatic_options: t.Optional[bool] = None, **options: t.Any, ) -> None: @@ -510,6 +510,7 @@ class Scaffold: """ raise NotImplementedError + @setupmethod def endpoint(self, endpoint: str) -> t.Callable: """Decorate a view function to register it for the given endpoint. Used if a rule is added without a ``view_func`` with @@ -534,7 +535,7 @@ class Scaffold: return decorator @setupmethod - def before_request(self, f: BeforeRequestCallable) -> BeforeRequestCallable: + def before_request(self, f: ft.BeforeRequestCallable) -> ft.BeforeRequestCallable: """Register a function to run before each request. For example, this can be used to open a database connection, or @@ -556,7 +557,7 @@ class Scaffold: return f @setupmethod - def after_request(self, f: AfterRequestCallable) -> AfterRequestCallable: + def after_request(self, f: ft.AfterRequestCallable) -> ft.AfterRequestCallable: """Register a function to run after each request to this object. The function is called with the response object, and must return @@ -572,7 +573,7 @@ class Scaffold: return f @setupmethod - def teardown_request(self, f: TeardownCallable) -> TeardownCallable: + def teardown_request(self, f: ft.TeardownCallable) -> ft.TeardownCallable: """Register a function to be run at the end of each request, regardless of whether there was an exception or not. These functions are executed when the request context is popped, even if not an @@ -612,16 +613,16 @@ class Scaffold: @setupmethod def context_processor( - self, f: TemplateContextProcessorCallable - ) -> TemplateContextProcessorCallable: + self, f: ft.TemplateContextProcessorCallable + ) -> ft.TemplateContextProcessorCallable: """Registers a template context processor function.""" self.template_context_processors[None].append(f) return f @setupmethod def url_value_preprocessor( - self, f: URLValuePreprocessorCallable - ) -> URLValuePreprocessorCallable: + self, f: ft.URLValuePreprocessorCallable + ) -> ft.URLValuePreprocessorCallable: """Register a URL value preprocessor function for all view functions in the application. These functions will be called before the :meth:`before_request` functions. @@ -638,7 +639,7 @@ class Scaffold: return f @setupmethod - def url_defaults(self, f: URLDefaultCallable) -> URLDefaultCallable: + def url_defaults(self, f: ft.URLDefaultCallable) -> ft.URLDefaultCallable: """Callback function for URL defaults for all view functions of the application. It's called with the endpoint and values and should update the values passed in place. @@ -649,7 +650,7 @@ class Scaffold: @setupmethod def errorhandler( self, code_or_exception: t.Union[t.Type[Exception], int] - ) -> t.Callable[["ErrorHandlerCallable"], "ErrorHandlerCallable"]: + ) -> t.Callable[[ft.ErrorHandlerDecorator], ft.ErrorHandlerDecorator]: """Register a function to handle errors by code or exception class. A decorator that is used to register a function given an @@ -679,7 +680,7 @@ class Scaffold: an arbitrary exception """ - def decorator(f: "ErrorHandlerCallable") -> "ErrorHandlerCallable": + def decorator(f: ft.ErrorHandlerDecorator) -> ft.ErrorHandlerDecorator: self.register_error_handler(code_or_exception, f) return f @@ -689,7 +690,7 @@ class Scaffold: def register_error_handler( self, code_or_exception: t.Union[t.Type[Exception], int], - f: "ErrorHandlerCallable", + f: ft.ErrorHandlerCallable, ) -> None: """Alternative error attach function to the :meth:`errorhandler` decorator that is more straightforward to use for non decorator @@ -697,22 +698,7 @@ class Scaffold: .. versionadded:: 0.7 """ - if isinstance(code_or_exception, HTTPException): # old broken behavior - raise ValueError( - "Tried to register a handler for an exception instance" - f" {code_or_exception!r}. Handlers can only be" - " registered for exception classes or HTTP error codes." - ) - - try: - exc_class, code = self._get_exc_class_and_code(code_or_exception) - except KeyError: - raise KeyError( - f"'{code_or_exception}' is not a recognized HTTP error" - " code. Use a subclass of HTTPException with that code" - " instead." - ) from None - + exc_class, code = self._get_exc_class_and_code(code_or_exception) self.error_handler_spec[None][code][exc_class] = f @staticmethod @@ -727,14 +713,32 @@ class Scaffold: code as an integer. """ exc_class: t.Type[Exception] + if isinstance(exc_class_or_code, int): - exc_class = default_exceptions[exc_class_or_code] + try: + exc_class = default_exceptions[exc_class_or_code] + except KeyError: + raise ValueError( + f"'{exc_class_or_code}' is not a recognized HTTP" + " error code. Use a subclass of HTTPException with" + " that code instead." + ) from None else: exc_class = exc_class_or_code - assert issubclass( - exc_class, Exception - ), "Custom exceptions must be subclasses of Exception." + if isinstance(exc_class, Exception): + raise TypeError( + f"{exc_class!r} is an instance, not a class. Handlers" + " can only be registered for Exception classes or HTTP" + " error codes." + ) + + if not issubclass(exc_class, Exception): + raise ValueError( + f"'{exc_class.__name__}' is not a subclass of Exception." + " Handlers can only be registered for Exception classes" + " or HTTP error codes." + ) if issubclass(exc_class, HTTPException): return exc_class, exc_class.code @@ -775,30 +779,55 @@ def _matching_loader_thinks_module_is_package(loader, mod_name): ) -def _find_package_path(root_mod_name): - """Find the path that contains the package or module.""" +def _path_is_relative_to(path: pathlib.PurePath, base: str) -> bool: + # Path.is_relative_to doesn't exist until Python 3.9 try: - spec = importlib.util.find_spec(root_mod_name) + path.relative_to(base) + return True + except ValueError: + return False - if spec is None: + +def _find_package_path(import_name): + """Find the path that contains the package or module.""" + root_mod_name, _, _ = import_name.partition(".") + + try: + root_spec = importlib.util.find_spec(root_mod_name) + + if root_spec is None: raise ValueError("not found") # ImportError: the machinery told us it does not exist # ValueError: # - the module name was invalid # - the module name is __main__ - # - *we* raised `ValueError` due to `spec` being `None` + # - *we* raised `ValueError` due to `root_spec` being `None` except (ImportError, ValueError): pass # handled below else: # namespace package - if spec.origin in {"namespace", None}: - return os.path.dirname(next(iter(spec.submodule_search_locations))) + if root_spec.origin in {"namespace", None}: + package_spec = importlib.util.find_spec(import_name) + if package_spec is not None and package_spec.submodule_search_locations: + # Pick the path in the namespace that contains the submodule. + package_path = pathlib.Path( + os.path.commonpath(package_spec.submodule_search_locations) + ) + search_locations = ( + location + for location in root_spec.submodule_search_locations + if _path_is_relative_to(package_path, location) + ) + else: + # Pick the first path. + search_locations = iter(root_spec.submodule_search_locations) + return os.path.dirname(next(search_locations)) # a package (with __init__.py) - elif spec.submodule_search_locations: - return os.path.dirname(os.path.dirname(spec.origin)) + elif root_spec.submodule_search_locations: + return os.path.dirname(os.path.dirname(root_spec.origin)) # just a normal module else: - return os.path.dirname(spec.origin) + return os.path.dirname(root_spec.origin) # we were unable to find the `package_path` using PEP 451 loaders loader = pkgutil.get_loader(root_mod_name) @@ -840,12 +869,11 @@ def find_package(import_name: str): for import. If the package is not installed, it's assumed that the package was imported from the current working directory. """ - root_mod_name, _, _ = import_name.partition(".") - package_path = _find_package_path(root_mod_name) + package_path = _find_package_path(import_name) py_prefix = os.path.abspath(sys.prefix) # installed to the system - if package_path.startswith(py_prefix): + if _path_is_relative_to(pathlib.PurePath(package_path), py_prefix): return py_prefix, package_path site_parent, site_folder = os.path.split(package_path) diff --git a/src/flask/sessions.py b/src/flask/sessions.py index 4e19270e..a14aecba 100644 --- a/src/flask/sessions.py +++ b/src/flask/sessions.py @@ -11,7 +11,7 @@ from werkzeug.datastructures import CallbackDict from .helpers import is_ip from .json.tag import TaggedJSONSerializer -if t.TYPE_CHECKING: +if t.TYPE_CHECKING: # pragma: no cover import typing_extensions as te from .app import Flask from .wrappers import Request, Response diff --git a/src/flask/templating.py b/src/flask/templating.py index b39adb77..36a8645c 100644 --- a/src/flask/templating.py +++ b/src/flask/templating.py @@ -10,7 +10,7 @@ from .globals import _request_ctx_stack from .signals import before_render_template from .signals import template_rendered -if t.TYPE_CHECKING: +if t.TYPE_CHECKING: # pragma: no cover from .app import Flask from .scaffold import Scaffold diff --git a/src/flask/testing.py b/src/flask/testing.py index e07e50e7..df69d903 100644 --- a/src/flask/testing.py +++ b/src/flask/testing.py @@ -14,7 +14,7 @@ from .globals import _request_ctx_stack from .json import dumps as json_dumps from .sessions import SessionMixin -if t.TYPE_CHECKING: +if t.TYPE_CHECKING: # pragma: no cover from werkzeug.test import TestResponse from .app import Flask diff --git a/src/flask/typing.py b/src/flask/typing.py index a839a7e4..18c2b10e 100644 --- a/src/flask/typing.py +++ b/src/flask/typing.py @@ -1,42 +1,40 @@ import typing as t - -if t.TYPE_CHECKING: +if t.TYPE_CHECKING: # pragma: no cover from _typeshed.wsgi import WSGIApplication # noqa: F401 from werkzeug.datastructures import Headers # noqa: F401 - from werkzeug.wrappers.response import Response # noqa: F401 + from werkzeug.wrappers import Response # noqa: F401 # The possible types that are directly convertible or are a Response object. -ResponseValue = t.Union[ - "Response", - str, - bytes, - t.Dict[str, t.Any], # any jsonify-able dict - t.Iterator[str], - t.Iterator[bytes], -] -StatusCode = int +ResponseValue = t.Union["Response", str, bytes, t.Dict[str, t.Any]] # the possible types for an individual HTTP header -HeaderName = str +# This should be a Union, but mypy doesn't pass unless it's a TypeVar. HeaderValue = t.Union[str, t.List[str], t.Tuple[str, ...]] # the possible types for HTTP headers HeadersValue = t.Union[ - "Headers", t.Dict[HeaderName, HeaderValue], t.List[t.Tuple[HeaderName, HeaderValue]] + "Headers", + t.Mapping[str, HeaderValue], + t.Sequence[t.Tuple[str, HeaderValue]], ] # The possible types returned by a route function. ResponseReturnValue = t.Union[ ResponseValue, t.Tuple[ResponseValue, HeadersValue], - t.Tuple[ResponseValue, StatusCode], - t.Tuple[ResponseValue, StatusCode, HeadersValue], + t.Tuple[ResponseValue, int], + t.Tuple[ResponseValue, int, HeadersValue], "WSGIApplication", ] +# Allow any subclass of werkzeug.Response, such as the one from Flask, +# as a callback argument. Using werkzeug.Response directly makes a +# callback annotated with flask.Response fail type checking. +ResponseClass = t.TypeVar("ResponseClass", bound="Response") + AppOrBlueprintKey = t.Optional[str] # The App key is None, whereas blueprints are named -AfterRequestCallable = t.Callable[["Response"], "Response"] +AfterRequestCallable = t.Callable[[ResponseClass], ResponseClass] BeforeFirstRequestCallable = t.Callable[[], None] BeforeRequestCallable = t.Callable[[], t.Optional[ResponseReturnValue]] TeardownCallable = t.Callable[[t.Optional[BaseException]], None] @@ -46,6 +44,7 @@ TemplateGlobalCallable = t.Callable[..., t.Any] TemplateTestCallable = t.Callable[..., bool] URLDefaultCallable = t.Callable[[str, dict], None] URLValuePreprocessorCallable = t.Callable[[t.Optional[str], t.Optional[dict]], None] + # This should take Exception, but that either breaks typing the argument # with a specific exception, or decorating multiple times with different # exceptions (and using a union type on the argument). @@ -53,3 +52,7 @@ URLValuePreprocessorCallable = t.Callable[[t.Optional[str], t.Optional[dict]], N # https://github.com/pallets/flask/issues/4295 # https://github.com/pallets/flask/issues/4297 ErrorHandlerCallable = t.Callable[[t.Any], ResponseReturnValue] +ErrorHandlerDecorator = t.TypeVar("ErrorHandlerDecorator", bound=ErrorHandlerCallable) + +ViewCallable = t.Callable[..., ResponseReturnValue] +RouteDecorator = t.TypeVar("RouteDecorator", bound=ViewCallable) diff --git a/src/flask/views.py b/src/flask/views.py index 1bd5c68b..7aac3dd5 100644 --- a/src/flask/views.py +++ b/src/flask/views.py @@ -1,8 +1,8 @@ import typing as t +from . import typing as ft from .globals import current_app from .globals import request -from .typing import ResponseReturnValue http_method_funcs = frozenset( @@ -11,77 +11,106 @@ http_method_funcs = frozenset( class View: - """Alternative way to use view functions. A subclass has to implement - :meth:`dispatch_request` which is called with the view arguments from - the URL routing system. If :attr:`methods` is provided the methods - do not have to be passed to the :meth:`~flask.Flask.add_url_rule` - method explicitly:: + """Subclass this class and override :meth:`dispatch_request` to + create a generic class-based view. Call :meth:`as_view` to create a + view function that creates an instance of the class with the given + arguments and calls its ``dispatch_request`` method with any URL + variables. - class MyView(View): - methods = ['GET'] + See :doc:`views` for a detailed guide. + + .. code-block:: python + + class Hello(View): + init_every_request = False def dispatch_request(self, name): - return f"Hello {name}!" + return f"Hello, {name}!" - app.add_url_rule('/hello/', view_func=MyView.as_view('myview')) + app.add_url_rule( + "/hello/", view_func=Hello.as_view("hello") + ) - When you want to decorate a pluggable view you will have to either do that - when the view function is created (by wrapping the return value of - :meth:`as_view`) or you can use the :attr:`decorators` attribute:: + Set :attr:`methods` on the class to change what methods the view + accepts. - class SecretView(View): - methods = ['GET'] - decorators = [superuser_required] + Set :attr:`decorators` on the class to apply a list of decorators to + the generated view function. Decorators applied to the class itself + will not be applied to the generated view function! - def dispatch_request(self): - ... - - The decorators stored in the decorators list are applied one after another - when the view function is created. Note that you can *not* use the class - based decorators since those would decorate the view class and not the - generated view function! + Set :attr:`init_every_request` to ``False`` for efficiency, unless + you need to store request-global data on ``self``. """ - #: A list of methods this view can handle. - methods: t.Optional[t.List[str]] = None + #: The methods this view is registered for. Uses the same default + #: (``["GET", "HEAD", "OPTIONS"]``) as ``route`` and + #: ``add_url_rule`` by default. + methods: t.ClassVar[t.Optional[t.Collection[str]]] = None - #: Setting this disables or force-enables the automatic options handling. - provide_automatic_options: t.Optional[bool] = None + #: Control whether the ``OPTIONS`` method is handled automatically. + #: Uses the same default (``True``) as ``route`` and + #: ``add_url_rule`` by default. + provide_automatic_options: t.ClassVar[t.Optional[bool]] = None - #: The canonical way to decorate class-based views is to decorate the - #: return value of as_view(). However since this moves parts of the - #: logic from the class declaration to the place where it's hooked - #: into the routing system. - #: - #: You can place one or more decorators in this list and whenever the - #: view function is created the result is automatically decorated. + #: A list of decorators to apply, in order, to the generated view + #: function. Remember that ``@decorator`` syntax is applied bottom + #: to top, so the first decorator in the list would be the bottom + #: decorator. #: #: .. versionadded:: 0.8 - decorators: t.List[t.Callable] = [] + decorators: t.ClassVar[t.List[t.Callable]] = [] - def dispatch_request(self) -> ResponseReturnValue: - """Subclasses have to override this method to implement the - actual view function code. This method is called with all - the arguments from the URL rule. + #: Create a new instance of this view class for every request by + #: default. If a view subclass sets this to ``False``, the same + #: instance is used for every request. + #: + #: A single instance is more efficient, especially if complex setup + #: is done during init. However, storing data on ``self`` is no + #: longer safe across requests, and :data:`~flask.g` should be used + #: instead. + #: + #: .. versionadded:: 2.2 + init_every_request: t.ClassVar[bool] = True + + def dispatch_request(self) -> ft.ResponseReturnValue: + """The actual view function behavior. Subclasses must override + this and return a valid response. Any variables from the URL + rule are passed as keyword arguments. """ raise NotImplementedError() @classmethod def as_view( cls, name: str, *class_args: t.Any, **class_kwargs: t.Any - ) -> t.Callable: - """Converts the class into an actual view function that can be used - with the routing system. Internally this generates a function on the - fly which will instantiate the :class:`View` on each request and call - the :meth:`dispatch_request` method on it. + ) -> ft.ViewCallable: + """Convert the class into a view function that can be registered + for a route. - The arguments passed to :meth:`as_view` are forwarded to the - constructor of the class. + By default, the generated view will create a new instance of the + view class for every request and call its + :meth:`dispatch_request` method. If the view class sets + :attr:`init_every_request` to ``False``, the same instance will + be used for every request. + + The arguments passed to this method are forwarded to the view + class ``__init__`` method. + + .. versionchanged:: 2.2 + Added the ``init_every_request`` class attribute. """ + if cls.init_every_request: - def view(*args: t.Any, **kwargs: t.Any) -> ResponseReturnValue: - self = view.view_class(*class_args, **class_kwargs) # type: ignore - return current_app.ensure_sync(self.dispatch_request)(*args, **kwargs) + def view(**kwargs: t.Any) -> ft.ResponseReturnValue: + self = view.view_class( # type: ignore[attr-defined] + *class_args, **class_kwargs + ) + return current_app.ensure_sync(self.dispatch_request)(**kwargs) + + else: + self = cls(*class_args, **class_kwargs) + + def view(**kwargs: t.Any) -> ft.ResponseReturnValue: + return current_app.ensure_sync(self.dispatch_request)(**kwargs) if cls.decorators: view.__name__ = name @@ -103,50 +132,51 @@ class View: return view -class MethodViewType(type): - """Metaclass for :class:`MethodView` that determines what methods the view - defines. +class MethodView(View): + """Dispatches request methods to the corresponding instance methods. + For example, if you implement a ``get`` method, it will be used to + handle ``GET`` requests. + + This can be useful for defining a REST API. + + :attr:`methods` is automatically set based on the methods defined on + the class. + + See :doc:`views` for a detailed guide. + + .. code-block:: python + + class CounterAPI(MethodView): + def get(self): + return str(session.get("counter", 0)) + + def post(self): + session["counter"] = session.get("counter", 0) + 1 + return redirect(url_for("counter")) + + app.add_url_rule( + "/counter", view_func=CounterAPI.as_view("counter") + ) """ - def __init__(cls, name, bases, d): - super().__init__(name, bases, d) + def __init_subclass__(cls, **kwargs: t.Any) -> None: + super().__init_subclass__(**kwargs) - if "methods" not in d: + if "methods" not in cls.__dict__: methods = set() - for base in bases: + for base in cls.__bases__: if getattr(base, "methods", None): - methods.update(base.methods) + methods.update(base.methods) # type: ignore[attr-defined] for key in http_method_funcs: if hasattr(cls, key): methods.add(key.upper()) - # If we have no method at all in there we don't want to add a - # method list. This is for instance the case for the base class - # or another subclass of a base method view that does not introduce - # new methods. if methods: cls.methods = methods - -class MethodView(View, metaclass=MethodViewType): - """A class-based view that dispatches request methods to the corresponding - class methods. For example, if you implement a ``get`` method, it will be - used to handle ``GET`` requests. :: - - class CounterAPI(MethodView): - def get(self): - return session.get('counter', 0) - - def post(self): - session['counter'] = session.get('counter', 0) + 1 - return 'OK' - - app.add_url_rule('/counter', view_func=CounterAPI.as_view('counter')) - """ - - def dispatch_request(self, *args: t.Any, **kwargs: t.Any) -> ResponseReturnValue: + def dispatch_request(self, **kwargs: t.Any) -> ft.ResponseReturnValue: meth = getattr(self, request.method.lower(), None) # If the request method is HEAD and we don't have a handler for it @@ -155,4 +185,4 @@ class MethodView(View, metaclass=MethodViewType): meth = getattr(self, "get", None) assert meth is not None, f"Unimplemented method {request.method!r}" - return current_app.ensure_sync(meth)(*args, **kwargs) + return current_app.ensure_sync(meth)(**kwargs) diff --git a/src/flask/wrappers.py b/src/flask/wrappers.py index 7153876b..4b855bfc 100644 --- a/src/flask/wrappers.py +++ b/src/flask/wrappers.py @@ -8,7 +8,7 @@ from . import json from .globals import current_app from .helpers import _split_blueprint_path -if t.TYPE_CHECKING: +if t.TYPE_CHECKING: # pragma: no cover from werkzeug.routing import Rule diff --git a/tests/test_async.py b/tests/test_async.py index c8bb9bf0..38be27c9 100644 --- a/tests/test_async.py +++ b/tests/test_async.py @@ -107,10 +107,12 @@ def test_async_before_after_request(): def index(): return "" - @app.before_first_request - async def before_first(): - nonlocal app_first_called - app_first_called = True + with pytest.deprecated_call(): + + @app.before_first_request + async def before_first(): + nonlocal app_first_called + app_first_called = True @app.before_request async def before(): diff --git a/tests/test_basic.py b/tests/test_basic.py index 3dc3a0e9..7c1f4197 100644 --- a/tests/test_basic.py +++ b/tests/test_basic.py @@ -329,6 +329,11 @@ def test_session_using_session_settings(app, client): flask.session["testing"] = 42 return "Hello World" + @app.route("/clear") + def clear(): + flask.session.pop("testing", None) + return "Goodbye World" + rv = client.get("/", "http://www.example.com:8080/test/") cookie = rv.headers["set-cookie"].lower() assert "domain=.example.com" in cookie @@ -337,11 +342,6 @@ def test_session_using_session_settings(app, client): assert "httponly" not in cookie assert "samesite" in cookie - @app.route("/clear") - def clear(): - flask.session.pop("testing", None) - return "Goodbye World" - rv = client.get("/clear", "http://www.example.com:8080/test/") cookie = rv.headers["set-cookie"].lower() assert "session=;" in cookie @@ -899,13 +899,6 @@ def test_error_handling(app, client): assert b"forbidden" == rv.data -def test_error_handler_unknown_code(app): - with pytest.raises(KeyError) as exc_info: - app.register_error_handler(999, lambda e: ("999", 999)) - - assert "Use a subclass" in exc_info.value.args[0] - - def test_error_handling_processing(app, client): app.testing = False @@ -1038,7 +1031,14 @@ def test_errorhandler_precedence(app, client): assert rv.data == b"E2" -def test_trapping_of_bad_request_key_errors(app, client): +@pytest.mark.parametrize( + ("debug", "trap", "expect_key", "expect_abort"), + [(False, None, True, True), (True, None, False, True), (False, True, False, False)], +) +def test_trap_bad_request_key_error(app, client, debug, trap, expect_key, expect_abort): + app.config["DEBUG"] = debug + app.config["TRAP_BAD_REQUEST_ERRORS"] = trap + @app.route("/key") def fail(): flask.request.form["missing_key"] @@ -1047,26 +1047,23 @@ def test_trapping_of_bad_request_key_errors(app, client): def allow_abort(): flask.abort(400) - rv = client.get("/key") - assert rv.status_code == 400 - assert b"missing_key" not in rv.data - rv = client.get("/abort") - assert rv.status_code == 400 + if expect_key: + rv = client.get("/key") + assert rv.status_code == 400 + assert b"missing_key" not in rv.data + else: + with pytest.raises(KeyError) as exc_info: + client.get("/key") - app.debug = True - with pytest.raises(KeyError) as e: - client.get("/key") - assert e.errisinstance(BadRequest) - assert "missing_key" in e.value.get_description() - rv = client.get("/abort") - assert rv.status_code == 400 + assert exc_info.errisinstance(BadRequest) + assert "missing_key" in exc_info.value.get_description() - app.debug = False - app.config["TRAP_BAD_REQUEST_ERRORS"] = True - with pytest.raises(KeyError): - client.get("/key") - with pytest.raises(BadRequest): - client.get("/abort") + if expect_abort: + rv = client.get("/abort") + assert rv.status_code == 400 + else: + with pytest.raises(BadRequest): + client.get("/abort") def test_trapping_of_all_http_exceptions(app, client): @@ -1668,7 +1665,7 @@ def test_nonascii_pathinfo(app, client): assert rv.data == b"Hello World!" -def test_debug_mode_complains_after_first_request(app, client): +def test_no_setup_after_first_request(app, client): app.debug = True @app.route("/") @@ -1678,27 +1675,20 @@ def test_debug_mode_complains_after_first_request(app, client): assert not app.got_first_request assert client.get("/").data == b"Awesome" - with pytest.raises(AssertionError) as e: + with pytest.raises(AssertionError) as exc_info: app.add_url_rule("/foo", endpoint="late") - assert "A setup function was called" in str(e.value) - - app.debug = False - - @app.route("/foo") - def working(): - return "Meh" - - assert client.get("/foo").data == b"Meh" - assert app.got_first_request + assert "setup method 'add_url_rule'" in str(exc_info.value) def test_before_first_request_functions(app, client): got = [] - @app.before_first_request - def foo(): - got.append(42) + with pytest.deprecated_call(): + + @app.before_first_request + def foo(): + got.append(42) client.get("/") assert got == [42] @@ -1710,10 +1700,12 @@ def test_before_first_request_functions(app, client): def test_before_first_request_functions_concurrent(app, client): got = [] - @app.before_first_request - def foo(): - time.sleep(0.2) - got.append(42) + with pytest.deprecated_call(): + + @app.before_first_request + def foo(): + time.sleep(0.2) + got.append(42) def get_and_assert(): client.get("/") @@ -1727,28 +1719,23 @@ def test_before_first_request_functions_concurrent(app, client): def test_routing_redirect_debugging(monkeypatch, app, client): - @app.route("/foo/", methods=["GET", "POST"]) - def foo(): - return "success" + app.config["DEBUG"] = True - app.debug = False - rv = client.post("/foo", data={}, follow_redirects=True) + @app.route("/user/", methods=["GET", "POST"]) + def user(): + return flask.request.form["status"] + + # default redirect code preserves form data + rv = client.post("/user", data={"status": "success"}, follow_redirects=True) assert rv.data == b"success" - app.debug = True - - with client: - rv = client.post("/foo", data={}, follow_redirects=True) - assert rv.data == b"success" - rv = client.get("/foo", data={}, follow_redirects=True) - assert rv.data == b"success" - + # 301 and 302 raise error monkeypatch.setattr(RequestRedirect, "code", 301) - with client, pytest.raises(AssertionError) as e: - client.post("/foo", data={}) + with client, pytest.raises(AssertionError) as exc_info: + client.post("/user", data={"status": "error"}, follow_redirects=True) - assert "canonical URL 'http://localhost/foo/'" in str(e.value) + assert "canonical URL 'http://localhost/user/'" in str(exc_info.value) def test_route_decorator_custom_endpoint(app, client): diff --git a/tests/test_blueprints.py b/tests/test_blueprints.py index fbe9eeee..1bf130f5 100644 --- a/tests/test_blueprints.py +++ b/tests/test_blueprints.py @@ -722,9 +722,11 @@ def test_app_request_processing(app, client): bp = flask.Blueprint("bp", __name__) evts = [] - @bp.before_app_first_request - def before_first_request(): - evts.append("first") + with pytest.deprecated_call(): + + @bp.before_app_first_request + def before_first_request(): + evts.append("first") @bp.before_app_request def before_app(): diff --git a/tests/test_cli.py b/tests/test_cli.py index 6e8b57f0..c9dd5ade 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -18,7 +18,6 @@ from flask import current_app from flask import Flask from flask.cli import AppGroup from flask.cli import DispatchingApp -from flask.cli import dotenv from flask.cli import find_best_app from flask.cli import FlaskGroup from flask.cli import get_version @@ -492,7 +491,18 @@ class TestRoutes: assert "No routes were registered." in result.output -need_dotenv = pytest.mark.skipif(dotenv is None, reason="dotenv is not installed") +def dotenv_not_available(): + try: + import dotenv # noqa: F401 + except ImportError: + return True + + return False + + +need_dotenv = pytest.mark.skipif( + dotenv_not_available(), reason="dotenv is not installed" +) @need_dotenv @@ -530,7 +540,7 @@ def test_dotenv_path(monkeypatch): def test_dotenv_optional(monkeypatch): - monkeypatch.setattr("flask.cli.dotenv", None) + monkeypatch.setitem(sys.modules, "dotenv", None) monkeypatch.chdir(test_path) load_dotenv() assert "FOO" not in os.environ @@ -602,7 +612,8 @@ def test_run_cert_import(monkeypatch): def test_run_cert_no_ssl(monkeypatch): - monkeypatch.setattr("flask.cli.ssl", None) + monkeypatch.setitem(sys.modules, "ssl", None) + with pytest.raises(click.BadParameter): run_command.make_context("run", ["--cert", "not_here"]) diff --git a/tests/test_config.py b/tests/test_config.py index 944b93d7..cd856b2b 100644 --- a/tests/test_config.py +++ b/tests/test_config.py @@ -113,6 +113,10 @@ def test_config_from_mapping(): app.config.from_mapping(SECRET_KEY="config", TEST_KEY="foo") common_object_test(app) + app = flask.Flask(__name__) + app.config.from_mapping(SECRET_KEY="config", TEST_KEY="foo", skip_key="skip") + common_object_test(app) + app = flask.Flask(__name__) with pytest.raises(TypeError): app.config.from_mapping({}, {}) diff --git a/tests/test_helpers.py b/tests/test_helpers.py index 58bf3c0b..cc2daaf7 100644 --- a/tests/test_helpers.py +++ b/tests/test_helpers.py @@ -2,6 +2,7 @@ import io import os import pytest +import werkzeug.exceptions import flask from flask.helpers import get_debug_flag @@ -118,11 +119,15 @@ class TestUrlFor: ) def test_url_for_with_scheme_not_external(self, app, req_ctx): - @app.route("/") - def index(): - return "42" + app.add_url_rule("/", endpoint="index") - pytest.raises(ValueError, flask.url_for, "index", _scheme="https") + # Implicit external with scheme. + url = flask.url_for("index", _scheme="https") + assert url == "https://localhost/" + + # Error when external=False with scheme + with pytest.raises(ValueError): + flask.url_for("index", _scheme="https", _external=False) def test_url_for_with_alternating_schemes(self, app, req_ctx): @app.route("/") @@ -158,6 +163,51 @@ class TestUrlFor: assert flask.url_for("myview", _method="POST") == "/myview/create" +def test_redirect_no_app(): + response = flask.redirect("https://localhost", 307) + assert response.location == "https://localhost" + assert response.status_code == 307 + + +def test_redirect_with_app(app): + def redirect(location, code=302): + raise ValueError + + app.redirect = redirect + + with app.app_context(), pytest.raises(ValueError): + flask.redirect("other") + + +def test_abort_no_app(): + with pytest.raises(werkzeug.exceptions.Unauthorized): + flask.abort(401) + + with pytest.raises(LookupError): + flask.abort(900) + + +def test_app_aborter_class(): + class MyAborter(werkzeug.exceptions.Aborter): + pass + + class MyFlask(flask.Flask): + aborter_class = MyAborter + + app = MyFlask(__name__) + assert isinstance(app.aborter, MyAborter) + + +def test_abort_with_app(app): + class My900Error(werkzeug.exceptions.HTTPException): + code = 900 + + app.aborter.mapping[900] = My900Error + + with app.app_context(), pytest.raises(My900Error): + flask.abort(900) + + class TestNoImports: """Test Flasks are created without import. diff --git a/tests/test_instance_config.py b/tests/test_instance_config.py index ee573664..c8cf0bf7 100644 --- a/tests/test_instance_config.py +++ b/tests/test_instance_config.py @@ -1,4 +1,3 @@ -import os import sys import pytest @@ -15,19 +14,6 @@ def test_explicit_instance_paths(modules_tmpdir): assert app.instance_path == str(modules_tmpdir) -@pytest.mark.xfail(reason="weird interaction with tox") -def test_main_module_paths(modules_tmpdir, purge_module): - app = modules_tmpdir.join("main_app.py") - app.write('import flask\n\napp = flask.Flask("__main__")') - purge_module("main_app") - - from main_app import app - - here = os.path.abspath(os.getcwd()) - assert app.instance_path == os.path.join(here, "instance") - - -@pytest.mark.xfail(reason="weird interaction with tox") def test_uninstalled_module_paths(modules_tmpdir, purge_module): app = modules_tmpdir.join("config_module_app.py").write( "import os\n" @@ -42,7 +28,6 @@ def test_uninstalled_module_paths(modules_tmpdir, purge_module): assert app.instance_path == str(modules_tmpdir.join("instance")) -@pytest.mark.xfail(reason="weird interaction with tox") def test_uninstalled_package_paths(modules_tmpdir, purge_module): app = modules_tmpdir.mkdir("config_package_app") init = app.join("__init__.py") @@ -59,6 +44,25 @@ def test_uninstalled_package_paths(modules_tmpdir, purge_module): assert app.instance_path == str(modules_tmpdir.join("instance")) +def test_uninstalled_namespace_paths(tmpdir, monkeypatch, purge_module): + def create_namespace(package): + project = tmpdir.join(f"project-{package}") + monkeypatch.syspath_prepend(str(project)) + project.join("namespace").join(package).join("__init__.py").write( + "import flask\napp = flask.Flask(__name__)\n", ensure=True + ) + return project + + _ = create_namespace("package1") + project2 = create_namespace("package2") + purge_module("namespace.package2") + purge_module("namespace") + + from namespace.package2 import app + + assert app.instance_path == str(project2.join("instance")) + + def test_installed_module_paths( modules_tmpdir, modules_tmpdir_prefix, purge_module, site_packages, limit_loader ): diff --git a/tests/test_user_error_handler.py b/tests/test_user_error_handler.py index d9f94a3f..79c5a73c 100644 --- a/tests/test_user_error_handler.py +++ b/tests/test_user_error_handler.py @@ -11,29 +11,35 @@ def test_error_handler_no_match(app, client): class CustomException(Exception): pass - class UnacceptableCustomException(BaseException): - pass - @app.errorhandler(CustomException) def custom_exception_handler(e): assert isinstance(e, CustomException) return "custom" - with pytest.raises( - AssertionError, match="Custom exceptions must be subclasses of Exception." - ): - app.register_error_handler(UnacceptableCustomException, None) + with pytest.raises(TypeError) as exc_info: + app.register_error_handler(CustomException(), None) + + assert "CustomException() is an instance, not a class." in str(exc_info.value) + + with pytest.raises(ValueError) as exc_info: + app.register_error_handler(list, None) + + assert "'list' is not a subclass of Exception." in str(exc_info.value) @app.errorhandler(500) def handle_500(e): assert isinstance(e, InternalServerError) - original = getattr(e, "original_exception", None) - if original is not None: - return f"wrapped {type(original).__name__}" + if e.original_exception is not None: + return f"wrapped {type(e.original_exception).__name__}" return "direct" + with pytest.raises(ValueError) as exc_info: + app.register_error_handler(999, None) + + assert "Use a subclass of HTTPException" in str(exc_info.value) + @app.route("/custom") def custom_test(): raise CustomException() diff --git a/tests/test_views.py b/tests/test_views.py index 0e215252..8d870def 100644 --- a/tests/test_views.py +++ b/tests/test_views.py @@ -240,3 +240,21 @@ def test_remove_method_from_parent(app, client): assert client.get("/").data == b"GET" assert client.post("/").status_code == 405 assert sorted(View.methods) == ["GET"] + + +def test_init_once(app, client): + n = 0 + + class CountInit(flask.views.View): + init_every_request = False + + def __init__(self): + nonlocal n + n += 1 + + def dispatch_request(self): + return str(n) + + app.add_url_rule("/", view_func=CountInit.as_view("index")) + assert client.get("/").data == b"1" + assert client.get("/").data == b"1" diff --git a/tests/typing/typing_error_handler.py b/tests/typing/typing_error_handler.py new file mode 100644 index 00000000..ec9c886f --- /dev/null +++ b/tests/typing/typing_error_handler.py @@ -0,0 +1,33 @@ +from __future__ import annotations + +from http import HTTPStatus + +from werkzeug.exceptions import BadRequest +from werkzeug.exceptions import NotFound + +from flask import Flask + +app = Flask(__name__) + + +@app.errorhandler(400) +@app.errorhandler(HTTPStatus.BAD_REQUEST) +@app.errorhandler(BadRequest) +def handle_400(e: BadRequest) -> str: + return "" + + +@app.errorhandler(ValueError) +def handle_custom(e: ValueError) -> str: + return "" + + +@app.errorhandler(ValueError) +def handle_accept_base(e: Exception) -> str: + return "" + + +@app.errorhandler(BadRequest) +@app.errorhandler(404) +def handle_multiple(e: BadRequest | NotFound) -> str: + return "" diff --git a/tests/typing/typing_route.py b/tests/typing/typing_route.py new file mode 100644 index 00000000..ba49d132 --- /dev/null +++ b/tests/typing/typing_route.py @@ -0,0 +1,62 @@ +from __future__ import annotations + +from http import HTTPStatus + +from flask import Flask +from flask import jsonify +from flask.templating import render_template +from flask.views import View +from flask.wrappers import Response + +app = Flask(__name__) + + +@app.route("/str") +def hello_str() -> str: + return "

Hello, World!

" + + +@app.route("/bytes") +def hello_bytes() -> bytes: + return b"

Hello, World!

" + + +@app.route("/json") +def hello_json() -> Response: + return jsonify({"response": "Hello, World!"}) + + +@app.route("/status") +@app.route("/status/") +def tuple_status(code: int = 200) -> tuple[str, int]: + return "hello", code + + +@app.route("/status-enum") +def tuple_status_enum() -> tuple[str, int]: + return "hello", HTTPStatus.OK + + +@app.route("/headers") +def tuple_headers() -> tuple[str, dict[str, str]]: + return "Hello, World!", {"Content-Type": "text/plain"} + + +@app.route("/template") +@app.route("/template/") +def return_template(name: str | None = None) -> str: + return render_template("index.html", name=name) + + +class RenderTemplateView(View): + def __init__(self: RenderTemplateView, template_name: str) -> None: + self.template_name = template_name + + def dispatch_request(self: RenderTemplateView) -> str: + return render_template(self.template_name) + + +app.add_url_rule( + "/about", + view_func=RenderTemplateView.as_view("about_page", template_name="about.html"), +) diff --git a/tox.ini b/tox.ini index 077d66f2..ee4d40f6 100644 --- a/tox.ini +++ b/tox.ini @@ -9,6 +9,7 @@ envlist = skip_missing_interpreters = true [testenv] +envtmpdir = {toxworkdir}/tmp/{envname} deps = -r requirements/tests.txt min: -r requirements/tests-pallets-min.txt