Recent pylance is striking out `Union` imports as deprecated

[gwk]

Summary

As of Python 3.12, typing.Union is not documented as deprecated. Furthermore, the type | operator is not a perfect replacement for Union, because union can mix string and type arguments whereas | cannot.

Unfortunately, Pylance is reporting that Union is deprecated. It also seems to be suffering from a bug where the version number is reported as [object Object]. Perhaps this is the reason for the error?

Environment data

• Language Server version: 2024.9.1
• OS and version: darwin arm64
• Python version (and distribution if applicable, e.g. Anaconda): CPython 3.12.2
• python.analysis.indexing: true
• python.analysis.typeCheckingMode: off

Code Snippet

from typing import Union

Expected behavior

I would expect Plyance to not be so aggressive about reporting typing.Union as deprecated, when it really is not. It seems that this is somebody's style preference that has been turned into a non-optional warning in the language server. Please consider that the recommended | type operator is not a perfect replacement for Union, because union can mix string and type arguments whereas | cannot. Pylance should not report it as deprecated or strike it through. At very least, it should display a hint to turn off such aggressive warnings like this in the hover explanation.

Note that Union is not documented as deprecated in 3.13 RC2 either. See:

• https://docs.python.org/3.12/library/typing.html#typing.Union
• https://docs.python.org/3.13/library/typing.html#typing.Union

Actual behavior

Pylance strikes out the Union import and displays this message on hover:

This type is deprecated as of Python [object Object]; use "|" insteadPylance

Logs

2024-09-14 09:51:10.848 [info] (Client) Pylance async client (2024.9.1) started with python extension (2024.15.2024091301)
2024-09-14 09:51:11.173 [info] [Info  - 9:51:11 AM] (50297) Pylance language server 2024.9.1 (pyright version 1.1.378, commit ce64adc1) starting
2024-09-14 09:51:11.217 [info] [Info  - 9:51:11 AM] (50297) Assuming Python version 3.12.2.final.0

[erictraut]

Thanks for reporting the [object Object] issue. That hasn't been previously reported. I just introduced a fix in pyright, and it will be fixed in the next pyright release.

As for the other issue, this is by design. By default, pyright doesn't mark Union as deprecated. This is true even in strict mode. I presume that you've opted to enable the deprecateTypingAliases option in your pyright configuration. Only when this is enabled will you see pyright treat typing.Union, typing.List, etc. as deprecated. While none of these older-style typing special forms are unlikely to go away any time soon, their use does make your code look outdated in general. Many pyright users requested that we provide a way to identify and report their usage to facilitate the modernization of their code base. If you prefer to use older forms like Union, simply revert the deprecateTypingAliases configuration option back to its default value of "false".

[gwk]

Eric, thank you for your kind and detailed response. You are correct, I unwittingly checked that box as part of a more involved update to Pylance settings.

I stand by the observation that while typing.List, Dict, and friends are all truly deprecated, Union is not, and as I explained above, not so easily replaced as the others. It is a shame that this is an all-or-nothing setting. I imagine that it is unlikely to change at this point but please consider adding a separate flag for Union that does not misrepresent it as deprecated.

Thanks again for your help!

[StellaHuang95]

This issue has been fixed in prerelease version 2024.9.101, which we've just released. You can find the changelog here: CHANGELOG.md

[agkphysics]

This issue has been fixed in prerelease version 2024.9.101

The release notes state:

Bug fix: Recent pylance is striking out Union imports as deprecated pylance-release#6390

But this is not correct. Optional and Union are both still marked as deprecated with Pylance v2024.9.101:

[debonte]

@agkphysics, do you have deprecateTypingAliases enabled? See this comment above.

[rchiodo]

Did you turn off the 'deprecateTypingAliases' setting? That's what causes the error to show up for me.

[gwk]

@debonte @rchiodo my hope with this bug report was that deprecateTypingAliases could be turned on to report all of the truly deprecated types, but not Union which is still necessary and not actually deprecated.

[erictraut]

@gwk, none of these old forms are going away. Removing them from typing would break too much existing code. That means you can continue to use List instead of list, etc. in your code if you prefer. Likewise, you can continue to use Optional[T] rather than T | None and Union[S, T] rather than S | T. The latter are preferred in modern code bases (and most people find them more readable), but you can stick with the old ones if you want. The deprecateTypingAliases check was added for users who want to modernize their code bases.

You mentioned that | isn't a perfect replacement for Union, but there are ways to make it work for all of the same use cases. For example, let's say that Foo requires a forward reference and therefore needs to be surrounded by quotes. In this case, "Foo" | int will not work, but "Foo | int" will. The need for quoting goes away almost entirely if you use from __future__ import annotations, which many modern code bases do. Python 3.14 will fully remove the need to include this import.

[gwk]

@erictraut thank you for explaining. Can you clarify what the meaning of the bug fix is in the change log? It vaguely sounds like the intent is to undo "Recent pylance is striking out Union imports as deprecated" but I guess that was just wishful thinking on my part.

[erictraut]

The pylance team wrote the release notes, so we'd need to ask them for clarification, but I suspect that it's referring to the fact that I fixed the [object Object] issue that you reported above. Perhaps their automated scripts just copied the title of your bug report into the release notes. If you look in the pyright release notes, there is no reference to "Union imports".

[debonte]

Perhaps their automated scripts just copied the title of your bug report into the release notes.

Yes, that's correct. We don't write our release notes by hand anymore.