Returned type is only `core.SchemaBase` under one very specific case.

Appears to have been there since at least 5.0.0

Should cover all valid combinations, including that only one of `if_true`, `if_false` may be `str`.

Required for an annotation in later commit, but the import complicated the diff

- `expr.Expression` -> `_expr_core.Expression` fixes the type appearing as `Any`
- `dict` -> `TypingDict[str, Any]` fixes the type appearing as `dict[Unknown, Unknown]`
- Generally, the hierarchy of `Union`'s is allowing reuse and trailing docstrings, which I think improves readability.

These will be used in `alt.condition` and related functions

Split out the `_PredicateType`/`_StatementType` parsing for reuse in `when-then-otherwise`.

Unsure if `expr` is still needed here as a side effect, but it is no longer needed internal to `api`.
Purely a conservative step.

Allows the distinct steps to be reused

See [arrow PR](apache/arrow#36996)

This operation was performed on every call, but was entirely static.

These need to be decoupled for the following cases:
- Only `if_true` provided
- multiple (`if_true`,`if_false`)
  - Ending of an `if_false`
  - Ending of an `if_true`

Also adds a placeholder `TypeError`.

Resolves:

> FAILED tests/utils/test_core.py::test_infer_encoding_types_with_condition - AssertionError: assert {'color': Col...  value: 2})} == {'color': Col...  value: 2})}

- Sufficient for solving [vega#3301](vega#3301)
- Still a work-in-progress

Will need updating with tests on `_Then`. Currently the wrapped `dict` should be a parseable input, but the rest of `altair` doesn't know what to do with `_Then` yet.

`list` fails on 3.8

vega#3427 (comment)

…python>=3.12.0`

Any objects using `__getattr__`, e.g. `Parameter` break on older versions [see PR](python/cpython#103034)

Within a recursive call, an `str` would always be checked for each case - despite the last always being false.

Somewhat duck-typing as `SchemaBase`.

Temporary solution while `when-then-otherwise` is not related to any other `altair` classes.

- Adds more specific return type for `_get_predicate_expr`
- Adds guard `_is_undefined`

- Removes the need for `**kwargs`, as only a single keyword is every checked
- Removes need for explanation comment
- Simplifies return type

- Wrap literals passed to `then`, `otherwise` in `alt.value`
  - opt-out as default
  - added overloads
- Wrap kwargs passed to `when` as `alt.datum.key == (value)`
- Accept multiple predicates in `when`, reducing all predicates as an `AND` reduction.
- Refactor to reduce code duplication
- Added some initial docs

…s from `__all__`

The `TypeVar` rule is broad, but covers common names like `T`, `S`, `R`, etc

…ce|pyright`

Experimental and will require some features in later commits to work reliably

…herwise` to expressions

Proof-of-concept only.

Used for passing some new tests

- Allows the option to parse strings as literals, skipping `parse_shorthand`.
- This behaviour is opt-out

Responding to @mattijn [comment](vega#3427 (comment))

Mostly test errors which are being checked

Deprecated since pandas 2.2.0, but CI uses version prior to new values introduction

- Provides static type checking instead of `Any`
- Alias name hints towards usage
- Alias doc gives further context, without requiring repeating & syncing wherever it is used

I'm happy with the content in the doc, hopefully this can be refined during review.

- It adapts parts of `alt.condition`, but not verbatim as there was a `# TODO: update the docstring`
- Contains links to other sources of inspo
- Deliberately avoided the word "condition" as much as possible
  -  `when`'s result can become a condition, but only after calling `result.then(...)`.
  - Stressing that `when` != `condition`

…altair into condition-multiple

Was only kept around in case some other code relied on it as a side-effect.
Have now confirmed that is not the case and is safe to remove.

Resolves vega#3427 (comment)

I believe `mypy` failed this on an earlier commit, but some uncommitted improvements to `Chart.Encode` have identified problems in `hexbins`, `select_detail` examples.

I'm planning to open another PR with that fix

Fixes 2/3 of vega@b85223f

Replaces the prior `mypy` error producing relative+implicit import logic with a single top-level, explicit import.
Amends some tests that were reliant on undocumented `alt.expr....` behaviour.

…is committed

- Fix inconsistent `&`/`AND` usage
- Fix url link endings
- Use specific directives instead of generic, where appropriate

- Use crossref directives
- Adds doc for `_When.then`

Possibly related to 95093d7

- This was quite a tricky merge

This was temporary se vega@55cc301

- utilise annotation scope/ `TYPE_CHECKING` is more places
- reduce the number of import aliases
-more robust handling of the `core.Dict`/`typing.Dict` special-case

Spotted some inconsistencies during testing that were corrected here

Resolves vega#3427 (comment)

This added complexity, and setting `seq_as_lit=False` doesn't make much sense from the perspective of the user

Utilises vega#3458

Resolves vega#3427 (comment)

```
tests\vegalite\v5\test_api.py:258: error: Item "None" of "dict[str, str | Expression | PredicateComposition | Any] | Any | None" has no attribute "pop"  [union-attr]
```

…tions

- Utilise `TypedDict.__extra_items__` https://peps.python.org/pep-0728/
- Use generics where knowledge of the internal structure was lacking
- Make `Then` a subclass of `SchemaBase`
- Introduce some informative errors for complex structural issues
- Update/add `@overload`s

Previously didn't inherit from `SchemaBase`

See astral-sh/ruff#12106

I've fixed to the new behaviour and disabled the rule

See vega#3427 (comment)

Not yet exposed as an option

- Suggested in vega#3427 (comment)
- New default is less likely to cause errors in spec
- See also vega#3427 (comment)

Some of these are less helpful now that annotation scope can be used

These are intended to show the desired solution for an example.
Therefore they should use the most concise syntax