Polars write_excel参数类型检查差异及优化问询

问题背景 #

使用Polars的write_excel方法时，column_formats参数要求传入ColumnFormatDict类型，其定义如下：

ColumnFormatDict: TypeAlias = Mapping[
    # dict of colname(s) or selector(s) to format string or dict
    Union[ColumnNameOrSelector, tuple[ColumnNameOrSelector, ...]],
    Union[str, Mapping[str, str]],
]

ColumnNameOrSelector: TypeAlias = Union[str, SelectorType]

SelectorType: TypeAlias = "Selector"

遇到的现象：

• 内联传入{"a":"#,##0;[Red]-#,##0"}时，类型检查无报错；
• 先将该字典赋值给变量column_formats再传入时，类型检查报错：

Argument of type "dict[str, str]" cannot be assigned to parameter "column_formats" of type "ColumnFormatDict | None" in function "write_excel"
  Type "dict[str, str]" is not assignable to type "ColumnFormatDict | None"
    "dict[str, str]" is not assignable to "Mapping[ColumnNameOrSelector | tuple[ColumnNameOrSelector, ...], str | Mapping[str, str]]"
      Type parameter "_KT@Mapping" is invariant, but "str" is not the same as "ColumnNameOrSelector | tuple[ColumnNameOrSelector, ...]"
    "dict[str, str]" is not assignable to "None"

显式注解变量类型为dict[str|cs.Selector|tuple[str|cs.Selector], str]可消除报错，但会限制参数灵活性。

问题解答 #

1. 为何内联时str可作为合法键，赋值变量后却不行？

这是Python类型检查器（如mypy）的类型推断规则差异导致的：

• 内联传参时，类型检查器会直接根据write_excel的参数类型要求，将字典推断为ColumnFormatDict类型——它会自动把str键适配到ColumnNameOrSelector | tuple[ColumnNameOrSelector, ...]这个联合类型中，因为str是ColumnNameOrSelector的子类型，上下文足够让检查器完成适配。
• 当你把字典赋值给变量时，类型检查器会默认推断最具体的类型：dict[str, str]。而Mapping的键类型是**不变（invariant）**的——也就是说，dict[str, str]不能被视为Mapping[Union[ColumnNameOrSelector, ...], ...]的子类型，因为两者的键类型不完全一致（str≠Union[ColumnNameOrSelector, ...]），因此会触发类型错误。

2. 修改ColumnNameOrSelector能否实现无需显式注解即可避免警告？

不能，问题的核心不在ColumnNameOrSelector的定义，而在ColumnFormatDict的结构。ColumnNameOrSelector已经包含了str，但ColumnFormatDict用Mapping[Union[KeyTypes], ValueTypes]的定义方式，导致变量推断的dict[str, str]无法兼容。

要实现无需显式注解，需要调整的是ColumnFormatDict的类型定义，而不是ColumnNameOrSelector——比如采用第三个问题中的拆分思路，让类型检查器能自动匹配到对应的子类型。

3. 将ColumnFormatDict拆分为多个Mapping的Union是否可行？

这个思路是可行的，而且能直接解决你遇到的变量赋值后报错的问题：

ColumnFormatDict: TypeAlias = Union[
    Mapping[str, Union[str, Mapping[str, str]]],
    Mapping[SelectorType, Union[str, Mapping[str, str]]],
    Mapping[tuple[str|SelectorType, ...], Union[str, Mapping[str, str]]],
]

拆分后，类型检查器会把dict[str, str]自动匹配到第一个Mapping[str, ...]分支，不再触发类型不兼容的错误。

不过需要注意一个局限：如果你的字典同时包含多种类型的键（比如既有str又有Selector），这种拆分后的定义可能无法匹配，因为此时字典的键类型是Union[str, SelectorType]，不属于任何一个单一键类型的Mapping分支。如果要覆盖这种混合键的场景，可以在Union中再添加一个包含所有键类型的分支：

ColumnFormatDict: TypeAlias = Union[
    Mapping[str, Union[str, Mapping[str, str]]],
    Mapping[SelectorType, Union[str, Mapping[str, str]]],
    Mapping[tuple[str|SelectorType, ...], Union[str, Mapping[str, str]]],
    Mapping[Union[str, SelectorType, tuple[str|SelectorType, ...]], Union[str, Mapping[str, str]]],
]

这样就能同时支持单一键类型和混合键类型的字典，兼顾灵活性和类型检查的兼容性。

内容的提问来源于stack exchange，提问作者Dean MacGregor