views.py 6.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191
  1. from __future__ import annotations
  2. import typing as t
  3. from . import typing as ft
  4. from .globals import current_app
  5. from .globals import request
  6. F = t.TypeVar("F", bound=t.Callable[..., t.Any])
  7. http_method_funcs = frozenset(
  8. ["get", "post", "head", "options", "delete", "put", "trace", "patch"]
  9. )
  10. class View:
  11. """Subclass this class and override :meth:`dispatch_request` to
  12. create a generic class-based view. Call :meth:`as_view` to create a
  13. view function that creates an instance of the class with the given
  14. arguments and calls its ``dispatch_request`` method with any URL
  15. variables.
  16. See :doc:`views` for a detailed guide.
  17. .. code-block:: python
  18. class Hello(View):
  19. init_every_request = False
  20. def dispatch_request(self, name):
  21. return f"Hello, {name}!"
  22. app.add_url_rule(
  23. "/hello/<name>", view_func=Hello.as_view("hello")
  24. )
  25. Set :attr:`methods` on the class to change what methods the view
  26. accepts.
  27. Set :attr:`decorators` on the class to apply a list of decorators to
  28. the generated view function. Decorators applied to the class itself
  29. will not be applied to the generated view function!
  30. Set :attr:`init_every_request` to ``False`` for efficiency, unless
  31. you need to store request-global data on ``self``.
  32. """
  33. #: The methods this view is registered for. Uses the same default
  34. #: (``["GET", "HEAD", "OPTIONS"]``) as ``route`` and
  35. #: ``add_url_rule`` by default.
  36. methods: t.ClassVar[t.Collection[str] | None] = None
  37. #: Control whether the ``OPTIONS`` method is handled automatically.
  38. #: Uses the same default (``True``) as ``route`` and
  39. #: ``add_url_rule`` by default.
  40. provide_automatic_options: t.ClassVar[bool | None] = None
  41. #: A list of decorators to apply, in order, to the generated view
  42. #: function. Remember that ``@decorator`` syntax is applied bottom
  43. #: to top, so the first decorator in the list would be the bottom
  44. #: decorator.
  45. #:
  46. #: .. versionadded:: 0.8
  47. decorators: t.ClassVar[list[t.Callable[..., t.Any]]] = []
  48. #: Create a new instance of this view class for every request by
  49. #: default. If a view subclass sets this to ``False``, the same
  50. #: instance is used for every request.
  51. #:
  52. #: A single instance is more efficient, especially if complex setup
  53. #: is done during init. However, storing data on ``self`` is no
  54. #: longer safe across requests, and :data:`~flask.g` should be used
  55. #: instead.
  56. #:
  57. #: .. versionadded:: 2.2
  58. init_every_request: t.ClassVar[bool] = True
  59. def dispatch_request(self) -> ft.ResponseReturnValue:
  60. """The actual view function behavior. Subclasses must override
  61. this and return a valid response. Any variables from the URL
  62. rule are passed as keyword arguments.
  63. """
  64. raise NotImplementedError()
  65. @classmethod
  66. def as_view(
  67. cls, name: str, *class_args: t.Any, **class_kwargs: t.Any
  68. ) -> ft.RouteCallable:
  69. """Convert the class into a view function that can be registered
  70. for a route.
  71. By default, the generated view will create a new instance of the
  72. view class for every request and call its
  73. :meth:`dispatch_request` method. If the view class sets
  74. :attr:`init_every_request` to ``False``, the same instance will
  75. be used for every request.
  76. Except for ``name``, all other arguments passed to this method
  77. are forwarded to the view class ``__init__`` method.
  78. .. versionchanged:: 2.2
  79. Added the ``init_every_request`` class attribute.
  80. """
  81. if cls.init_every_request:
  82. def view(**kwargs: t.Any) -> ft.ResponseReturnValue:
  83. self = view.view_class( # type: ignore[attr-defined]
  84. *class_args, **class_kwargs
  85. )
  86. return current_app.ensure_sync(self.dispatch_request)(**kwargs) # type: ignore[no-any-return]
  87. else:
  88. self = cls(*class_args, **class_kwargs) # pyright: ignore
  89. def view(**kwargs: t.Any) -> ft.ResponseReturnValue:
  90. return current_app.ensure_sync(self.dispatch_request)(**kwargs) # type: ignore[no-any-return]
  91. if cls.decorators:
  92. view.__name__ = name
  93. view.__module__ = cls.__module__
  94. for decorator in cls.decorators:
  95. view = decorator(view)
  96. # We attach the view class to the view function for two reasons:
  97. # first of all it allows us to easily figure out what class-based
  98. # view this thing came from, secondly it's also used for instantiating
  99. # the view class so you can actually replace it with something else
  100. # for testing purposes and debugging.
  101. view.view_class = cls # type: ignore
  102. view.__name__ = name
  103. view.__doc__ = cls.__doc__
  104. view.__module__ = cls.__module__
  105. view.methods = cls.methods # type: ignore
  106. view.provide_automatic_options = cls.provide_automatic_options # type: ignore
  107. return view
  108. class MethodView(View):
  109. """Dispatches request methods to the corresponding instance methods.
  110. For example, if you implement a ``get`` method, it will be used to
  111. handle ``GET`` requests.
  112. This can be useful for defining a REST API.
  113. :attr:`methods` is automatically set based on the methods defined on
  114. the class.
  115. See :doc:`views` for a detailed guide.
  116. .. code-block:: python
  117. class CounterAPI(MethodView):
  118. def get(self):
  119. return str(session.get("counter", 0))
  120. def post(self):
  121. session["counter"] = session.get("counter", 0) + 1
  122. return redirect(url_for("counter"))
  123. app.add_url_rule(
  124. "/counter", view_func=CounterAPI.as_view("counter")
  125. )
  126. """
  127. def __init_subclass__(cls, **kwargs: t.Any) -> None:
  128. super().__init_subclass__(**kwargs)
  129. if "methods" not in cls.__dict__:
  130. methods = set()
  131. for base in cls.__bases__:
  132. if getattr(base, "methods", None):
  133. methods.update(base.methods) # type: ignore[attr-defined]
  134. for key in http_method_funcs:
  135. if hasattr(cls, key):
  136. methods.add(key.upper())
  137. if methods:
  138. cls.methods = methods
  139. def dispatch_request(self, **kwargs: t.Any) -> ft.ResponseReturnValue:
  140. meth = getattr(self, request.method.lower(), None)
  141. # If the request method is HEAD and we don't have a handler for it
  142. # retry with GET.
  143. if meth is None and request.method == "HEAD":
  144. meth = getattr(self, "get", None)
  145. assert meth is not None, f"Unimplemented method {request.method!r}"
  146. return current_app.ensure_sync(meth)(**kwargs) # type: ignore[no-any-return]