Python tokenize.detect_encoding 怎样识别源文件编码声明

遇到 Python 源文件的中文注释、历史编码或文件头声明时，真正容易出错的地方不是“把字符串转成什么编码”，而是解码之前如何识别编码。tokenize.detect_encoding 接收返回字节的 readline 函数，最多读取两行，返回编码名称和已经读到的原始字节行。

官方资料：https://docs.python.org/3/library/tokenize.html

它的判断范围很明确：先看 UTF-8 BOM，再看符合 PEP 263 的编码声明；两者冲突抛出 SyntaxError；都没有时返回 utf-8。下面按一次“读取源文件后中文内容解码失败”的故障复盘，把这条判断链拆开。

问题现场：源文件还没解码，编码已经影响后续读取

假设一个工具要扫描 Python 文件中的注释，但它先用错误的编码把整个文件读成字符串，随后才寻找 # coding:。这时声明本身已经失去作用，中文注释可能先触发解码异常，或者被错误解释。根因在于编码声明属于字节层面的元信息，不能等到文本解码完成后再补救。

Python 的 tokenize.tokenize 也沿用这套识别逻辑；如果只是要按正确编码打开文件，可以直接使用 tokenize.open。下面这个最小写法保留了未解码的输入：

from io import BytesIO
from tokenize import detect_encoding

# 这里模拟尚未解码的 Python 源文件，声明位于第一行
source = b"# coding: latin-1\nprint('ready')\n"

# readline 必须逐行返回 bytes，不能先 decode 成 str
encoding, consumed_lines = detect_encoding(BytesIO(source).readline)
print(encoding)
print(consumed_lines)

输出中的 encoding 是后续解码应使用的名称，consumed_lines 是函数为了判断编码而读出的原始行。它们不是已经完成的全文内容，也不代表函数扫描了整个文件。

读取边界：为什么最多只看两行

编码声明按照 PEP 263 约定只能出现在第一行或第二行；第一行还可能是 Unix shebang。于是 detect_encoding 不需要把整个文件读入内存：它通过传入的 readline 最多取两次数据，找到声明就返回，读不到声明则使用默认值。

这里有两个边界需要记住：

• 传入的回调要像文件对象的 readline() 一样工作，每次返回一行 bytes；返回 str 会破坏它的输入约定。
• 返回的已读行仍是原始字节，调用方可以把它们交给后续的 tokenizer，避免为了探测编码而重复读取底层流。

from pathlib import Path
from tokenize import detect_encoding

def source_encoding(path: str) -> str:
    # 以二进制方式打开，确保编码声明在解码前仍可见
    with Path(path).open("rb") as handle:
        encoding, _ = detect_encoding(handle.readline)
        return encoding

print(source_encoding("example.py"))

BOM、编码声明和默认 UTF-8 如何落到结果

判断结果可以压缩成四种情况：

因此，看到 utf-8-sig 时不要误以为文件声明了一个特殊业务编码；它说明检测到了 UTF-8 BOM。反过来，普通的 utf-8 结果也不能证明文件一定写了 # coding: utf-8，因为没有任何声明时同样会得到这个默认值。

修复动作：按场景选择 detect_encoding 或 tokenize.open

如果程序需要自己接管字节流，使用 detect_encoding(handle.readline)，然后基于返回的编码完成后续读取。若目标只是“用 Python 识别的编码打开一个源文件”，优先使用 tokenize.open(filename)，官方文档明确说明它会调用同一套检测逻辑。

import tokenize

def read_source(path: str) -> str:
    # tokenize.open 会根据 BOM 或编码声明选择文本编码
    with tokenize.open(path) as handle:
        return handle.read()

text = read_source("example.py")
print(text[:40])

复查时按这个顺序看：调用回调是否返回 bytes；声明是否位于前两行；是否同时存在不一致的 BOM 和声明；最后确认调用方是否把 utf-8-sig、声明编码和默认 utf-8 当成了同一个事实。这样可以把“中文文件打不开”的表象，收敛到可定位的输入边界。

几个容易混淆的边界

• 不要把 generate_tokens 当成同一个入口。它接收返回字符串的 readline，并且不会产生 ENCODING token；需要识别源文件编码时，应从字节入口开始。
• 不要把示例中的已读行当成全文缓存。函数只为判断编码读取有限行，后续 tokenizer 或文件读取仍需处理剩余内容。
• 不要吞掉冲突异常。如果 BOM 与声明不一致，静默选一个编码会让同一文件在不同工具中得到不同结果，应该保留 SyntaxError 并修正文件头。

常见问题

detect_encoding 没有编码声明时返回什么？

返回 utf-8。这表示 Python 源文件在没有额外声明时采用默认 UTF-8，并不表示函数从文件中读取到了一个显式的 UTF-8 标记。

为什么传入文本文件的 readline 不合适？

因为检测需要在解码前查看 BOM 和编码声明，接口约定回调返回的是每行原始 bytes。已经解码成 str 后，检测阶段就失去了区分原始字节信号的条件。

归根结底，tokenize.detect_encoding 解决的是“先识别、后解码”的源文件入口问题：最多看两行，优先处理 BOM 和编码声明，冲突时报错，无声明时回到 UTF-8。掌握这四个边界，便能在自定义源码扫描器和普通文件读取之间做出稳定选择。