gh-105499: Merge typing.Union and types.UnionType

[JelleZijlstra]

• Issue: Merge typing.Union and types.UnionType #105499

---

📚 Documentation preview 📚: https://cpython-previews--105511.org.readthedocs.build/

[AlexWaygood]

Would we be able to get rid of typing._make_union, and just have TypeVar etc. call UnionType.__class_getitem__ directly?

[JelleZijlstra]

Would we be able to get rid of typing._make_union, and just have TypeVar etc. call UnionType.__class_getitem__ directly?

Yes

[AlexWaygood]

Instead of deleting typing.Union completely, adding UnionType.__class_getitem__, and making typing.Union an alias for types.UnionType, I wonder if we could just change typing.Union so that it's a special form that just returns instances of UnionType:

fromoperatorimportor_fromfunctoolsimportreduce@_SpecialFormdefUnion(self, parameters):
returnreduce(or_, parameters)

That would avoid the issue of "Should we rename types.UnionType to be Union", as we'd keep them as distinct objects.

But I know your plan is to deal with handling forward refs in | expressions later, which would mean that^ idea above wouldn't work right now (unions involving forward references would break).

So perhaps you could instead expose a _secret_undocumented_constructor method for types.UnionType (we can bikeshed over the name), and then just do

@_SpecialFormdefUnion(self, parameters):
returntypes.UnionType._secret_undocumented_constructor(parameters)

Or we could just expose the constructor of types.UnionType, of course.

[AlexWaygood]

Also you can now get rid of this function as part of this PR; prior callers of the function can now just use isinstance() checks against types.UnionType:

cpython/Lib/functools.py

Lines 842 to 844 in 6a8b862

	def_is_union_type(cls):
	fromtypingimportget_origin, Union
	returnget_origin(cls) in {Union, types.UnionType}

[JelleZijlstra]

That would avoid the issue of "Should we rename types.UnionType to be Union", as we'd keep them as distinct objects.

I'd rather not keep them as distinct objects, though; that means we still have two objects that to a user look like the same thing. Plus, we'd have get_origin(Union[int, str]) != Union.

[AlexWaygood]

I guess one of my reservations here is that UnionType ends up looking like a pretty weird type. You can't construct instances of it directly:

>>> from types import UnionType
>>> UnionType(int, str)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
TypeError: cannot create 'types.UnionType' instances

...Except wait, you can, we now have a "secret __class_getitem__ backdoor" to create instances directly:

>>> UnionType[int, str, bytes]
int | str | bytes

It's very unusual for __class_getitem__ to just directly return instances of the class, and it feels really weird to make that the only way you're allowed to construct instances of the class.

Maybe that means we should just expose the constructor as well as adding __class_getitem__...?

Plus, we'd have get_origin(Union[int, str]) != Union.

Good point, that would indeed be confusing.

[JelleZijlstra]

I can make the constructor work. Should it take *args and union them all together?

[AlexWaygood]

I can make the constructor work. Should it take *args and union them all together?

That makes sense to me!

[AlexWaygood]

This looks great, in my opinion. From a design perspective, the only weirdnesses I can see are that both of these become valid at runtime:

fromtypesimportUnionTypefromtypingimportUnionUnionType[int, str]
Union(int, str)

I can live with that, though, and hopefully linters can flag those uses. (Type checkers almost certainly will, anyway.) On our side, we can just not document that you can do either of those things.

[JelleZijlstra]

.__args__ is no longer writable.

[JelleZijlstra]

With the new code there are fewer code paths that trigger the equality comparison.

[JelleZijlstra]

It's been long enough, I'm planning to merge this once the tests pass again.

[bedevere-bot]

🤖 New build scheduled with the buildbot fleet by @JelleZijlstra for commit cab69f0 🤖

Results will be shown at:

https://buildbot.python.org/all/#/grid?branch=refs%2Fpull%2F105511%2Fmerge

If you want to schedule another build, you need to add the 🔨 test-with-buildbots label again.

[hugovk]

This PR causes a potential regression: #131933.