SQLAlchemy 与 Pyright 相爱相杀的故事
Pyright 作为一款功能强大的静态类型检查器，深得我心。但近日使用 SQLAlchemy 时，Pyright 提示的类型检查报错，却让我陷入困扰。
本篇文章将简单分享解决思路以及背后的原理。
背景
假设有如下 python 代码：
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy import Column, Integer, String
Base = declarative_base()
class User(Base):
__tablename__ = "users"
id = Column(Integer, primary_key=True)
name = Column(String)
def print_username(name: str):
print(name)
if __name__ == "__main__":
user = User(id=42, name=42)
print_username(user.name)
Pyright 认真负责给出如下报错提示：[Pyright reportGeneralTypeIssues] Argument of type "Column[str]" cannot be assigned to parameter "name" of type "str" in function "print_username" [E]
解决办法
很简单，本地安装 sqlalchemy-stubs 后，报错消失。
Pyright 可正确识别 user 实例的 name 属性为 str 类型，而不是代码定义的 Column 类型。
小技巧：无需引用，直接使用 reveal_type 方法调试类型：
WHY???
为什么安装 stub 包后，无需任何配置，即可直接对 pyright 生效？
Try to resolve using stubs or inlined types found within installed packages.
For a given package, try to resolve first using a stub package. Stub packages, as defined in PEP 561, are named the same as the original package but with “-stubs” appended.
参考 pyright 文档，默认根据包名 -stubs 后缀自动识别。
为什么安装 stub 包后，可正确识别 name 的类型？
首先安装前，pyright 根据 sqlalchemy 的源代码，解析对应的类型，自然将 user.name 当作 Column 类型。安装 sqlalchemy-stubs 后，优先通过 stub 中定义的接口类型解析。
具体实现参考 sqlalchemy-stubs/sql/schema.pyi::Column，关键代码如下。
简而言之类似 java 中的泛型（generics），当 Column 的类型定义为 Type[TypeEngine[_T]] 时，强制约束返回的类型为 T。
_T = TypeVar('_T')
class Column(SchemaItem, ColumnClause[_T]):
__visit_name__: str = ...
key: str = ...
primary_key: bool = ...
nullable: bool = ...
default: Optional[Any] = ...
server_default: Optional[Any] = ...
server_onupdate: Optional[FetchedValue] = ...
index: Optional[bool] = ...
unique: Optional[bool] = ...
system: bool = ...
doc: Optional[str] = ...
onupdate: Optional[Any] = ...
autoincrement: Union[bool, str] = ...
constraints: Set[Constraint] = ...
foreign_keys: Set[ForeignKey] = ... # type: ignore # incompatible with ColumnElement.foreign_keys
info: Optional[Mapping[str, Any]] = ...
comment: Optional[str] = ...
table: Table = ... # TODO: double-check this.
# Now without a name argument.
@overload
def __init__(self, type_: Type[TypeEngine[_T]], *args: Any, autoincrement: Union[bool, str] = ...,
default: Any = ..., doc: str = ..., key: str = ..., index: bool = ..., info: Mapping[str, Any] = ...,
nullable: bool = ..., onupdate: Any = ..., primary_key: bool = ..., server_default: Any = ...,
server_onupdate: Union[FetchedValue, FunctionElement] = ..., quote: Optional[bool] = ..., unique: bool = ...,
system: bool = ..., comment: str = ...) -> None: ...
@overload
def __get__(self, instance: None, owner: Any) -> Column[_T]: ...
@overload
def __get__(self, instance: object, owner: Any) -> _T: ...