Enable py3.14 and deprecate some alias functionality by nstarman · Pull Request #225 · beartype/plum

nstarman · 2025-11-23T23:50:06Z

Aliases are now always turned on. The alias machinery dynamically creates TypeAliasType objects that are ONLY used in string representations, never in the actual type.

Fixes #224
Fixes #227

coveralls · 2025-11-23T23:52:46Z

Pull Request Test Coverage Report for Build 22191117846

Details

106 of 106 (100.0%) changed or added relevant lines in 4 files are covered.
No unchanged relevant lines lost coverage.
Overall coverage increased (+0.009%) to 99.6%

Totals
Change from base Build 22190629474:	0.009%
Covered Lines:	997
Relevant Lines:	1001

💛 - Coveralls

nstarman · 2025-11-24T00:10:20Z

@wesselb I don't know how to resolve this serious problem.

nstarman · 2025-11-24T01:37:39Z

Looking at https://github.com/python/cpython/blob/425f24e4fad672c211307a9f0018c8d39c4db9de/Objects/unionobject.c#L279 I kind of doubt the union alias functionality can continue to work this way.
A potential alternative would be if beartype could dynamically generate TypeAliasType of the union and swap it in-place by modifying the function's annotations.

Meanwhile can I make this a no-op for Python 3.14+?

wesselb · 2025-11-24T10:52:53Z

Meanwhile can I make this a no-op for Python 3.14+?

Absolutely. Let's do this for now until we figure out whether this is still possible for 3.14+.

nstarman · 2025-11-25T03:25:19Z

Fully functional until py3.14 then they turn into deprecated no-ops.

nstarman · 2025-11-25T03:39:26Z

Tests need adjustment

nstarman · 2025-12-17T19:39:44Z

I can work on this after #179

wesselb · 2025-12-18T10:05:52Z

@nstarman that would be amazing! :)

nstarman · 2026-02-19T16:30:10Z

Copilot

Pull request overview

Enables Python 3.14 support by avoiding typing.Union monkeypatching (now immutable) and shifting union-alias handling to Plum’s own formatting/registry, with updated tests/docs/CI to cover the new behavior.

Changes:

Add Python 3.14 test coverage and split union-alias tests by Python version.
Update union aliasing internals to use TypeAliasType on 3.14+ and apply alias-aware formatting in repr_short/repr_type.
Adjust dependency constraints and documentation examples for the new 3.14+ behavior.

Reviewed changes

Copilot reviewed 13 out of 14 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
`src/plum/_alias.py`	Adds 3.14+ path using `TypeAliasType`, deprecates activation APIs, and introduces `_transform_union_alias`.
`src/plum/repr.py`	Uses `_transform_union_alias` so `repr_short`/`repr_type` can display registered union aliases.
`src/plum/_signature.py`	Refactors `beartype` type-hint wrapping usage (import/usage cleanup).
`src/plum/_type.py`	Small refactor in `resolve_type_hint` and adjusts `UNION_TYPES` container type.
`tests/test_alias_upto313.py`	Skips these tests on 3.14+ and routes activation calls via `plum.*`.
`tests/test_alias_314plus.py`	New 3.14+ focused tests for alias formatting and deprecated APIs.
`tests/test_util.py`	Updates expected `typing.Union[...]` short repr for 3.14+.
`tests/conftest.py`	Adds an autouse fixture to isolate/clear the union-alias registry per test.
`docs/union_aliases.md`	Adds version-gated examples for the changed Union repr behavior in 3.14+.
`docs/comparison.md`	Adds version-gated example output to match 3.14+ Union repr changes.
`pyproject.toml`	Adds conditional `beartype` minimum versions keyed on Python version.
`.github/workflows/ci.yml`	Adds Python 3.14 to CI and pre-release beartype test runs.
`.pre-commit-config.yaml`	Removes default Python language version pinning.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-19T16:35:56Z

.github/workflows/ci.yml

+            extra-install: "pip install --upgrade --pre beartype"
+          - name: "3.14"
+            python-version: "3.14"
+            extra-install: ""
+          - name: "3.14-pre-beartype"
+            python-version: "3.14"
+            extra-install: "pip install --upgrade --pre beartype"


The matrix extra-install uses pip install ... even though the job environment is managed via uv sync / uv run. Without activating the venv, pip may install outside the uv environment, so the pre-beartype runs might not actually test against the pre-release beartype. Use uv pip install --upgrade --pre beartype (or uv run python -m pip ...) to ensure the install lands in the environment used by the subsequent uv run pytest.

Suggested change

extra-install: "pip install --upgrade --pre beartype"

- name: "3.14"

python-version: "3.14"

extra-install: ""

- name: "3.14-pre-beartype"

python-version: "3.14"

extra-install: "pip install --upgrade --pre beartype"

extra-install: "uv pip install --upgrade --pre beartype"

- name: "3.14"

python-version: "3.14"

extra-install: ""

- name: "3.14-pre-beartype"

python-version: "3.14"

extra-install: "uv pip install --upgrade --pre beartype"

Copilot · 2026-02-19T16:35:57Z

docs/union_aliases.md

 Union aliases must be activated explicitly, because the feature
 monkeypatches `Union.__str__` and `Union.__repr__`.


This paragraph implies union aliases must be activated because they monkeypatch Union.__str__/__repr__, but on Python 3.14+ activate_union_aliases is deprecated and Union repr can’t be monkeypatched. Consider rewording to make the behavior/version split explicit (e.g., activation required only on <=3.13; on 3.14+ aliasing affects Plum’s own formatting only).

Suggested change

Union aliases must be activated explicitly, because the feature

monkeypatches `Union.__str__` and `Union.__repr__`.

On Python 3.13 and earlier, union aliases work by monkeypatching

`typing.Union.__str__` and `typing.Union.__repr__`, and therefore must be

activated explicitly.

On Python 3.14 and later, `typing.Union`'s representation can no longer be

monkeypatched and `activate_union_aliases()` is deprecated; union aliases

instead only affect how Plum formats unions in its own output.

Copilot · 2026-02-19T16:35:57Z

docs/union_aliases.md

 >>> Union[tuple(scalar_types) + (tuple,)]       # Scalar or tuple
-typing.Union[Scalar, tuple]
+ typing.Union[Scalar, tuple]

 >>> Union[tuple(scalar_types) + (tuple, list)]  # Scalar or tuple or list
-typing.Union[Scalar, tuple, list]
+ typing.Union[Scalar, tuple, list]


The two output lines in this code block have leading whitespace before typing.Union[...] (note the extra space). That will likely cause doctest/sybil output matching to fail and also looks unintentional; remove the leading space(s).

Copilot · 2026-02-19T16:35:58Z

tests/test_alias_314plus.py

+def test_union_alias(display):
+    plum.set_union_alias(int | str, alias="IntStr")
+
+    # Check that printing is normal before registering any aliases.
+    assert display(Union[int, str]) == "IntStr"  # noqa: UP007
+


The comment says printing is checked "before registering any aliases", but the alias was already registered just above. Either move the assertion before the first set_union_alias call or adjust the comment so it matches the test setup.

Copilot · 2026-02-19T16:35:58Z

src/plum/_alias.py

+        # Check for conflicting aliases
+        for existing_union, existing_alias in _ALIASED_UNIONS.items():
+            if set(existing_union) == set(args) and alias != repr(existing_alias):
+                union_str = repr(union)
+                raise RuntimeError(
+                    f"`{union_str}` already has alias `{existing_alias!r}`."
+                )


Avoid using repr(existing_alias) for conflict detection. repr() isn’t a stable API and may change formatting across Python/typing_extensions versions, which could incorrectly treat re-registering the same alias name as a conflict. Compare against the alias name attribute instead (e.g., existing_alias.__name__).

Signed-off-by: nstarman <nstarman@users.noreply.github.com>

nstarman · 2026-02-19T16:48:37Z

@leycec one part of this PR is to change the type hint repr machinery in plum.alias to use TypeAliasType objects that are never used a runtime, only for pretty printing. I was wondering if this functionality, which turns out to be quite simple, would be relevant to upstream into beartype itself. With these aliases type annotations can become visually much simpler.

#225 (comment)

nstarman · 2026-02-19T16:58:18Z

@wesselb, currently this PR uses the TypeAliasType repr directly, but we might want to preserve the old behaviour of transforming it to Union[{repr}]. LMK.

nstarman force-pushed the mnt/py314 branch 2 times, most recently from 99374d0 to baee207 Compare November 24, 2025 00:03

nstarman force-pushed the mnt/py314 branch from baee207 to e717eb1 Compare November 25, 2025 03:24

nstarman force-pushed the mnt/py314 branch from e717eb1 to a7f501c Compare January 2, 2026 07:14

nstarman force-pushed the mnt/py314 branch 10 times, most recently from 23b77fd to 76e1a75 Compare February 13, 2026 04:34

nstarman changed the title ~~test: py3.14~~ enable py3.14 Feb 13, 2026

nstarman force-pushed the mnt/py314 branch from 76e1a75 to c8463ca Compare February 19, 2026 16:26

nstarman marked this pull request as ready for review February 19, 2026 16:30

nstarman requested review from Copilot and wesselb February 19, 2026 16:30

nstarman changed the title ~~enable py3.14~~ Enable py3.14 and deprecate some alias functionality Feb 19, 2026

Copilot started reviewing on behalf of nstarman February 19, 2026 16:30 View session

Copilot AI reviewed Feb 19, 2026

View reviewed changes

nstarman added 4 commits February 19, 2026 11:42

test: py3.14

d024176

Signed-off-by: nstarman <nstarman@users.noreply.github.com>

feat: deprecate union aliasing

c4c977a

Signed-off-by: nstarman <nstarman@users.noreply.github.com>

refactor: some simplifications

0c8ceea

Signed-off-by: nstarman <nstarman@users.noreply.github.com>

feat: union alias in python 3.14

1e063b0

Signed-off-by: nstarman <nstarman@users.noreply.github.com>

nstarman force-pushed the mnt/py314 branch from c8463ca to 1e063b0 Compare February 19, 2026 16:46

		Union aliases must be activated explicitly, because the feature
		monkeypatches `Union.__str__` and `Union.__repr__`.

-Union aliases must be activated explicitly, because the feature
-monkeypatches `Union.__str__` and `Union.__repr__`.
+On Python 3.13 and earlier, union aliases work by monkeypatching
+`typing.Union.__str__` and `typing.Union.__repr__`, and therefore must be
+activated explicitly.
+On Python 3.14 and later, `typing.Union`'s representation can no longer be
+monkeypatched and `activate_union_aliases()` is deprecated; union aliases
+instead only affect how Plum formats unions in its own output.

Conversation

nstarman commented Nov 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coveralls commented Nov 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 22191117846

Details

💛 - Coveralls

Uh oh!

nstarman commented Nov 24, 2025

Uh oh!

nstarman commented Nov 24, 2025

Uh oh!

wesselb commented Nov 24, 2025

Uh oh!

nstarman commented Nov 25, 2025

Uh oh!

nstarman commented Nov 25, 2025

Uh oh!

nstarman commented Dec 17, 2025

Uh oh!

wesselb commented Dec 18, 2025

Uh oh!

nstarman commented Feb 19, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 19, 2026

Choose a reason for hiding this comment

Uh oh!

nstarman commented Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nstarman commented Feb 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Comments

nstarman commented Nov 23, 2025 •

edited

Loading

coveralls commented Nov 23, 2025 •

edited

Loading

nstarman commented Feb 19, 2026 •

edited

Loading