__format__ 方法必须返回字符串，不能返回 none；它接收原始 format_spec 字符串，需手动解析并处理所有分支，空 format_spec 时建议返回 str(self)。
__format__ 方法必须返回字符串，不能返回 None
Python 的 __format__ 方法被 format() 函数和 f-string 调用时，**必须显式返回一个 str 类型值**。如果忘记 return 或返回了 None，会直接抛出 TypeError: non-empty format string passed to object.__format__（即使格式化字符串为空也会触发）。
- 常见错误：在方法里只做 print 或 logging，没写 return
- 正确做法：所有分支都返回
str，包括处理未知 format_spec 的兜底逻辑 - 示例错误写法：
def __format__(self, format_spec): print(f"Formatting with {format_spec}") # 缺少 return → TypeError - 推荐兜底：用
return str(self)或return self.__str__()
format_spec 参数是纯字符串，不自动解析成数字或布尔值
__format__ 接收的 format_spec 是原始字符串，比如 f"{obj:.2f}" 传进来的是 ".2f"，f"{obj!s:upper}" 传进来的是 "upper" —— 它不会帮你转成 float 或调用 .upper()，全得自己拆解和判断。
- 不要假设
format_spec是某种类型；用if format_spec == "hex"或正则匹配（如re.match(r'^\.(\d+)f$', format_spec)）来解析 - 支持标准格式码（如
d,x,e）需手动实现，Python 不会代理给int()或float() - 建议提前约定好自定义格式码（如
"short","debug"），避免和内置格式冲突
与 __str__ 和 __repr__ 的协作关系要理清
__format__ 不替代 __str__ 或 __repr__，而是补充它们：当显式使用格式化（如 format(obj, spec) 或 f"{obj:spec}"）时才触发；否则仍走 __str__（print）或 __repr__（交互式显示）。
- 不要在
__format__里重复实现__str__逻辑，除非 format_spec 为空字符串（f"{obj:}"）——此时可返回str(self) - 如果希望空 format_spec 行为等同于
__str__，明确写if not format_spec: return str(self) - 调试时可用
print(repr(format_spec))看实际传入值，避免因空格或不可见字符误判
在 f-string 中触发 __format__ 需带格式说明符
f-string 只有在花括号内写了冒号（:）才会调用 __format__。写 f"{obj}" 走的是 __str__，而 f"{obj:}"、f"{obj:!s}"、f"{obj:json}" 才会进 __format__。
-
f"{obj:}"传入空字符串""给format_spec -
f"{obj:!s}"先调用__str__再格式化，不进__format__ -
f"{obj:debug}"才真正把"debug"传给__format__ - 测试时别漏掉冒号 —— 这是最常见的“写了 __format__ 却没生效”的原因
注意：format_spec 解析没有统一标准库工具，不同项目往往各自实现一套简化解析逻辑；越早定义清晰的格式码语义，后期维护成本越低。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
