feat(python): Make UNSET a PEP 661 sentinel

[dangotbanned]

Description

As defined on main, UNSET has a few issues - most of which are not that visible.

This PR introduces a conditional-backport for sentinel (python 3.15).
Mosaic gets both the runtime and typing benefits - while requiring no new dependencies .
When available ¹, typing_extensions.sentinel is prefered - before defining a minimal ² vendored version ³

The new tests are a combination of:

• tests adapted from the typing_extensions test suite (1, 2)
• examples from the sentinel (python 3.15) docs
• and a handful of runtime & static cases I didn't steal 😅

What's fixed?

(4dcdb43)

UNSET can be used directly in annotations and is understood by type checkers:

from vgplot._types import UNSET

def function(arg: int | str | UNSET = UNSET) -> None:
    #                       ^^^^^^^
    #      would cause a runtime `TypeError` on main
    from typing_extensions import assert_never, assert_type

    if arg is not UNSET:  # would not perform type narrowing on `main`, 
                          # requires a solution like https://github.com/vega/altair/blob/48b388f140c79d29056d6ea56e519b27e2ed8838/altair/utils/schemapi.py#L1012-L1023
        assert_type(arg, int | str)
    elif isinstance(arg, (int, str)):
        assert_never(arg)
        #            ~~~ branch is unreachable because there is only 1 `UNSET`
    else:
        assert_type(arg, UNSET)

UNSET maintains identity when copied or pickled:

import copy
import pickle

from vgplot._types import UNSET

print(
    copy.copy(UNSET)
    is copy.deepcopy(UNSET)
    is pickle.loads(pickle.dumps(UNSET))
    is UNSET
)
# True

UNSET now has a visible docstring:

Related

• PEP 661 – Sentinel Values
• sentinel (python 3.15)
• typing_extensions.sentinel
• Add sentinels (PEP 661) to the spec python/typing#2277

Footnotes

1. typing_extensions>=4.16.0 is installed ↩

2. I've documented the original source and the differences are the exclusion of deprecation paths,
   which serve no benefit to mosaic. ↩

3. We've used this technique a few times in narwhals, but not (yet) for sentinel ↩

[dangotbanned]

I've had this sitting ready since shortly after opening #1075

But didn't want to create too much noise - so here's a present now if anyone wants it 😄

[dangotbanned]

@domoritz

Can we remove this in the future? Would be good to add a note saying when we can remove this?

So this part would be detected by Ruff via outdated-version-block (UP036)

Anything that uses sys.version_info works the same and will be flagged in-step with

mosaic/packages/vgplot/vgplot-python/pyproject.toml

Line 6 in cdb956b

requires-python = ">=3.10"

But on this part:

when we can remove this?

Without dependencies?
October 2031

With "typing_extensions>=4.16"?
Any time 😄

[dangotbanned]

I could add some of that here I suppose 😅

[dangotbanned]

I went with a module doc instead, since I wrote one in (https://github.com/narwhals-dev/narwhals/blob/deffd1d1e11dd593675119c1445dc7d5291426c3/src/narwhals/_typing_compat.py)

[domoritz]

I'm generally a fan of updating version requirements when it helps us clean up stuff. We don't need to support the oldest Python versions so feel free to update version requirements.

[dangotbanned]

If we were to update requirements, adding this would be my preference as it is a single file dependency and very common:

dependencies = [
  "typing-extensions>=4.16 ; python_full_version < '3.15'",
]

Depending on the latest python version can simplify maintainence, but it will hurt adoption of Mosaic.
It would mean that no downstream packages can offer backwards compatibility, if they have vgplot as a required dependency