SQLModel官方示例运行失败求助：新手遭遇两类报错

我是数据库新手，正在为PySimpleGUI项目学习SQLModel，严格遵循官方文档运行入门示例代码，但本地无法正常执行，已完成文档列出的所有基础步骤。

问题代码 #

"""sql model"""
from sqlmodel import SQLModel, Field, create_engine, Session
from typing import Optional


class Hero(SQLModel, Table=True):
    """testing sqlmodel"""
    id: Optional = Field(default=None, primary_key=True)
    name: str
    secret_name: str
    age: Optional[int] = None


hero_1 = Hero(name="Deadpond", secret_name="Dive Wilson")
hero_2 = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
hero_3 = Hero(name="Rusty-Man", secret_name="Tommy Sharp", age=48)

engine = create_engine("sqlite:///database.db")

SQLModel.metadata.create_all(engine)
with Session(engine) as s:
    s.add(hero_1)
    s.add(hero_2)
    s.add(hero_3)
    s.commit()

首次运行报错 #

$ py model.py                                                          
Traceback (most recent call last):
  File "pydantic\validators.py", line 751, in pydantic.validators.find_validators            
TypeError: issubclass() arg 1 must be a class                                                

During handling of the above exception, another exception occurred:                          

Traceback (most recent call last):                                                           
  File "C:\Users\muham\Desktop\fun and learning\learning_mysql\model.py", line 6, in <module>
    class Hero(SQLModel):
  File "C:\Users\muham\AppData\Local\Programs\Python\Python310\lib\site-packages\sqlmodel\main.py", line 272, in __new__
    new_cls = super().__new__(cls, name, bases, dict_used, **config_kwargs)
  File "pydantic\main.py", line 198, in pydantic.main.ModelMetaclass.__new__
  File "pydantic\fields.py", line 506, in pydantic.fields.ModelField.infer
  File "pydantic\fields.py", line 436, in pydantic.fields.ModelField.__init__
  File "pydantic\fields.py", line 557, in pydantic.fields.ModelField.prepare
  File "pydantic\fields.py", line 831, in pydantic.fields.ModelField.populate_validators
  File "pydantic\validators.py", line 760, in find_validators
RuntimeError: error checking inheritance of typing.Optional (type: Optional)

报错原因：id字段的类型声明错误，Optional是泛型类型，必须指定具体的内部类型，不能直接写Optional。这里id作为主键，应该声明为Optional[int]。

后续运行报错 #

$ py model.py 
Traceback (most recent call last):
  File "C:\Users\muham\AppData\Local\Programs\Python\Python310\lib\site-packages\sqlalchemy\orm\session.py", line 2619, in add  
    state = attributes.instance_state(instance)                                                                                 
AttributeError: 'Hero' object has no attribute '_sa_instance_state'                                                            

The above exception was the direct cause of the following exception:                                                            

Traceback (most recent call last):                                                                                              
  File "C:\Users\muham\Desktop\fun and learning\learning_mysql\model.py", line 22, in <module>                                  
    s.add(hero_1)                                                                                                               
  File "C:\Users\muham\AppData\Local\Programs\Python\Python310\lib\site-packages\sqlalchemy\orm\session.py", line 2621, in add  
    util.raise_                                                                                                                
  File "C:\Users\muham\AppData\Local\Programs\Python\Python310\lib\site-packages\sqlalchemy\util\compat.py", line 208, in raise_
    raise exception                                                                                                             
sqlalchemy.orm.exc.UnmappedInstanceError: Class '__main__.Hero' is not mapped

报错原因：首次运行的类型错误导致Hero类没有被正确映射为数据库表，因此创建的Hero实例缺少SQLAlchemy所需的_sa_instance_state属性，解决第一个问题后该报错会自动消失。

修正后的代码 #

"""sql model"""
from sqlmodel import SQLModel, Field, create_engine, Session
from typing import Optional


class Hero(SQLModel, Table=True):
    """testing sqlmodel"""
    id: Optional[int] = Field(default=None, primary_key=True)  # 修正类型声明
    name: str
    secret_name: str
    age: Optional[int] = None


hero_1 = Hero(name="Deadpond", secret_name="Dive Wilson")
hero_2 = Hero(name="Spider-Boy", secret_name="Pedro Parqueador")
hero_3 = Hero(name="Rusty-Man", secret_name="Tommy Sharp", age=48)

engine = create_engine("sqlite:///database.db")

SQLModel.metadata.create_all(engine)
with Session(engine) as s:
    s.add(hero_1)
    s.add(hero_2)
    s.add(hero_3)
    s.commit()

验证说明 #

运行修正后的代码，会自动生成database.db SQLite数据库文件，三个Hero实例会被正确插入到hero表中。

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