Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/flask/sansio/app.py: 42%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1from __future__ import annotations
3import logging
4import os
5import sys
6import typing as t
7from datetime import timedelta
8from itertools import chain
10from werkzeug.exceptions import Aborter
11from werkzeug.exceptions import BadRequest
12from werkzeug.exceptions import BadRequestKeyError
13from werkzeug.routing import BuildError
14from werkzeug.routing import Map
15from werkzeug.routing import Rule
16from werkzeug.sansio.response import Response
17from werkzeug.utils import cached_property
18from werkzeug.utils import redirect as _wz_redirect
20from .. import typing as ft
21from ..config import Config
22from ..config import ConfigAttribute
23from ..ctx import _AppCtxGlobals
24from ..helpers import _split_blueprint_path
25from ..helpers import get_debug_flag
26from ..json.provider import DefaultJSONProvider
27from ..json.provider import JSONProvider
28from ..logging import create_logger
29from ..templating import DispatchingJinjaLoader
30from ..templating import Environment
31from .scaffold import _endpoint_from_view_func
32from .scaffold import find_package
33from .scaffold import Scaffold
34from .scaffold import setupmethod
36if t.TYPE_CHECKING: # pragma: no cover
37 from werkzeug.wrappers import Response as BaseResponse
39 from ..testing import FlaskClient
40 from ..testing import FlaskCliRunner
41 from .blueprints import Blueprint
43T_shell_context_processor = t.TypeVar(
44 "T_shell_context_processor", bound=ft.ShellContextProcessorCallable
45)
46T_teardown = t.TypeVar("T_teardown", bound=ft.TeardownCallable)
47T_template_filter = t.TypeVar("T_template_filter", bound=ft.TemplateFilterCallable)
48T_template_global = t.TypeVar("T_template_global", bound=ft.TemplateGlobalCallable)
49T_template_test = t.TypeVar("T_template_test", bound=ft.TemplateTestCallable)
52def _make_timedelta(value: timedelta | int | None) -> timedelta | None:
53 if value is None or isinstance(value, timedelta):
54 return value
56 return timedelta(seconds=value)
59class App(Scaffold):
60 """The flask object implements a WSGI application and acts as the central
61 object. It is passed the name of the module or package of the
62 application. Once it is created it will act as a central registry for
63 the view functions, the URL rules, template configuration and much more.
65 The name of the package is used to resolve resources from inside the
66 package or the folder the module is contained in depending on if the
67 package parameter resolves to an actual python package (a folder with
68 an :file:`__init__.py` file inside) or a standard module (just a ``.py`` file).
70 For more information about resource loading, see :func:`open_resource`.
72 Usually you create a :class:`Flask` instance in your main module or
73 in the :file:`__init__.py` file of your package like this::
75 from flask import Flask
76 app = Flask(__name__)
78 .. admonition:: About the First Parameter
80 The idea of the first parameter is to give Flask an idea of what
81 belongs to your application. This name is used to find resources
82 on the filesystem, can be used by extensions to improve debugging
83 information and a lot more.
85 So it's important what you provide there. If you are using a single
86 module, `__name__` is always the correct value. If you however are
87 using a package, it's usually recommended to hardcode the name of
88 your package there.
90 For example if your application is defined in :file:`yourapplication/app.py`
91 you should create it with one of the two versions below::
93 app = Flask('yourapplication')
94 app = Flask(__name__.split('.')[0])
96 Why is that? The application will work even with `__name__`, thanks
97 to how resources are looked up. However it will make debugging more
98 painful. Certain extensions can make assumptions based on the
99 import name of your application. For example the Flask-SQLAlchemy
100 extension will look for the code in your application that triggered
101 an SQL query in debug mode. If the import name is not properly set
102 up, that debugging information is lost. (For example it would only
103 pick up SQL queries in `yourapplication.app` and not
104 `yourapplication.views.frontend`)
106 .. versionadded:: 0.7
107 The `static_url_path`, `static_folder`, and `template_folder`
108 parameters were added.
110 .. versionadded:: 0.8
111 The `instance_path` and `instance_relative_config` parameters were
112 added.
114 .. versionadded:: 0.11
115 The `root_path` parameter was added.
117 .. versionadded:: 1.0
118 The ``host_matching`` and ``static_host`` parameters were added.
120 .. versionadded:: 1.0
121 The ``subdomain_matching`` parameter was added. Subdomain
122 matching needs to be enabled manually now. Setting
123 :data:`SERVER_NAME` does not implicitly enable it.
125 :param import_name: the name of the application package
126 :param static_url_path: can be used to specify a different path for the
127 static files on the web. Defaults to the name
128 of the `static_folder` folder.
129 :param static_folder: The folder with static files that is served at
130 ``static_url_path``. Relative to the application ``root_path``
131 or an absolute path. Defaults to ``'static'``.
132 :param static_host: the host to use when adding the static route.
133 Defaults to None. Required when using ``host_matching=True``
134 with a ``static_folder`` configured.
135 :param host_matching: set ``url_map.host_matching`` attribute.
136 Defaults to False.
137 :param subdomain_matching: consider the subdomain relative to
138 :data:`SERVER_NAME` when matching routes. Defaults to False.
139 :param template_folder: the folder that contains the templates that should
140 be used by the application. Defaults to
141 ``'templates'`` folder in the root path of the
142 application.
143 :param instance_path: An alternative instance path for the application.
144 By default the folder ``'instance'`` next to the
145 package or module is assumed to be the instance
146 path.
147 :param instance_relative_config: if set to ``True`` relative filenames
148 for loading the config are assumed to
149 be relative to the instance path instead
150 of the application root.
151 :param root_path: The path to the root of the application files.
152 This should only be set manually when it can't be detected
153 automatically, such as for namespace packages.
154 """
156 #: The class of the object assigned to :attr:`aborter`, created by
157 #: :meth:`create_aborter`. That object is called by
158 #: :func:`flask.abort` to raise HTTP errors, and can be
159 #: called directly as well.
160 #:
161 #: Defaults to :class:`werkzeug.exceptions.Aborter`.
162 #:
163 #: .. versionadded:: 2.2
164 aborter_class = Aborter
166 #: The class that is used for the Jinja environment.
167 #:
168 #: .. versionadded:: 0.11
169 jinja_environment = Environment
171 #: The class that is used for the :data:`~flask.g` instance.
172 #:
173 #: Example use cases for a custom class:
174 #:
175 #: 1. Store arbitrary attributes on flask.g.
176 #: 2. Add a property for lazy per-request database connectors.
177 #: 3. Return None instead of AttributeError on unexpected attributes.
178 #: 4. Raise exception if an unexpected attr is set, a "controlled" flask.g.
179 #:
180 #: In Flask 0.9 this property was called `request_globals_class` but it
181 #: was changed in 0.10 to :attr:`app_ctx_globals_class` because the
182 #: flask.g object is now application context scoped.
183 #:
184 #: .. versionadded:: 0.10
185 app_ctx_globals_class = _AppCtxGlobals
187 #: The class that is used for the ``config`` attribute of this app.
188 #: Defaults to :class:`~flask.Config`.
189 #:
190 #: Example use cases for a custom class:
191 #:
192 #: 1. Default values for certain config options.
193 #: 2. Access to config values through attributes in addition to keys.
194 #:
195 #: .. versionadded:: 0.11
196 config_class = Config
198 #: The testing flag. Set this to ``True`` to enable the test mode of
199 #: Flask extensions (and in the future probably also Flask itself).
200 #: For example this might activate test helpers that have an
201 #: additional runtime cost which should not be enabled by default.
202 #:
203 #: If this is enabled and PROPAGATE_EXCEPTIONS is not changed from the
204 #: default it's implicitly enabled.
205 #:
206 #: This attribute can also be configured from the config with the
207 #: ``TESTING`` configuration key. Defaults to ``False``.
208 testing = ConfigAttribute[bool]("TESTING")
210 #: If a secret key is set, cryptographic components can use this to
211 #: sign cookies and other things. Set this to a complex random value
212 #: when you want to use the secure cookie for instance.
213 #:
214 #: This attribute can also be configured from the config with the
215 #: :data:`SECRET_KEY` configuration key. Defaults to ``None``.
216 secret_key = ConfigAttribute[t.Union[str, bytes, None]]("SECRET_KEY")
218 #: A :class:`~datetime.timedelta` which is used to set the expiration
219 #: date of a permanent session. The default is 31 days which makes a
220 #: permanent session survive for roughly one month.
221 #:
222 #: This attribute can also be configured from the config with the
223 #: ``PERMANENT_SESSION_LIFETIME`` configuration key. Defaults to
224 #: ``timedelta(days=31)``
225 permanent_session_lifetime = ConfigAttribute[timedelta](
226 "PERMANENT_SESSION_LIFETIME",
227 get_converter=_make_timedelta, # type: ignore[arg-type]
228 )
230 json_provider_class: type[JSONProvider] = DefaultJSONProvider
231 """A subclass of :class:`~flask.json.provider.JSONProvider`. An
232 instance is created and assigned to :attr:`app.json` when creating
233 the app.
235 The default, :class:`~flask.json.provider.DefaultJSONProvider`, uses
236 Python's built-in :mod:`json` library. A different provider can use
237 a different JSON library.
239 .. versionadded:: 2.2
240 """
242 #: Options that are passed to the Jinja environment in
243 #: :meth:`create_jinja_environment`. Changing these options after
244 #: the environment is created (accessing :attr:`jinja_env`) will
245 #: have no effect.
246 #:
247 #: .. versionchanged:: 1.1.0
248 #: This is a ``dict`` instead of an ``ImmutableDict`` to allow
249 #: easier configuration.
250 #:
251 jinja_options: dict[str, t.Any] = {}
253 #: The rule object to use for URL rules created. This is used by
254 #: :meth:`add_url_rule`. Defaults to :class:`werkzeug.routing.Rule`.
255 #:
256 #: .. versionadded:: 0.7
257 url_rule_class = Rule
259 #: The map object to use for storing the URL rules and routing
260 #: configuration parameters. Defaults to :class:`werkzeug.routing.Map`.
261 #:
262 #: .. versionadded:: 1.1.0
263 url_map_class = Map
265 #: The :meth:`test_client` method creates an instance of this test
266 #: client class. Defaults to :class:`~flask.testing.FlaskClient`.
267 #:
268 #: .. versionadded:: 0.7
269 test_client_class: type[FlaskClient] | None = None
271 #: The :class:`~click.testing.CliRunner` subclass, by default
272 #: :class:`~flask.testing.FlaskCliRunner` that is used by
273 #: :meth:`test_cli_runner`. Its ``__init__`` method should take a
274 #: Flask app object as the first argument.
275 #:
276 #: .. versionadded:: 1.0
277 test_cli_runner_class: type[FlaskCliRunner] | None = None
279 default_config: dict[str, t.Any]
280 response_class: type[Response]
282 def __init__(
283 self,
284 import_name: str,
285 static_url_path: str | None = None,
286 static_folder: str | os.PathLike[str] | None = "static",
287 static_host: str | None = None,
288 host_matching: bool = False,
289 subdomain_matching: bool = False,
290 template_folder: str | os.PathLike[str] | None = "templates",
291 instance_path: str | None = None,
292 instance_relative_config: bool = False,
293 root_path: str | None = None,
294 ):
295 super().__init__(
296 import_name=import_name,
297 static_folder=static_folder,
298 static_url_path=static_url_path,
299 template_folder=template_folder,
300 root_path=root_path,
301 )
303 if instance_path is None:
304 instance_path = self.auto_find_instance_path()
305 elif not os.path.isabs(instance_path):
306 raise ValueError(
307 "If an instance path is provided it must be absolute."
308 " A relative path was given instead."
309 )
311 #: Holds the path to the instance folder.
312 #:
313 #: .. versionadded:: 0.8
314 self.instance_path = instance_path
316 #: The configuration dictionary as :class:`Config`. This behaves
317 #: exactly like a regular dictionary but supports additional methods
318 #: to load a config from files.
319 self.config = self.make_config(instance_relative_config)
321 #: An instance of :attr:`aborter_class` created by
322 #: :meth:`make_aborter`. This is called by :func:`flask.abort`
323 #: to raise HTTP errors, and can be called directly as well.
324 #:
325 #: .. versionadded:: 2.2
326 #: Moved from ``flask.abort``, which calls this object.
327 self.aborter = self.make_aborter()
329 self.json: JSONProvider = self.json_provider_class(self)
330 """Provides access to JSON methods. Functions in ``flask.json``
331 will call methods on this provider when the application context
332 is active. Used for handling JSON requests and responses.
334 An instance of :attr:`json_provider_class`. Can be customized by
335 changing that attribute on a subclass, or by assigning to this
336 attribute afterwards.
338 The default, :class:`~flask.json.provider.DefaultJSONProvider`,
339 uses Python's built-in :mod:`json` library. A different provider
340 can use a different JSON library.
342 .. versionadded:: 2.2
343 """
345 #: A list of functions that are called by
346 #: :meth:`handle_url_build_error` when :meth:`.url_for` raises a
347 #: :exc:`~werkzeug.routing.BuildError`. Each function is called
348 #: with ``error``, ``endpoint`` and ``values``. If a function
349 #: returns ``None`` or raises a ``BuildError``, it is skipped.
350 #: Otherwise, its return value is returned by ``url_for``.
351 #:
352 #: .. versionadded:: 0.9
353 self.url_build_error_handlers: list[
354 t.Callable[[Exception, str, dict[str, t.Any]], str]
355 ] = []
357 #: A list of functions that are called when the application context
358 #: is destroyed. Since the application context is also torn down
359 #: if the request ends this is the place to store code that disconnects
360 #: from databases.
361 #:
362 #: .. versionadded:: 0.9
363 self.teardown_appcontext_funcs: list[ft.TeardownCallable] = []
365 #: A list of shell context processor functions that should be run
366 #: when a shell context is created.
367 #:
368 #: .. versionadded:: 0.11
369 self.shell_context_processors: list[ft.ShellContextProcessorCallable] = []
371 #: Maps registered blueprint names to blueprint objects. The
372 #: dict retains the order the blueprints were registered in.
373 #: Blueprints can be registered multiple times, this dict does
374 #: not track how often they were attached.
375 #:
376 #: .. versionadded:: 0.7
377 self.blueprints: dict[str, Blueprint] = {}
379 #: a place where extensions can store application specific state. For
380 #: example this is where an extension could store database engines and
381 #: similar things.
382 #:
383 #: The key must match the name of the extension module. For example in
384 #: case of a "Flask-Foo" extension in `flask_foo`, the key would be
385 #: ``'foo'``.
386 #:
387 #: .. versionadded:: 0.7
388 self.extensions: dict[str, t.Any] = {}
390 #: The :class:`~werkzeug.routing.Map` for this instance. You can use
391 #: this to change the routing converters after the class was created
392 #: but before any routes are connected. Example::
393 #:
394 #: from werkzeug.routing import BaseConverter
395 #:
396 #: class ListConverter(BaseConverter):
397 #: def to_python(self, value):
398 #: return value.split(',')
399 #: def to_url(self, values):
400 #: return ','.join(super(ListConverter, self).to_url(value)
401 #: for value in values)
402 #:
403 #: app = Flask(__name__)
404 #: app.url_map.converters['list'] = ListConverter
405 self.url_map = self.url_map_class(host_matching=host_matching)
407 self.subdomain_matching = subdomain_matching
409 # tracks internally if the application already handled at least one
410 # request.
411 self._got_first_request = False
413 def _check_setup_finished(self, f_name: str) -> None:
414 if self._got_first_request:
415 raise AssertionError(
416 f"The setup method '{f_name}' can no longer be called"
417 " on the application. It has already handled its first"
418 " request, any changes will not be applied"
419 " consistently.\n"
420 "Make sure all imports, decorators, functions, etc."
421 " needed to set up the application are done before"
422 " running it."
423 )
425 @cached_property
426 def name(self) -> str: # type: ignore
427 """The name of the application. This is usually the import name
428 with the difference that it's guessed from the run file if the
429 import name is main. This name is used as a display name when
430 Flask needs the name of the application. It can be set and overridden
431 to change the value.
433 .. versionadded:: 0.8
434 """
435 if self.import_name == "__main__":
436 fn: str | None = getattr(sys.modules["__main__"], "__file__", None)
437 if fn is None:
438 return "__main__"
439 return os.path.splitext(os.path.basename(fn))[0]
440 return self.import_name
442 @cached_property
443 def logger(self) -> logging.Logger:
444 """A standard Python :class:`~logging.Logger` for the app, with
445 the same name as :attr:`name`.
447 In debug mode, the logger's :attr:`~logging.Logger.level` will
448 be set to :data:`~logging.DEBUG`.
450 If there are no handlers configured, a default handler will be
451 added. See :doc:`/logging` for more information.
453 .. versionchanged:: 1.1.0
454 The logger takes the same name as :attr:`name` rather than
455 hard-coding ``"flask.app"``.
457 .. versionchanged:: 1.0.0
458 Behavior was simplified. The logger is always named
459 ``"flask.app"``. The level is only set during configuration,
460 it doesn't check ``app.debug`` each time. Only one format is
461 used, not different ones depending on ``app.debug``. No
462 handlers are removed, and a handler is only added if no
463 handlers are already configured.
465 .. versionadded:: 0.3
466 """
467 return create_logger(self)
469 @cached_property
470 def jinja_env(self) -> Environment:
471 """The Jinja environment used to load templates.
473 The environment is created the first time this property is
474 accessed. Changing :attr:`jinja_options` after that will have no
475 effect.
476 """
477 return self.create_jinja_environment()
479 def create_jinja_environment(self) -> Environment:
480 raise NotImplementedError()
482 def make_config(self, instance_relative: bool = False) -> Config:
483 """Used to create the config attribute by the Flask constructor.
484 The `instance_relative` parameter is passed in from the constructor
485 of Flask (there named `instance_relative_config`) and indicates if
486 the config should be relative to the instance path or the root path
487 of the application.
489 .. versionadded:: 0.8
490 """
491 root_path = self.root_path
492 if instance_relative:
493 root_path = self.instance_path
494 defaults = dict(self.default_config)
495 defaults["DEBUG"] = get_debug_flag()
496 return self.config_class(root_path, defaults)
498 def make_aborter(self) -> Aborter:
499 """Create the object to assign to :attr:`aborter`. That object
500 is called by :func:`flask.abort` to raise HTTP errors, and can
501 be called directly as well.
503 By default, this creates an instance of :attr:`aborter_class`,
504 which defaults to :class:`werkzeug.exceptions.Aborter`.
506 .. versionadded:: 2.2
507 """
508 return self.aborter_class()
510 def auto_find_instance_path(self) -> str:
511 """Tries to locate the instance path if it was not provided to the
512 constructor of the application class. It will basically calculate
513 the path to a folder named ``instance`` next to your main file or
514 the package.
516 .. versionadded:: 0.8
517 """
518 prefix, package_path = find_package(self.import_name)
519 if prefix is None:
520 return os.path.join(package_path, "instance")
521 return os.path.join(prefix, "var", f"{self.name}-instance")
523 def create_global_jinja_loader(self) -> DispatchingJinjaLoader:
524 """Creates the loader for the Jinja2 environment. Can be used to
525 override just the loader and keeping the rest unchanged. It's
526 discouraged to override this function. Instead one should override
527 the :meth:`jinja_loader` function instead.
529 The global loader dispatches between the loaders of the application
530 and the individual blueprints.
532 .. versionadded:: 0.7
533 """
534 return DispatchingJinjaLoader(self)
536 def select_jinja_autoescape(self, filename: str) -> bool:
537 """Returns ``True`` if autoescaping should be active for the given
538 template name. If no template name is given, returns `True`.
540 .. versionchanged:: 2.2
541 Autoescaping is now enabled by default for ``.svg`` files.
543 .. versionadded:: 0.5
544 """
545 if filename is None:
546 return True
547 return filename.endswith((".html", ".htm", ".xml", ".xhtml", ".svg"))
549 @property
550 def debug(self) -> bool:
551 """Whether debug mode is enabled. When using ``flask run`` to start the
552 development server, an interactive debugger will be shown for unhandled
553 exceptions, and the server will be reloaded when code changes. This maps to the
554 :data:`DEBUG` config key. It may not behave as expected if set late.
556 **Do not enable debug mode when deploying in production.**
558 Default: ``False``
559 """
560 return self.config["DEBUG"] # type: ignore[no-any-return]
562 @debug.setter
563 def debug(self, value: bool) -> None:
564 self.config["DEBUG"] = value
566 if self.config["TEMPLATES_AUTO_RELOAD"] is None:
567 self.jinja_env.auto_reload = value
569 @setupmethod
570 def register_blueprint(self, blueprint: Blueprint, **options: t.Any) -> None:
571 """Register a :class:`~flask.Blueprint` on the application. Keyword
572 arguments passed to this method will override the defaults set on the
573 blueprint.
575 Calls the blueprint's :meth:`~flask.Blueprint.register` method after
576 recording the blueprint in the application's :attr:`blueprints`.
578 :param blueprint: The blueprint to register.
579 :param url_prefix: Blueprint routes will be prefixed with this.
580 :param subdomain: Blueprint routes will match on this subdomain.
581 :param url_defaults: Blueprint routes will use these default values for
582 view arguments.
583 :param options: Additional keyword arguments are passed to
584 :class:`~flask.blueprints.BlueprintSetupState`. They can be
585 accessed in :meth:`~flask.Blueprint.record` callbacks.
587 .. versionchanged:: 2.0.1
588 The ``name`` option can be used to change the (pre-dotted)
589 name the blueprint is registered with. This allows the same
590 blueprint to be registered multiple times with unique names
591 for ``url_for``.
593 .. versionadded:: 0.7
594 """
595 blueprint.register(self, options)
597 def iter_blueprints(self) -> t.ValuesView[Blueprint]:
598 """Iterates over all blueprints by the order they were registered.
600 .. versionadded:: 0.11
601 """
602 return self.blueprints.values()
604 @setupmethod
605 def add_url_rule(
606 self,
607 rule: str,
608 endpoint: str | None = None,
609 view_func: ft.RouteCallable | None = None,
610 provide_automatic_options: bool | None = None,
611 **options: t.Any,
612 ) -> None:
613 if endpoint is None:
614 endpoint = _endpoint_from_view_func(view_func) # type: ignore
615 options["endpoint"] = endpoint
616 methods = options.pop("methods", None)
618 # if the methods are not given and the view_func object knows its
619 # methods we can use that instead. If neither exists, we go with
620 # a tuple of only ``GET`` as default.
621 if methods is None:
622 methods = getattr(view_func, "methods", None) or ("GET",)
623 if isinstance(methods, str):
624 raise TypeError(
625 "Allowed methods must be a list of strings, for"
626 ' example: @app.route(..., methods=["POST"])'
627 )
628 methods = {item.upper() for item in methods}
630 # Methods that should always be added
631 required_methods = set(getattr(view_func, "required_methods", ()))
633 # starting with Flask 0.8 the view_func object can disable and
634 # force-enable the automatic options handling.
635 if provide_automatic_options is None:
636 provide_automatic_options = getattr(
637 view_func, "provide_automatic_options", None
638 )
640 if provide_automatic_options is None:
641 if "OPTIONS" not in methods:
642 provide_automatic_options = True
643 required_methods.add("OPTIONS")
644 else:
645 provide_automatic_options = False
647 # Add the required methods now.
648 methods |= required_methods
650 rule_obj = self.url_rule_class(rule, methods=methods, **options)
651 rule_obj.provide_automatic_options = provide_automatic_options # type: ignore[attr-defined]
653 self.url_map.add(rule_obj)
654 if view_func is not None:
655 old_func = self.view_functions.get(endpoint)
656 if old_func is not None and old_func != view_func:
657 raise AssertionError(
658 "View function mapping is overwriting an existing"
659 f" endpoint function: {endpoint}"
660 )
661 self.view_functions[endpoint] = view_func
663 @setupmethod
664 def template_filter(
665 self, name: str | None = None
666 ) -> t.Callable[[T_template_filter], T_template_filter]:
667 """A decorator that is used to register custom template filter.
668 You can specify a name for the filter, otherwise the function
669 name will be used. Example::
671 @app.template_filter()
672 def reverse(s):
673 return s[::-1]
675 :param name: the optional name of the filter, otherwise the
676 function name will be used.
677 """
679 def decorator(f: T_template_filter) -> T_template_filter:
680 self.add_template_filter(f, name=name)
681 return f
683 return decorator
685 @setupmethod
686 def add_template_filter(
687 self, f: ft.TemplateFilterCallable, name: str | None = None
688 ) -> None:
689 """Register a custom template filter. Works exactly like the
690 :meth:`template_filter` decorator.
692 :param name: the optional name of the filter, otherwise the
693 function name will be used.
694 """
695 self.jinja_env.filters[name or f.__name__] = f
697 @setupmethod
698 def template_test(
699 self, name: str | None = None
700 ) -> t.Callable[[T_template_test], T_template_test]:
701 """A decorator that is used to register custom template test.
702 You can specify a name for the test, otherwise the function
703 name will be used. Example::
705 @app.template_test()
706 def is_prime(n):
707 if n == 2:
708 return True
709 for i in range(2, int(math.ceil(math.sqrt(n))) + 1):
710 if n % i == 0:
711 return False
712 return True
714 .. versionadded:: 0.10
716 :param name: the optional name of the test, otherwise the
717 function name will be used.
718 """
720 def decorator(f: T_template_test) -> T_template_test:
721 self.add_template_test(f, name=name)
722 return f
724 return decorator
726 @setupmethod
727 def add_template_test(
728 self, f: ft.TemplateTestCallable, name: str | None = None
729 ) -> None:
730 """Register a custom template test. Works exactly like the
731 :meth:`template_test` decorator.
733 .. versionadded:: 0.10
735 :param name: the optional name of the test, otherwise the
736 function name will be used.
737 """
738 self.jinja_env.tests[name or f.__name__] = f
740 @setupmethod
741 def template_global(
742 self, name: str | None = None
743 ) -> t.Callable[[T_template_global], T_template_global]:
744 """A decorator that is used to register a custom template global function.
745 You can specify a name for the global function, otherwise the function
746 name will be used. Example::
748 @app.template_global()
749 def double(n):
750 return 2 * n
752 .. versionadded:: 0.10
754 :param name: the optional name of the global function, otherwise the
755 function name will be used.
756 """
758 def decorator(f: T_template_global) -> T_template_global:
759 self.add_template_global(f, name=name)
760 return f
762 return decorator
764 @setupmethod
765 def add_template_global(
766 self, f: ft.TemplateGlobalCallable, name: str | None = None
767 ) -> None:
768 """Register a custom template global function. Works exactly like the
769 :meth:`template_global` decorator.
771 .. versionadded:: 0.10
773 :param name: the optional name of the global function, otherwise the
774 function name will be used.
775 """
776 self.jinja_env.globals[name or f.__name__] = f
778 @setupmethod
779 def teardown_appcontext(self, f: T_teardown) -> T_teardown:
780 """Registers a function to be called when the application
781 context is popped. The application context is typically popped
782 after the request context for each request, at the end of CLI
783 commands, or after a manually pushed context ends.
785 .. code-block:: python
787 with app.app_context():
788 ...
790 When the ``with`` block exits (or ``ctx.pop()`` is called), the
791 teardown functions are called just before the app context is
792 made inactive. Since a request context typically also manages an
793 application context it would also be called when you pop a
794 request context.
796 When a teardown function was called because of an unhandled
797 exception it will be passed an error object. If an
798 :meth:`errorhandler` is registered, it will handle the exception
799 and the teardown will not receive it.
801 Teardown functions must avoid raising exceptions. If they
802 execute code that might fail they must surround that code with a
803 ``try``/``except`` block and log any errors.
805 The return values of teardown functions are ignored.
807 .. versionadded:: 0.9
808 """
809 self.teardown_appcontext_funcs.append(f)
810 return f
812 @setupmethod
813 def shell_context_processor(
814 self, f: T_shell_context_processor
815 ) -> T_shell_context_processor:
816 """Registers a shell context processor function.
818 .. versionadded:: 0.11
819 """
820 self.shell_context_processors.append(f)
821 return f
823 def _find_error_handler(
824 self, e: Exception, blueprints: list[str]
825 ) -> ft.ErrorHandlerCallable | None:
826 """Return a registered error handler for an exception in this order:
827 blueprint handler for a specific code, app handler for a specific code,
828 blueprint handler for an exception class, app handler for an exception
829 class, or ``None`` if a suitable handler is not found.
830 """
831 exc_class, code = self._get_exc_class_and_code(type(e))
832 names = (*blueprints, None)
834 for c in (code, None) if code is not None else (None,):
835 for name in names:
836 handler_map = self.error_handler_spec[name][c]
838 if not handler_map:
839 continue
841 for cls in exc_class.__mro__:
842 handler = handler_map.get(cls)
844 if handler is not None:
845 return handler
846 return None
848 def trap_http_exception(self, e: Exception) -> bool:
849 """Checks if an HTTP exception should be trapped or not. By default
850 this will return ``False`` for all exceptions except for a bad request
851 key error if ``TRAP_BAD_REQUEST_ERRORS`` is set to ``True``. It
852 also returns ``True`` if ``TRAP_HTTP_EXCEPTIONS`` is set to ``True``.
854 This is called for all HTTP exceptions raised by a view function.
855 If it returns ``True`` for any exception the error handler for this
856 exception is not called and it shows up as regular exception in the
857 traceback. This is helpful for debugging implicitly raised HTTP
858 exceptions.
860 .. versionchanged:: 1.0
861 Bad request errors are not trapped by default in debug mode.
863 .. versionadded:: 0.8
864 """
865 if self.config["TRAP_HTTP_EXCEPTIONS"]:
866 return True
868 trap_bad_request = self.config["TRAP_BAD_REQUEST_ERRORS"]
870 # if unset, trap key errors in debug mode
871 if (
872 trap_bad_request is None
873 and self.debug
874 and isinstance(e, BadRequestKeyError)
875 ):
876 return True
878 if trap_bad_request:
879 return isinstance(e, BadRequest)
881 return False
883 def should_ignore_error(self, error: BaseException | None) -> bool:
884 """This is called to figure out if an error should be ignored
885 or not as far as the teardown system is concerned. If this
886 function returns ``True`` then the teardown handlers will not be
887 passed the error.
889 .. versionadded:: 0.10
890 """
891 return False
893 def redirect(self, location: str, code: int = 302) -> BaseResponse:
894 """Create a redirect response object.
896 This is called by :func:`flask.redirect`, and can be called
897 directly as well.
899 :param location: The URL to redirect to.
900 :param code: The status code for the redirect.
902 .. versionadded:: 2.2
903 Moved from ``flask.redirect``, which calls this method.
904 """
905 return _wz_redirect(
906 location,
907 code=code,
908 Response=self.response_class, # type: ignore[arg-type]
909 )
911 def inject_url_defaults(self, endpoint: str, values: dict[str, t.Any]) -> None:
912 """Injects the URL defaults for the given endpoint directly into
913 the values dictionary passed. This is used internally and
914 automatically called on URL building.
916 .. versionadded:: 0.7
917 """
918 names: t.Iterable[str | None] = (None,)
920 # url_for may be called outside a request context, parse the
921 # passed endpoint instead of using request.blueprints.
922 if "." in endpoint:
923 names = chain(
924 names, reversed(_split_blueprint_path(endpoint.rpartition(".")[0]))
925 )
927 for name in names:
928 if name in self.url_default_functions:
929 for func in self.url_default_functions[name]:
930 func(endpoint, values)
932 def handle_url_build_error(
933 self, error: BuildError, endpoint: str, values: dict[str, t.Any]
934 ) -> str:
935 """Called by :meth:`.url_for` if a
936 :exc:`~werkzeug.routing.BuildError` was raised. If this returns
937 a value, it will be returned by ``url_for``, otherwise the error
938 will be re-raised.
940 Each function in :attr:`url_build_error_handlers` is called with
941 ``error``, ``endpoint`` and ``values``. If a function returns
942 ``None`` or raises a ``BuildError``, it is skipped. Otherwise,
943 its return value is returned by ``url_for``.
945 :param error: The active ``BuildError`` being handled.
946 :param endpoint: The endpoint being built.
947 :param values: The keyword arguments passed to ``url_for``.
948 """
949 for handler in self.url_build_error_handlers:
950 try:
951 rv = handler(error, endpoint, values)
952 except BuildError as e:
953 # make error available outside except block
954 error = e
955 else:
956 if rv is not None:
957 return rv
959 # Re-raise if called with an active exception, otherwise raise
960 # the passed in exception.
961 if error is sys.exc_info()[1]:
962 raise
964 raise error