VSCode中tkinter.Canvas类型提示来源及子类应用方法

我遇到了一个十分困扰的问题。
VSCode的一项重要功能是，我在编写接收**kw参数的tkinter类时，它会提供对应的类型提示，示例如下：

目前我尝试基于Tk.Canvas()类创建子类，VSCode已经自动生成了如下方法定义：

class MyCanvas(Tk.Canvas):
    def __init__(self, master: Misc | None, cnf: dict[str, Any] | None, *, background: _Color, bd: _ScreenUnits, bg: _Color, border: _ScreenUnits, borderwidth: _ScreenUnits, closeenough: float, confine: bool, cursor: _Cursor, height: _ScreenUnits, highlightbackground: _Color, highlightcolor: _Color, highlightthickness: _ScreenUnits, insertbackground: _Color, insertborderwidth: _ScreenUnits, insertofftime: int, insertontime: int, insertwidth: _ScreenUnits, name: str, offset: Any, relief: _Relief, scrollregion: Tuple[_ScreenUnits, _ScreenUnits, _ScreenUnits, _ScreenUnits] | Tuple[()], selectbackground: _Color, selectborderwidth: _ScreenUnits, selectforeground: _Color, state: Literal["normal", "disabled"], takefocus: _TakeFocusValue, width: _ScreenUnits, xscrollcommand: _XYScrollCommand, xscrollincrement: _ScreenUnits, yscrollcommand: _XYScrollCommand, yscrollincrement: _ScreenUnits) -> None:
        super().__init__(master=master, cnf=cnf, background=background, bd=bd, bg=bg, border=border, borderwidth=borderwidth, closeenough=closeenough, confine=confine, cursor=cursor, height=height, highlightbackground=highlightbackground, highlightcolor=highlightcolor, highlightthickness=highlightthickness, insertbackground=insertbackground, insertborderwidth=insertborderwidth, insertofftime=insertofftime, insertontime=insertontime, insertwidth=insertwidth, name=name, offset=offset, relief=relief, scrollregion=scrollregion, selectbackground=selectbackground, selectborderwidth=selectborderwidth, selectforeground=selectforeground, state=state, takefocus=takefocus, width=width, xscrollcommand=xscrollcommand, xscrollincrement=xscrollincrement, yscrollcommand=yscrollcommand, yscrollincrement=yscrollincrement)

但这个定义存在明显问题：它将本应通过**kw传递的属性改为独立参数，还引用了_Color、_ScreenUnits等未定义的类型。我随后查看Tk.Canvas.__init__()的源码定义，内容如下：

def __init__(self, master=None, cnf={}, **kw):
        """Construct a canvas widget with the parent MASTER.

        Valid resource names: background, bd, bg, borderwidth, closeenough,
        confine, cursor, height, highlightbackground, highlightcolor,
        highlightthickness, insertbackground, insertborderwidth,
        insertofftime, insertontime, insertwidth, offset, relief,
        scrollregion, selectbackground, selectborderwidth, selectforeground,
        state, takefocus, width, xscrollcommand, xscrollincrement,
        yscrollcommand, yscrollincrement."""
        Widget.__init__(self, master, 'canvas', cnf, kw)

这让我十分困惑：Tk.Canvas的类定义中没有任何类型提示，我看到的类型提示到底来源于哪里？有没有办法让我编写的子类的**kw参数也能触发相同的类型提示？

类型提示的来源 #

你在VSCode里看到的tkinter类型提示并非来自tkinter的运行时源码，而是来源于typeshed项目的类型存根文件（.pyi后缀）。Pyright（VSCode的Pylance插件底层的类型检查器）默认内置了typeshed的全量类型注解，这些存根文件为Python标准库、常用第三方库补充了完整的类型定义，你看到的_Color、_ScreenUnits等类型都是typeshed的tkinter存根中定义的内部类型，仅用于类型检查，不会在运行时存在，所以直接把自动生成的代码复制到你的项目中会报类型未定义的错误。

VSCode自动生成的长参数方法定义，是Pylance读取了存根中Canvas.__init__的重载展开形式后生成的，不适合直接用于业务代码开发。

子类实现相同**kw类型提示的方法 #

根据你的使用场景可以选择两种方案：

方案1：透传所有参数（无需额外校验参数场景） #

如果你的子类不需要单独处理父类的构造参数，只做透传，直接用以下写法即可，Pylance会自动继承父类的类型提示：

import tkinter as Tk
from tkinter import Misc
from typing import Any, override

class MyCanvas(Tk.Canvas):
    @override
    def __init__(self, master: Misc | None = None, cnf: dict[str, Any] = {}, **kw) -> None:
        # 你自己的子类初始化逻辑写在这里
        super().__init__(master=master, cnf=cnf, **kw)

写完后实例化MyCanvas时，输入**kw的键就会自动弹出和原生Tk.Canvas完全一致的类型提示。

方案2：需要自定义参数+严格类型校验场景 #

如果你需要给子类加自定义构造参数，同时保留父类参数的类型提示，可以用PEP 692引入的Unpack特性搭配TypedDict实现（Python 3.11及以上可用typing.Unpack，低版本可以安装typing_extensions导入Unpack）：

import tkinter as Tk
from tkinter import Misc
from typing import TypedDict, Unpack, override

# 你可以从typeshed的tkinter存根中复制Canvas参数的类型定义，也可以自定义简化版本
class CanvasInitKwargs(TypedDict, total=False):
    background: str | tuple[int, int, int]
    bd: int | str
    bg: str | tuple[int, int, int]
    # 其他需要的参数按规则补充即可
    width: int | str
    height: int | str

class MyCanvas(Tk.Canvas):
    # 自定义参数放在**kw前面
    def __init__(self, master: Misc | None = None, cnf: dict[str, Any] = {}, custom_param: str = "test", **kw: Unpack[CanvasInitKwargs]) -> None:
        # 处理自定义参数
        print(custom_param)
        super().__init__(master=master, cnf=cnf, **kw)

注意事项 #

如果写完后没有弹出提示，检查VSCode的Pylance插件设置：

• 类型检查级别设置为basic或更高
• 没有禁用typeshed类型存根的加载

内容的提问来源于stack exchange，提问作者Eduardo Machado Behling