Pyright fails to resolve `type(None)` to the `None` singleton, preventing standard type narrowing

[rob3c]

Describe the bug

When type(None) is assigned to a variable and used in a Union type hint, Pyright fails to resolve it to the None singleton. This prevents standard type narrowing (e.g., if not obj.my_list) from removing the None branch, causing elements to be inferred as Unknown.

Code Sample

import typing
none_type = type(None) # Alias for the None singleton

class MyClass:
    # Pyright treats this Union as list[str] | Unknown
    my_list: typing.Union[list[str], none_type]

def fn(o: MyClass):
    if not o.my_list:
        return
    
    # Expected: list[str]
    # Actual: list[str | Unknown]
    elements = [e for e in o.my_list]

Environment

Python 3.13, Pyright/Pylance v2026.2.1

[gramster]

I'm confused; that if will throw an exception in the code you have provided. You have to actually initialize a my_list attribute, and then the type is correct.

[rob3c]

Sorry, I wrote this too quickly, and my minimal repro is too minimal lol!

Here's a real working example that still shows the designtime typing problem indicated above:

import typing

none_type = type(None) # Alias for the `None` singleton

class MyClass:
    def __init__(self):
        # Pyright treats this Union as list[str] | Unknown
        self.my_list: typing.Union[list[str], none_type] = None

def fn(o: MyClass):
    if not o.my_list:
        return

    # Expected: list[str]
    # Actual: list[str | Unknown]
    elements = [e for e in o.my_list]


mc = MyClass()
fn(mc)
mc.my_list = ['a']
fn(mc)

i.e. Pylance/Pyright still breaks in the way I described, but the code actually works now.

[rob3c]

For added context where I ran into this problem (I use None directly in my own code without incident), it was using the CVAT SDK. Part of that library code is generated using templates for the OpenAPI Generator.

Strictly speaking, the CVAT project is choosing to use the none_type indirection in their templates that Pylance/Pyright doesn't seem to be handling correctly. That said, the openapi-generator project itself seems to use it in their python generator, and CVAT likely just followed their example.

I've already opened a issue in the CVAT repo as well FWIW. If you claim that Pylance/Pyright is working as intended, then it'll be especially important for them to update their templates. And I should probably create an issue with OpenAPI Generator also.

[rob3c]

Here's what PEP 484 says about Using None:

When used in a type hint, the expression None is considered equivalent to type(None).

Maybe CVAT's and OAPI Gen's use of none_type as above is correctly considered wrong by Pyright. But since PEP 484 says using None and type(None) in type hints are equivalent, why is this syntax ok:

self.my_list = typing.Union[list[str], None] = None

but this one is not and causes Pyright to introduce the persistent Unknown type:

self.my_list: typing.Union[list[str], type(None)] = None

Also, previously in PEP 483 in both the fundamental building blocks and Pragmatics sections, the usage of None and type(None) is said to be equivalent, and they're specifically shown in Union type hints like this:

fundamental building blocks:

Optional[t1]. Alias for Union[t1, None], i.e. Union[t1, type(None)].

pragmatics:

Where a type is expected, None can be substituted for type(None); e.g. Union[t1, None] == Union[t1, type(None)].