fix(typing): Improve Then annotations, autocompletion, docs

[dangotbanned]

Fixes #3552

Overview of issues by @binste in comment

The draft PR is very helpful! Trying to summarise/reword it for myself:

• Then should not inherit from SchemaBase as it muddies autocompletion
• We need a type hint which lets a SchemaBase pass due to alt.condition and alt.when().then().otherwise(). Can be SchemaBase or a protocol
• It's unclear to me when, as a developer, I'd use SchemaLike. If I understand it correctly, we mainly introduce it now to make these types work.
• Purpose:
  • Fix type errors users might get right now, keeping types as narrow as possible so they are more useful
  • Improving UX: keep/improve autocompletion + provide a good visual indication that we mean conditions can be passed

How about

@runtime_checkable
class Condition(Protocol):
   """We use this protocol to signal to a user that they can pass any condition created by either `alt.condition` or `alt.when`.

   Other SchemaBase instances will pass as `Condition` as well and so for type checkers it won't matter but using this protocol when only conditions are expected at least gives a better visual indication to users.
   """
    _schema: ClassVar[_SchemaLikeDict] = {"type": "object"}

    def to_dict(self, *args, **kwds) -> Any: ...


def chart_encode(
   col_7: Optional[str | Color | Condition | Map | ColorDatum | ColorValue] = Undefined,
)

Condition is not yet used anywhere in the codebase and it makes it clearer what we intend to do with the protocol. What do you think?

Tasks

• Allow Then in Chart.encode(), without subclassing SchemaBase
  • See comment for screenshots of old autocomplete
• Experiment with simplifying Chart.encode() annotations
  • comment
  • 08bf16e (#3567)
• Standardise user-facing (but non-public) aliases & documentation
  • (Condition|Schema)Like
    • d20109e (#3567)
  • Various TypeAlias|TypedDict in api.py
    • 0a6d599 (#3567)
    • 0a93309 (#3567)

Related

• feat: Improve the syntax for conditions with multiple predicates #3427 (comment)
• d12a741
• 0bdfa72 (#3536)

Note

This PR started as a draft proposal for addressing multiple related issues.
See #3552 (comment) for further info

Draft PR Demo

Purely demonstrating type checking behavior for #3552 (comment)

Extended chart_encode

Note

mypy failing is expected and part of the demonstration

[dangotbanned]

For reference, this is the short/long form

[dangotbanned]

I was surprised that the current schema doesn't allow this.

Conditional encodings can omit the default, but conditional properties must define one.
I find this strange as all the conditional properties I tested accept value=None - so maybe this support could be added in vega-lite?

[dangotbanned]

I'm thinking we could simplify these by adding some intermediate, non-exported aliases.

So for the first two channels:

Imports/defs

from typing import Union
from typing_extensions import TypeAlias

from altair import (
    Angle,
    AngleDatum,
    AngleValue,
    Color,
    ColorDatum,
    ColorValue,
    Undefined,
)
from altair.utils import Optional
from altair.vegalite.v5.api import IntoCondition
from altair.vegalite.v5.schema._typing import Map

AnyAngle: TypeAlias = Union[Angle, AngleDatum, AngleValue]
AnyColor: TypeAlias = Union[Color, ColorDatum, ColorValue]

class _EncodingMixin:
    def encode_current(
        self,
        *args: Any,
        angle: Optional[
            str | Angle | Map | AngleDatum | AngleValue | IntoCondition
        ] = Undefined,
        color: Optional[
            str | Color | Map | ColorDatum | ColorValue | IntoCondition
        ] = Undefined,
    ): ...
    def encode_proposed(
        self,
        *args: Any,
        angle: Optional[str | AnyAngle | Map | IntoCondition] = Undefined,
        color: Optional[str | AnyColor | Map | IntoCondition] = Undefined,
    ): ...

Would certainly reduce the amount of repetition in all the names.
Since there are 40 channels, with up to 3 names each - adding just a single new type IntoCondition has a big impact

[dangotbanned]

See: feat(typing): Adds Any... aliases in channels.py

[dangotbanned]

See this thread, regarding potential trade-off with an alias here

• feat(typing): Adds public altair.typing module #3515 (comment)

IMO this is isn't as big of an issue as before - but still relevant

[dangotbanned]

Not requiring this # type: ignore demonstrates that #3552 is fixed