Add Pyright/Pylance TypeAlias stub support for Python 3.12 compatibility

[Copilot]

This PR implements custom type stubs to provide better Pyright/Pylance support for Python 3.12's TypeAliasType functionality, following the recommended approach of using local stubs rather than modifying the standard library.

Problem

Python 3.12 introduced the type statement and typing.TypeAliasType for type aliases, but some type checkers like Pyright/Pylance may need additional type information (like __class_getitem__) that isn't always available in the standard library stubs.

Solution

This PR adds:

• pyrightconfig.json - Configures Pyright to use custom stubs from the typings directory
• typings/typing.pyi - Minimal stub file that defines TypeAliasType with the __class_getitem__ method

The implementation follows Python typing best practices:

• Uses Pyright's dedicated stubPath setting instead of extraPaths
• Provides only the minimal definitions needed (partial stub approach)
• Follows the conventional typings/ directory structure

Example Usage

With these stubs in place, type checkers will properly handle Python 3.12 type aliases:

from typing import TypeAlias

# This will now have proper type checker support
MyStringType: TypeAlias = str

# Python 3.12+ syntax also works
type NumberType = int | float

Testing

Added comprehensive tests in test_typing_stub.py to verify:

• Stub files exist and are properly formatted
• Pyright configuration is correct
• Type alias functionality works as expected
• Python 3.12 type statement syntax is supported

All tests pass (16/16) with no regressions introduced.

References

• Pyright stub documentation
• Python 3.12 type statement PEP 695
• Typing specification on stubs

Original prompt

Your plan is on the right track—use a local stub instead of touching the stdlib. A couple of tweaks will make it cleaner and more robust for Pyright/Pylance.

What to change

Prefer Pyright’s stub path over extraPaths
Pyright (and Pylance) have a dedicated setting for custom stubs. Use it—the default is already ./typings, but making it explicit is nice.

pyrightconfig.json

{
"stubPath": "typings",
"executionEnvironments": [
{ "root": "." }
]
}

(Alternatively in VS Code settings for Pylance: "python.analysis.stubPath": "typings".) Pyright’s docs explicitly recommend custom stub files and describe how they’re found.
GitHub
+1

Put your stub here and keep it minimal

engine/python/
typings/
typing.pyi

typing.pyi (only define what you need)

from typing import Any, TypeAlias

class TypeAliasType:
@classmethod
def class_getitem(cls, item: Any) -> "TypeAliasType": ...

Pyright will prefer your stub for typing over the bundled one when resolving types, and a partial stub that only declares the members you care about is fine. (That’s the recommended approach for custom stubs.)
GitHub

Why this works / context

Type aliases & 3.12: Python 3.12 added the type statement and the runtime typing.TypeAliasType object that represents such aliases. If your checker or tooling expects a particular attribute (like class_getitem), a local stub is the safest way to describe it without editing the stdlib.
Python documentation
+1

Stubs best-practice: Stubs (.pyi) are the sanctioned way to provide or override type info; both the typing spec and mypy docs cover this pattern.
Typing Documentation
+1

Extra tips (optional, but useful)

If you also run Pylance in VS Code, it honors the same stub directory via python.analysis.stubPath. The “typings” folder approach is a common and documented workflow.
GitHub
+1

If you need back-compat on older Pythons, note that TypeAliasType has been backported to typing_extensions; some tooling/lint rules (e.g., Ruff UP040) encourage migrating to PEP 695’s type syntax where possible.
GitHub
+1

Keep the stub as small as possible—only the symbols you rely on. Pyright explicitly recommends “custom, minimal stubs” for gaps.
GitHub

TL;DR

Use stubPath: "typings" (or VS Code’s python.analysis.stubPath) rather than extraPaths.
GitHub
+1

Add engine/python/typings/typing.pyi with just the TypeAliasType bits you need.
Typing Documentation

Don’t modify the stdlib; let the checker read your stub first. ✔️

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[codesandbox]

Review or Edit in CodeSandbox

Open the branch in Web Editor • VS Code • Insiders

Open Preview