Replace **flags with explicit kwargs on Library.filter (#3360)

is_safe, needs_autoescape, and expects_localtime are the only flags
Django's Library.filter consumes, so type them explicitly.

Author: federicobond

django-stubs/template/library.pyi

@@ -24,11 +24,35 @@ class Library:
     def tag(self, name: str | None = None, compile_function: None = None) -> Callable[[_C], _C]: ...
     def tag_function(self, func: _C) -> _C: ...
     @overload
-    def filter(self, name: _C, filter_func: None = None, **flags: Any) -> _C: ...
+    def filter(
+        self,
+        name: _C,
+        filter_func: None = None,
+        *,
+        is_safe: bool = False,
+        needs_autoescape: bool = False,
+        expects_localtime: bool = False,
+    ) -> _C: ...
     @overload
-    def filter(self, name: str | None, filter_func: _C, **flags: Any) -> _C: ...
+    def filter(
+        self,
+        name: str | None,
+        filter_func: _C,
+        *,
+        is_safe: bool = False,
+        needs_autoescape: bool = False,
+        expects_localtime: bool = False,
+    ) -> _C: ...
     @overload
-    def filter(self, name: str | None = None, filter_func: None = None, **flags: Any) -> Callable[[_C], _C]: ...
+    def filter(
+        self,
+        name: str | None = None,
+        filter_func: None = None,
+        *,
+        is_safe: bool = False,
+        needs_autoescape: bool = False,
+        expects_localtime: bool = False,
+    ) -> Callable[[_C], _C]: ...
     def filter_function(self, func: _C, **flags: Any) -> _C: ...
     @overload
     def simple_tag(self, func: _C, takes_context: bool | None = None, name: str | None = None) -> _C: ...

tests/assert_type/template/test_library.py

@@ -29,6 +29,24 @@ def lower2(value: str) -> str:
 assert_type(lower2("test"), str)
 
 
+# register.filter with all flags
+@register.filter(name="plain", is_safe=True, needs_autoescape=False, expects_localtime=False)
+def plain_filter(value: str) -> str:
+    return value
+
+
+assert_type(plain_filter("x"), str)
+
+
+# Negative: non-bool values for flag kwargs are rejected
+register.filter("bad_is_safe", is_safe="yes")  # type: ignore[call-overload]  # pyright: ignore[reportCallIssue,reportArgumentType]  # pyrefly: ignore[no-matching-overload]  # ty: ignore[no-matching-overload]
+register.filter("bad_needs_autoescape", needs_autoescape="no")  # type: ignore[call-overload]  # pyright: ignore[reportCallIssue,reportArgumentType]  # pyrefly: ignore[no-matching-overload]  # ty: ignore[no-matching-overload]
+register.filter("bad_expects_localtime", expects_localtime=None)  # type: ignore[call-overload]  # pyright: ignore[reportCallIssue,reportArgumentType]  # pyrefly: ignore[no-matching-overload]  # ty: ignore[no-matching-overload]
+
+# Negative: unknown kwargs are rejected
+register.filter("unknown_flag", safe=True)  # type: ignore[call-overload]  # pyright: ignore[reportCallIssue]  # pyrefly: ignore[no-matching-overload]  # ty: ignore[no-matching-overload]
+
+
 # register.simple_tag (bare)
 @register.simple_tag
 def current_time(format_string: str) -> str: