feat: Support Chart.transform_filter(*predicates, **constraints)

altair/vegalite/v5/api.py

@@ -530,6 +530,18 @@ def check_fields_and_encodings(parameter: Parameter, field_name: str) -> bool:
 ]
 """Permitted types for `predicate`."""
 
+# FIXME: Remove before merging
+_OrigFilterType: TypeAlias = "str | Expr | Expression | Predicate | Parameter | PredicateComposition | dict[str, Predicate | str | list | bool]"
+"""**Temporary** alias for ``transform_filter``'s original annotation.
+
+Notes
+-----
+- Quite similar to ``_PredicateType``
+- Probably some redundant typing, that can be reduced
+    - ``Predicate`` derives ``PredicateComposition``
+        - Includes all ``(Logical|Field|Parameter)...Predicate``
+"""
+
 _ComposablePredicateType: TypeAlias = Union[
     _expr_core.OperatorMixin, SelectionPredicateComposition
 ]
@@ -2949,14 +2961,10 @@ def transform_extent(
     # # E.g. {'not': alt.FieldRangePredicate(field='year', range=[1950, 1960])}
     def transform_filter(
         self,
-        filter: str
-        | Expr
-        | Expression
-        | Predicate
-        | Parameter
-        | PredicateComposition
-        | dict[str, Predicate | str | list | bool],
-        **kwargs: Any,
+        predicate: Optional[_PredicateType] = Undefined,
+        *more_predicates: _ComposablePredicateType,
+        empty: Optional[bool] = Undefined,
+        **constraints: _FieldEqualType,
     ) -> Self:
         """
         Add a :class:`FilterTransform` to the schema.
@@ -2976,14 +2984,17 @@ def transform_filter(
         self : Chart object
             returns chart to allow for chaining
         """
-        if isinstance(filter, Parameter):
-            new_filter: dict[str, Any] = {"param": filter.name}
-            if "empty" in kwargs:
-                new_filter["empty"] = kwargs.pop("empty")
-            elif isinstance(filter.empty, bool):
-                new_filter["empty"] = filter.empty
-            filter = new_filter
-        return self._add_transform(core.FilterTransform(filter=filter, **kwargs))
+        if depr_filter := constraints.pop("filter", None):
+            utils.deprecated_warn(
+                "Passing `filter` as a keyword is ambiguous.\n\n"
+                "Use a positional argument for `<5.5.0` behavior.\n"
+                "Or, `alt.datum['filter'] == ...` if referring to a column named 'filter'.",
+                version="5.5.0",
+            )
+            more_predicates = *more_predicates, t.cast(Any, depr_filter)
+        cond = _parse_when(predicate, *more_predicates, empty=empty, **constraints)
+        pred = cond.get("test", cond)
+        return self._add_transform(core.FilterTransform(filter=pred))
 
     def transform_flatten(
         self,

tests/examples_arguments_syntax/line_chart_with_cumsum_faceted.py

@@ -12,7 +12,7 @@
 columns_sorted = ['Drought', 'Epidemic', 'Earthquake', 'Flood']
 
 alt.Chart(source).transform_filter(
-    {'and': [
+    {'and': [ # type: ignore[arg-type]
         alt.FieldOneOfPredicate(field='Entity', oneOf=columns_sorted), # Filter data to show only disasters in columns_sorted
         alt.FieldRangePredicate(field='Year', range=[1900, 2000]) # Filter data to show only 20th century
     ]}

tests/examples_methods_syntax/line_chart_with_cumsum_faceted.py

@@ -12,7 +12,7 @@
 columns_sorted = ['Drought', 'Epidemic', 'Earthquake', 'Flood']
 
 alt.Chart(source).transform_filter(
-    {'and': [
+    {'and': [ # type: ignore[arg-type]
         alt.FieldOneOfPredicate(field='Entity', oneOf=columns_sorted), # Filter data to show only disasters in columns_sorted
         alt.FieldRangePredicate(field='Year', range=[1900, 2000]) # Filter data to show only 20th century
     ]}