feat: Support &, |, ~ on all ...Predicate classes

[dangotbanned]

Resolves #695

Description

This PR enables the use of logical composition operators (&, |, ~) directly on all 12 of:

...Predicate classes

• core.FieldEqualPredicate
• core.FieldGTEPredicate
• core.FieldGTPredicate
• core.FieldLTEPredicate
• core.FieldLTPredicate
• core.FieldOneOfPredicate
• core.FieldRangePredicate
• core.FieldValidPredicate
• core.LogicalAndPredicate
• core.LogicalOrPredicate
• core.LogicalNotPredicate
• core.ParameterPredicate

It appears this functionality has been desired for some time, but never implemented fully.

api.SelectionPredicateComposition already contained the code required to get this working - this PR moves that to core.PredicateComposition.

The change is fully backwards compatible, turning the old class into an alias (1dc15b7)

This also provides a cleaner solution to (#3664 (comment)) - than any of the alternatives documented there

Example

import altair as alt
from vega_datasets import data

source = data.disasters()
columns_sorted = ["Drought", "Epidemic", "Earthquake", "Flood"]

base = (
    alt.Chart(source, height=200)
    .mark_line(interpolate="monotone")
    .encode(
        x=alt.X("Year:Q").axis(format="d"),
        color="Entity",
        column="Entity",
        y="sum(Deaths)",
    )
)

chart_old = base.transform_filter(
    {
        "and": [
            alt.FieldOneOfPredicate(field="Entity", oneOf=columns_sorted),
            alt.FieldRangePredicate(field="Year", range=[1900, 2000]),
        ]
    }
)

chart_new = base.transform_filter(
    alt.FieldOneOfPredicate(field="Entity", oneOf=columns_sorted)
    & alt.FieldRangePredicate(field="Year", range=[1900, 2000])
)
chart_old & chart_new

Output

User Guide

Tasks

• Core implementation & tests (commits)
• Update User Guide- Logical Operands (commit)

Other Future Work

• I mentioned in (c1d05ec) that something similar could be done for expr.core.Expression -> core.Expr
  • possibly as part of Improve (Expression|expr|Expr|ExprRef) UX & ergonomics #3616
• feat(RFC): Adds agg, field utility classes #3505
  • That PR features similar functionality via _wrap_composition
  • This PR can therefore simplify the implementation there, removing the need for that extra step entirely

Related

• feat: Support Chart.transform_filter(*predicates, **constraints) #3664
• docs: Promote when-then-otherwise in User Guide #3544 (comment)
• https://altair-viz.github.io/user_guide/transform/filter.html#logical-operands