__format__ 方法必须正确定义才能响应格式说明符；常见错误包括签名错误、返回值非字符串、父类干扰、格式说明符被提前消费等。

Python 类要支持 f"{obj}" 或 format(obj, spec)，必须实现 __format__ 方法；不实现就只能走 __str__ 或 __repr__ 回退逻辑，无法响应格式说明符（如 :.2f、10）。</code:></strong></p> <h3>为什么 <code>__format__ 不生效？常见错误现象

写了 __format__ 却发现 f"{obj:.2f}" 仍报错 ValueError: Unknown format code 'f' for object of type 'xxx'，通常因为：

• __format__ 方法签名错误：必须接收 self 和 format_spec: str 两个参数，少一个或类型不对都会跳过调用
• 返回值不是 str：哪怕返回 bytes 或 None，Python 都会抛出格式化错误
• 父类干扰：如果继承自内置类型（如 float、int），且未显式覆盖 __format__，Python 可能直接用父类逻辑，忽略你的实现
• 格式说明符被提前消费：比如在 __str__ 里误用了 format() 而没传 format_spec，导致逻辑错位

__format__ 的参数差异与典型使用场景

format_spec 是字符串，内容完全由格式化语法决定，比如 f"{obj: 中的 <code> 就是传入的 <code>format_spec。它没有强制结构，全靠你解析 —— Python 不帮你拆解对齐、宽度、精度这些语义。

python-script-generator

快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。

下载

• 数值类对象（如自定义向量、金额）常需支持 :.2f、:e 等，此时应委托给 float(self) 或内部数值再调用 format(..., format_spec)
• 字符串类包装（如带颜色标记的文本）可能只关心对齐和填充，如 :>20，可复用 str(self).rjust(20)
• 日期/时间类建议兼容 ISO 标准缩写，如 :iso → self.dt.isoformat()，:date → self.dt.date().isoformat()
• 空 format_spec（即 f"{obj}"）代表“默认格式”，通常应等价于 str(self)，不要抛异常

性能与兼容性要注意什么？

__format__ 是高频调用路径，尤其在日志、表格渲染中反复格式化。别在其中做重操作：

立即学习“Python免费学习笔记（深入）”；

• 避免每次调用都重新解析 format_spec 正则 —— 如果格式种类固定（如只支持 hex、bin、dec），用 if/elif 分支比正则快得多
• 不要在 __format__ 里触发 I/O 或网络请求，格式化不是加载数据的时机
• 兼容旧代码：如果类已有 __str__，确保 __format__("", "") 返回结果与 str(obj) 一致，否则 print(obj) 行为可能突变
• 注意 !r、!s 等转换标志（conversion）是在格式化前处理的，不会进 __format__，它们只影响 __repr__ 和 __str__

最易被忽略的一点：格式说明符是纯字符串，没有任何预定义含义。Python 不会帮你判断 .2f 是否合法，也不会自动截断小数位 —— 这些都得你手动解析、校验、委托。写完记得测 format(obj, "invalid") 是否抛出合适异常，而不是静默返回奇怪字符串。