Python codecs 的转换类型：rot_13 明明能查到，为什么字符串 encode 却拒绝它
维护一段旧文本工具时，看到注册表里有rot_13，于是直接调用字符串的encode，结果得到LookupError。换成codecs.encode却立即成功。错误名称很容易让人以为机器缺少编码器，实际关键是调用接口要求什么类型：字符串encode需要产生字节，ROT13转换的结果仍然是字符串。
本文在Linux、CPython 3.12.14实跑。保存为demo.py并执行python3 demo.py即可，所有内容只在内存中流转。输入特意混合英文、标点和一个汉字，观察ROT13的字符替换与UTF-8字节表示分别发生在哪一步，不读写文件，也不注册自定义codec。
AI生成的概念示意图：文字符号先发生同类替换，再经过另一道关口变成小方块，表示文本转换与字节编码是两个阶段。
完整程序与本次实跑
完整可运行程序
import codecs
text = "Hello, 云!"
transformed = codecs.encode(text, "rot_13")
assert transformed == "Uryyb, 云!"
assert isinstance(transformed, str)
print("transform:", transformed)
print("transform type:", type(transformed).__name__)
try:
text.encode("rot_13")
except LookupError as exc:
print("str.encode error:", type(exc).__name__)
else:
raise AssertionError("text transform unexpectedly produced bytes")
wire = transformed.encode("utf-8")
print("wire type:", type(wire).__name__)
print("wire hex:", wire.hex())
restored = codecs.decode(wire.decode("utf-8"), "rot_13")
assert restored == text
print("round trip:", restored == text)
hex_bytes = codecs.encode(b"AB", "hex_codec")
assert hex_bytes == b"4142"
print("hex transform:", hex_bytes, type(hex_bytes).__name__)
assert codecs.decode(hex_bytes, "hex_codec") == b"AB"
print("codec exists:", codecs.lookup("rot_13").name)本次实际输出（以下为结果，不是程序）
transform: Uryyb, 云! transform type: str str.encode error: LookupError wire type: bytes wire hex: 55727979622c20e4ba9121 round trip: True hex transform: b'4142' bytes codec exists: rot-13
通用codec接口不承诺输出一定是字节
transform显示Uryyb，汉字与标点保持原样；transform type明确为str。codecs.encode调用注册的转换器，并允许它实现文本到文本等转换，不强行把结果限定为bytes。ROT13把拉丁字母旋转十三个位置，用相同转换再做一次就能还原。
最后一行codec exists打印rot-13，证明查找确实成功。中间str.encode抛出LookupError，并不与这个事实矛盾：名字存在和这个名字能否用于当前接口，是两项检查。遇到类似错误，先查转换的输入输出类型，通常比重新安装包更有针对性。
字符串encode负责跨入字节世界
wire由transformed.encode("utf-8")产生，类型才变成bytes。十六进制输出中，英文字母和标点对应各自字节，汉字对应多个UTF-8字节。这个步骤负责文本的外部表示，前面的ROT13只改变文本内容；把两步混成一次调用，就会失去各自清楚的类型边界。
如果下游接口要求二进制消息，应传wire；如果界面要显示变换后的文字，应传transformed。不要为了满足一个报错而到处补encode或decode。沿变量名标出“文本”“变换后文本”“传输字节”，可以直接检查某一步是不是重复编码或解码顺序反了。
往返必须按相反顺序撤销两步
还原时先把wire按UTF-8解码成字符串，再交给ROT13的decode，round trip因此为True。把字节直接交给这个文本转换器，不符合其输入契约；反过来，只做UTF-8解码也只能拿到已经替换过字母的文字，原英文仍未恢复。
本例ROT13的编码与解码效果相同，但不要把这个特点推广到其它转换。设计多阶段流水线时，应记录每一步的方向和中间类型，并按逆序恢复。测试中同时检查最终内容和中间类型，比只检查最后打印出来“看着正常”更容易发现边界错误。
字节到字节也是另一种合法codec
hex transform得到b'4142'，类型仍为bytes。输入AB两个字节，被转换成表示其十六进制的四个ASCII字节。这个例子说明注册表里的codec并非全部是字符集编码，同一个encode动词可能对应不同类型的转换。
若要在界面展示十六进制文字，可以选择明确返回字符串的接口；若继续走二进制转换链，则保留bytes更直接。不要把b前缀当成正文的一部分，它是Python展示字节对象的表示法。写入其它协议时应依据对象内容处理，而不是把repr结果再当有效载荷。
把类型合同留在接口旁边
通用包装函数若允许调用方任意填写codec名称，就不能同时承诺所有输出都是bytes。更稳妥的做法是限制允许的转换种类，明确每种输入与输出，或在转换后执行类型检查并返回可解释错误。查找成功只证明名称注册，不能证明它适合写文件、发消息或接入某个流接口。
ROT13只是演示文本转换，不能用于保护秘密或替代加密。本文也没有讨论压缩、认证与字符规范化。修复这类故障的关键，是先把内容替换、字符编码和展示表示分开，再选各自类型契约匹配的API；仅仅把异常吞掉会让错误流向后面的接口。
参考资料
官方资料核验于2026年10月2日；上述输出来自本次固定输入实跑，退出码为0。
