如何自动将Python dataclass/Pydantic模型按Go结构体风格对齐注释

Python的dataclass是非常实用的特性，能以简洁优雅的方式定义类，基础使用示例：

from dataclasses import dataclass

@dataclass
class InventoryItem:
    """Class for keeping track of an item in inventory."""
    name: str
    unit_price: float
    quantity_on_hand: int = 0

    def total_cost(self) -> float:
        return self.unit_price * self.quantity_on_hand

基于Python类型注解机制，还有很多工具可以实现类似其他语言结构体的类定义效果，Pydantic就是典型代表，示例：

from pydantic import BaseModel


class User(BaseModel):
    id: int
    name = 'John Doe'
    signup_ts: Optional[datetime] = None
    friends: List[int] = []

高频使用Pydantic对接非规范API时，经常需要给每个字段加行尾注释做自文档化，但默认格式下字段名、类型、注释错落不齐，可读性很差，原始代码示例：

class G6A(BaseModel):
    transaction_id: items.TransactionReference # Transaction Id
    mpan_core: items.MPAN # MPAN Core
    registration_date: items.CallistoDate # Registration Date
    action_required: G6AAction # Action Required

参考Go语言结构体的对齐风格，把字段名、类型、行尾注释按三列对齐后排版可读性会大幅提升，对齐后效果：

class G6A(BaseModel):
    transaction_id:     items.TransactionReference  # Transaction Id
    mpan_core:          items.MPAN                  # MPAN Core
    registration_date:  items.CallistoDate          # Registration Date
    action_required:    G6AAction                   # Action Required

Go语言结构体的典型对齐风格参考：

type T struct {
    name    string // name of the object
    value   int    // its value
}

可用工具与实现方案 #

你排查过的autopep8、black等主流通用Python格式化工具，原生设计遵循PEP8最小改动原则，不会主动做跨行的列对齐操作，默认不支持该效果，可通过以下方式实现需求：

• 使用pyink：Google基于Black二次开发的格式化工具，内置类型注解、行尾注释对齐能力，在配置中开启align_annotations、align_trailing_comments选项后，即可自动对dataclass、Pydantic类的字段做对齐排版，和Black的格式规则兼容性极高。
• 使用ruff：高性能Python linter+格式化工具，0.1版本后的格式化模块支持自定义对齐规则，开启注解对齐、尾注释对齐规则后即可实现三列对齐效果，格式化速度远快于传统Python格式化工具，适合大型项目使用。
• 使用编辑器对齐插件：VS Code、PyCharm等IDE都有支持按分隔符对齐的插件，选中需要调整的类字段块后，触发对齐功能按:、#两个分隔符做列对齐即可，不需要修改项目全局格式化配置，适合仅对特定模型类做对齐的场景。
• 自定义AST脚本实现：如果现成工具的对齐规则不符合个人习惯，可以写简单的Python脚本，通过AST遍历定位所有dataclass、Pydantic模型类，拆分每行的字段名、类型、注释三部分，按列最大长度补空格对齐后写回文件，几十行代码即可实现，还可以自定义列间距、缩进规则，完全适配个人排版习惯。

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