Merge 0abda4d277 into 284273e3c5

CHANGES.rst

@@ -5,6 +5,7 @@ Unreleased
 
 -   Drop support for Python 3.9. :pr:`5730`
 -   Remove previously deprecated code: ``__version__``. :pr:`5648`
+-   Support for using @app.template_filter, @app.template_test, and @app.template_global decorators without parentheses. :pr:`5736`
 
 
 Version 3.1.1

docs/_static/flask-icon.svg

@@ -1 +1,13 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg width="100%" height="100%" viewBox="0 0 1000 1000" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;"><g><path d="M448.955,119.915c-0.579,59.76 13.398,192.715 18.542,238.988l-356.626,159.589c-23.367,-39.985 -40.836,-96.035 -51.551,-140.858l-2.503,1.065c-8.573,3.718 -16.932,2.18 -20.609,-3.664l-0.456,-0.734l-34.175,-62.778c-2.402,-4.381 -2.054,-10.547 1.006,-16.32c3.06,-5.777 8.827,-11.157 14.901,-13.815l409.395,-175.316c6.074,-2.657 12.451,-2.59 16.655,0.176c4.44,2.587 5.304,5.387 5.421,13.667Z" style="fill:#3babc3;fill-rule:nonzero;"/><path d="M477.297,411.517l-343.415,153.677c20.185,38.246 45.103,78.851 75.476,118.011l302.647,-154.214c-6.532,-16.924 -12.929,-35.311 -34.708,-117.474Z" style="fill:#3babc3;fill-rule:nonzero;"/><path d="M243.67,724.046l289.522,-147.543c30.054,59.626 66.144,102.294 104.553,132.415c86.929,68.257 183.958,71.364 241.412,65.146l-1.966,-9.7c-0.612,-3.136 0.28,-5.597 3.584,-6.859l30.59,-11.989c5.211,-2.017 10.611,-0.495 14.279,3.584l31.177,-12.015c4.981,-2.008 10.611,-0.494 14.233,3.564l24.268,37.075c11.806,16.723 -1.924,27.342 -6.368,29.035l-39.431,15.407c1.542,5.232 1.471,13.31 -9.022,17.288l-30.636,11.969c-9.584,3.739 -16.61,-2.411 -17.524,-8.292l-0.998,-5.224c-184.485,74.282 -330.818,70.194 -445.692,26.944c-82.561,-31.081 -149.05,-82.639 -201.981,-140.805Z" style="fill:#3babc3;fill-rule:nonzero;"/></g></svg>
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg width="100%" height="100%" viewBox="0 0 500 500" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:2;">
+    <rect id="Icon" x="0" y="0" width="500" height="500" style="fill:none;"/>
+    <clipPath id="_clip1">
+        <rect x="0" y="0" width="500" height="500"/>
+    </clipPath>
+    <g clip-path="url(#_clip1)">
+        <path d="M224.446,59.975c-0.056,-4.151 -0.483,-5.543 -2.7,-6.823c-2.104,-1.393 -5.288,-1.421 -8.329,-0.085l-204.674,87.64c-3.042,1.336 -5.913,4.008 -7.448,6.908c-1.535,2.899 -1.705,5.97 -0.511,8.158l17.084,31.384l0.228,0.369c1.847,2.928 6.026,3.696 10.29,1.82l1.251,-0.54c5.344,22.4 14.1,50.429 25.783,70.413l178.294,-79.794c-2.559,-23.14 -9.552,-89.602 -9.268,-119.479l0,0.029Z" style="fill:#3babc3;fill-rule:nonzero;"/>
+        <path d="M238.603,205.776l-171.698,76.838c10.091,19.132 22.542,39.428 37.722,58.986c50.429,-25.698 100.887,-51.396 151.316,-77.094c-3.269,-8.471 -6.452,-17.653 -17.34,-58.73Z" style="fill:#3babc3;fill-rule:nonzero;"/>
+        <path d="M497.601,388.846l-12.139,-18.535c-1.819,-2.018 -4.633,-2.786 -7.106,-1.791l-15.578,5.999c-1.848,-2.047 -4.52,-2.815 -7.135,-1.791c-5.089,1.99 -10.206,4.008 -15.294,5.998c-1.649,0.625 -2.104,1.847 -1.791,3.439l0.995,4.861c-28.711,3.099 -77.236,1.564 -120.701,-32.577c-19.216,-15.066 -37.239,-36.386 -52.277,-66.206l-144.75,73.768c26.466,29.08 59.697,54.864 100.973,70.385c57.422,21.633 130.593,23.679 222.838,-13.475l0.512,2.616c0.455,2.928 3.98,6.026 8.755,4.15l15.323,-5.97c5.258,-1.99 5.287,-6.026 4.519,-8.641l19.729,-7.704c2.217,-0.853 9.096,-6.169 3.183,-14.526l-0.056,-0Z" style="fill:#3babc3;fill-rule:nonzero;"/>
+    </g>
+</svg>

docs/templating.rst

@@ -145,7 +145,11 @@ that.  You can either put them by hand into the
 :attr:`~flask.Flask.jinja_env` of the application or use the
 :meth:`~flask.Flask.template_filter` decorator.
 
-The two following examples work the same and both reverse an object::
+The following examples work the same and all reverse an object::
+
+    @app.template_filter # use the function name as filter name
+    def reverse_filter(s):
+        return s[::-1]
 
     @app.template_filter('reverse')
     def reverse_filter(s):

src/flask/sansio/app.py

@@ -662,20 +662,36 @@ class App(Scaffold):
 
     @setupmethod
     def template_filter(
-        self, name: str | None = None
-    ) -> t.Callable[[T_template_filter], T_template_filter]:
+        self, name: t.Callable[..., t.Any] | str | None = None
+    ) -> t.Callable[[T_template_filter], T_template_filter] | T_template_filter:
         """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::
 
-          @app.template_filter()
-          def reverse(s):
-              return s[::-1]
+            @app.template_filter()
+            def reverse(s):
+                return s[::-1]
+
+        The decorator also can be used without parentheses::
+
+            @app.template_filter
+            def reverse(s):
+                return s[::-1]
 
         :param name: the optional name of the filter, otherwise the
                      function name will be used.
         """
 
+        if callable(name):
+            # If name is callable, it is the function to register.
+            # This is a shortcut for the common case of
+            # @app.template_filter
+            # def func():
+
+            func = name
+            self.add_template_filter(func)
+            return func
+
         def decorator(f: T_template_filter) -> T_template_filter:
             self.add_template_filter(f, name=name)
             return f
@@ -696,27 +712,47 @@ class App(Scaffold):
 
     @setupmethod
     def template_test(
-        self, name: str | None = None
-    ) -> t.Callable[[T_template_test], T_template_test]:
+        self, name: t.Callable[..., t.Any] | str | None = None
+    ) -> t.Callable[[T_template_test], T_template_test] | T_template_filter:
         """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::
 
-          @app.template_test()
-          def is_prime(n):
-              if n == 2:
-                  return True
-              for i in range(2, int(math.ceil(math.sqrt(n))) + 1):
-                  if n % i == 0:
-                      return False
+            @app.template_test()
+            def is_prime(n):
+                if n == 2:
+                    return True
+                for i in range(2, int(math.ceil(math.sqrt(n))) + 1):
+                    if n % i == 0:
+                        return False
               return True
 
+        The decorator also can be used without parentheses::
+
+            @app.template_test
+            def is_prime(n):
+                if n == 2:
+                    return True
+                for i in range(2, int(math.ceil(math.sqrt(n))) + 1):
+                    if n % i == 0:
+                        return False
+
         .. versionadded:: 0.10
 
         :param name: the optional name of the test, otherwise the
                      function name will be used.
         """
 
+        if callable(name):
+            # If name is callable, it is the function to register.
+            # This is a shortcut for the common case of
+            # @app.template_test
+            # def func():
+
+            func = name
+            self.add_template_test(func)
+            return func
+
         def decorator(f: T_template_test) -> T_template_test:
             self.add_template_test(f, name=name)
             return f
@@ -739,8 +775,8 @@ class App(Scaffold):
 
     @setupmethod
     def template_global(
-        self, name: str | None = None
-    ) -> t.Callable[[T_template_global], T_template_global]:
+        self, name: t.Callable[..., t.Any] | str | None = None
+    ) -> t.Callable[[T_template_global], T_template_global] | T_template_filter:
         """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::
@@ -749,12 +785,28 @@ class App(Scaffold):
             def double(n):
                 return 2 * n
 
+        The decorator also can be used without parentheses::
+
+            @app.template_global
+            def double(n):
+                return 2 * n
+
         .. versionadded:: 0.10
 
         :param name: the optional name of the global function, otherwise the
                      function name will be used.
         """
 
+        if callable(name):
+            # If name is callable, it is the function to register.
+            # This is a shortcut for the common case of
+            # @app.template_global
+            # def func():
+
+            func = name
+            self.add_template_global(func)
+            return func
+
         def decorator(f: T_template_global) -> T_template_global:
             self.add_template_global(f, name=name)
             return f

src/flask/sansio/blueprints.py

@@ -442,8 +442,8 @@ class Blueprint(Scaffold):
 
     @setupmethod
     def app_template_filter(
-        self, name: str | None = None
-    ) -> t.Callable[[T_template_filter], T_template_filter]:
+        self, name: t.Callable[..., t.Any] | str | None = None
+    ) -> t.Callable[[T_template_filter], T_template_filter] | T_template_filter:
         """Register a template filter, available in any template rendered by the
         application. Equivalent to :meth:`.Flask.template_filter`.
 
@@ -451,6 +451,16 @@ class Blueprint(Scaffold):
                      function name will be used.
         """
 
+        if callable(name):
+            # If name is callable, it is the function to register.
+            # This is a shortcut for the common case of
+            # @bp.add_template_filter
+            # def func():
+
+            func = name
+            self.add_app_template_filter(func)
+            return func
+
         def decorator(f: T_template_filter) -> T_template_filter:
             self.add_app_template_filter(f, name=name)
             return f
@@ -476,8 +486,8 @@ class Blueprint(Scaffold):
 
     @setupmethod
     def app_template_test(
-        self, name: str | None = None
-    ) -> t.Callable[[T_template_test], T_template_test]:
+        self, name: t.Callable[..., t.Any] | str | None = None
+    ) -> t.Callable[[T_template_test], T_template_test] | T_template_filter:
         """Register a template test, available in any template rendered by the
         application. Equivalent to :meth:`.Flask.template_test`.
 
@@ -487,6 +497,16 @@ class Blueprint(Scaffold):
                      function name will be used.
         """
 
+        if callable(name):
+            # If name is callable, it is the function to register.
+            # This is a shortcut for the common case of
+            # @bp.add_template_test
+            # def func():
+
+            func = name
+            self.add_app_template_test(func)
+            return func
+
         def decorator(f: T_template_test) -> T_template_test:
             self.add_app_template_test(f, name=name)
             return f
@@ -514,8 +534,8 @@ class Blueprint(Scaffold):
 
     @setupmethod
     def app_template_global(
-        self, name: str | None = None
-    ) -> t.Callable[[T_template_global], T_template_global]:
+        self, name: t.Callable[..., t.Any] | str | None = None
+    ) -> t.Callable[[T_template_global], T_template_global] | T_template_filter:
         """Register a template global, available in any template rendered by the
         application. Equivalent to :meth:`.Flask.template_global`.
 
@@ -524,6 +544,15 @@ class Blueprint(Scaffold):
         :param name: the optional name of the global, otherwise the
                      function name will be used.
         """
+        if callable(name):
+            # If name is callable, it is the function to register.
+            # This is a shortcut for the common case of
+            # @bp.add_template_global
+            # def func():
+
+            func = name
+            self.add_app_template_global(func)
+            return func
 
         def decorator(f: T_template_global) -> T_template_global:
             self.add_app_template_global(f, name=name)

tests/test_blueprints.py

@@ -366,11 +366,35 @@ def test_template_filter(app):
     def my_reverse(s):
         return s[::-1]
 
+    @bp.app_template_filter
+    def my_reverse_2(s):
+        return s[::-1]
+
+    @bp.app_template_filter("my_reverse_custom_name_3")
+    def my_reverse_3(s):
+        return s[::-1]
+
+    @bp.app_template_filter(name="my_reverse_custom_name_4")
+    def my_reverse_4(s):
+        return s[::-1]
+
     app.register_blueprint(bp, url_prefix="/py")
     assert "my_reverse" in app.jinja_env.filters.keys()
     assert app.jinja_env.filters["my_reverse"] == my_reverse
     assert app.jinja_env.filters["my_reverse"]("abcd") == "dcba"
 
+    assert "my_reverse_2" in app.jinja_env.filters.keys()
+    assert app.jinja_env.filters["my_reverse_2"] == my_reverse_2
+    assert app.jinja_env.filters["my_reverse_2"]("abcd") == "dcba"
+
+    assert "my_reverse_custom_name_3" in app.jinja_env.filters.keys()
+    assert app.jinja_env.filters["my_reverse_custom_name_3"] == my_reverse_3
+    assert app.jinja_env.filters["my_reverse_custom_name_3"]("abcd") == "dcba"
+
+    assert "my_reverse_custom_name_4" in app.jinja_env.filters.keys()
+    assert app.jinja_env.filters["my_reverse_custom_name_4"] == my_reverse_4
+    assert app.jinja_env.filters["my_reverse_custom_name_4"]("abcd") == "dcba"
+
 
 def test_add_template_filter(app):
     bp = flask.Blueprint("bp", __name__)
@@ -502,11 +526,35 @@ def test_template_test(app):
     def is_boolean(value):
         return isinstance(value, bool)
 
+    @bp.app_template_test
+    def boolean_2(value):
+        return isinstance(value, bool)
+
+    @bp.app_template_test("my_boolean_custom_name")
+    def boolean_3(value):
+        return isinstance(value, bool)
+
+    @bp.app_template_test(name="my_boolean_custom_name_2")
+    def boolean_4(value):
+        return isinstance(value, bool)
+
     app.register_blueprint(bp, url_prefix="/py")
     assert "is_boolean" in app.jinja_env.tests.keys()
     assert app.jinja_env.tests["is_boolean"] == is_boolean
     assert app.jinja_env.tests["is_boolean"](False)
 
+    assert "boolean_2" in app.jinja_env.tests.keys()
+    assert app.jinja_env.tests["boolean_2"] == boolean_2
+    assert app.jinja_env.tests["boolean_2"](False)
+
+    assert "my_boolean_custom_name" in app.jinja_env.tests.keys()
+    assert app.jinja_env.tests["my_boolean_custom_name"] == boolean_3
+    assert app.jinja_env.tests["my_boolean_custom_name"](False)
+
+    assert "my_boolean_custom_name_2" in app.jinja_env.tests.keys()
+    assert app.jinja_env.tests["my_boolean_custom_name_2"] == boolean_4
+    assert app.jinja_env.tests["my_boolean_custom_name_2"](False)
+
 
 def test_add_template_test(app):
     bp = flask.Blueprint("bp", __name__)
@@ -679,6 +727,18 @@ def test_template_global(app):
     def get_answer():
         return 42
 
+    @bp.app_template_global
+    def get_stuff_1():
+        return "get_stuff_1"
+
+    @bp.app_template_global("my_get_stuff_custom_name_2")
+    def get_stuff_2():
+        return "get_stuff_2"
+
+    @bp.app_template_global(name="my_get_stuff_custom_name_3")
+    def get_stuff_3():
+        return "get_stuff_3"
+
     # Make sure the function is not in the jinja_env already
     assert "get_answer" not in app.jinja_env.globals.keys()
     app.register_blueprint(bp)
@@ -688,10 +748,31 @@ def test_template_global(app):
     assert app.jinja_env.globals["get_answer"] is get_answer
     assert app.jinja_env.globals["get_answer"]() == 42
 
+    assert "get_stuff_1" in app.jinja_env.globals.keys()
+    assert app.jinja_env.globals["get_stuff_1"] == get_stuff_1
+    assert app.jinja_env.globals["get_stuff_1"](), "get_stuff_1"
+
+    assert "my_get_stuff_custom_name_2" in app.jinja_env.globals.keys()
+    assert app.jinja_env.globals["my_get_stuff_custom_name_2"] == get_stuff_2
+    assert app.jinja_env.globals["my_get_stuff_custom_name_2"](), "get_stuff_2"
+
+    assert "my_get_stuff_custom_name_3" in app.jinja_env.globals.keys()
+    assert app.jinja_env.globals["my_get_stuff_custom_name_3"] == get_stuff_3
+    assert app.jinja_env.globals["my_get_stuff_custom_name_3"](), "get_stuff_3"
+
     with app.app_context():
         rv = flask.render_template_string("{{ get_answer() }}")
         assert rv == "42"
 
+        rv = flask.render_template_string("{{ get_stuff_1() }}")
+        assert rv == "get_stuff_1"
+
+        rv = flask.render_template_string("{{ my_get_stuff_custom_name_2() }}")
+        assert rv == "get_stuff_2"
+
+        rv = flask.render_template_string("{{ my_get_stuff_custom_name_3() }}")
+        assert rv == "get_stuff_3"
+
 
 def test_request_processing(app, client):
     bp = flask.Blueprint("bp", __name__)

tests/test_templating.py

@@ -129,6 +129,30 @@ def test_template_filter(app):
     assert app.jinja_env.filters["my_reverse"] == my_reverse
     assert app.jinja_env.filters["my_reverse"]("abcd") == "dcba"
 
+    @app.template_filter
+    def my_reverse_2(s):
+        return s[::-1]
+
+    assert "my_reverse_2" in app.jinja_env.filters.keys()
+    assert app.jinja_env.filters["my_reverse_2"] == my_reverse_2
+    assert app.jinja_env.filters["my_reverse_2"]("abcd") == "dcba"
+
+    @app.template_filter("my_reverse_custom_name_3")
+    def my_reverse_3(s):
+        return s[::-1]
+
+    assert "my_reverse_custom_name_3" in app.jinja_env.filters.keys()
+    assert app.jinja_env.filters["my_reverse_custom_name_3"] == my_reverse_3
+    assert app.jinja_env.filters["my_reverse_custom_name_3"]("abcd") == "dcba"
+
+    @app.template_filter(name="my_reverse_custom_name_4")
+    def my_reverse_4(s):
+        return s[::-1]
+
+    assert "my_reverse_custom_name_4" in app.jinja_env.filters.keys()
+    assert app.jinja_env.filters["my_reverse_custom_name_4"] == my_reverse_4
+    assert app.jinja_env.filters["my_reverse_custom_name_4"]("abcd") == "dcba"
+
 
 def test_add_template_filter(app):
     def my_reverse(s):
@@ -223,6 +247,30 @@ def test_template_test(app):
     assert app.jinja_env.tests["boolean"] == boolean
     assert app.jinja_env.tests["boolean"](False)
 
+    @app.template_test
+    def boolean_2(value):
+        return isinstance(value, bool)
+
+    assert "boolean_2" in app.jinja_env.tests.keys()
+    assert app.jinja_env.tests["boolean_2"] == boolean_2
+    assert app.jinja_env.tests["boolean_2"](False)
+
+    @app.template_test("my_boolean_custom_name")
+    def boolean_3(value):
+        return isinstance(value, bool)
+
+    assert "my_boolean_custom_name" in app.jinja_env.tests.keys()
+    assert app.jinja_env.tests["my_boolean_custom_name"] == boolean_3
+    assert app.jinja_env.tests["my_boolean_custom_name"](False)
+
+    @app.template_test(name="my_boolean_custom_name_2")
+    def boolean_4(value):
+        return isinstance(value, bool)
+
+    assert "my_boolean_custom_name_2" in app.jinja_env.tests.keys()
+    assert app.jinja_env.tests["my_boolean_custom_name_2"] == boolean_4
+    assert app.jinja_env.tests["my_boolean_custom_name_2"](False)
+
 
 def test_add_template_test(app):
     def boolean(value):
@@ -320,6 +368,39 @@ def test_add_template_global(app, app_ctx):
     rv = flask.render_template_string("{{ get_stuff() }}")
     assert rv == "42"
 
+    @app.template_global
+    def get_stuff_1():
+        return "get_stuff_1"
+
+    assert "get_stuff_1" in app.jinja_env.globals.keys()
+    assert app.jinja_env.globals["get_stuff_1"] == get_stuff_1
+    assert app.jinja_env.globals["get_stuff_1"](), "get_stuff_1"
+
+    rv = flask.render_template_string("{{ get_stuff_1() }}")
+    assert rv == "get_stuff_1"
+
+    @app.template_global("my_get_stuff_custom_name_2")
+    def get_stuff_2():
+        return "get_stuff_2"
+
+    assert "my_get_stuff_custom_name_2" in app.jinja_env.globals.keys()
+    assert app.jinja_env.globals["my_get_stuff_custom_name_2"] == get_stuff_2
+    assert app.jinja_env.globals["my_get_stuff_custom_name_2"](), "get_stuff_2"
+
+    rv = flask.render_template_string("{{ my_get_stuff_custom_name_2() }}")
+    assert rv == "get_stuff_2"
+
+    @app.template_global(name="my_get_stuff_custom_name_3")
+    def get_stuff_3():
+        return "get_stuff_3"
+
+    assert "my_get_stuff_custom_name_3" in app.jinja_env.globals.keys()
+    assert app.jinja_env.globals["my_get_stuff_custom_name_3"] == get_stuff_3
+    assert app.jinja_env.globals["my_get_stuff_custom_name_3"](), "get_stuff_3"
+
+    rv = flask.render_template_string("{{ my_get_stuff_custom_name_3() }}")
+    assert rv == "get_stuff_3"
+
 
 def test_custom_template_loader(client):
     class MyFlask(flask.Flask):