编解码器基类
codecs 模块定义了一系列基类用来定义配合编解码器对象进行工作的接口,并且也可用作定制编解码器实现的基础。

每种编解码器必须定义四个接口以便用作 Python 中的编解码器:无状态编码器、无状态解码器、流读取器和流写入器。 流读取器和写入器通常会重用无状态编码器/解码器来实现文件协议。 编解码器作者还需要定义编解码器将如何处理编码和解码错误。

错误处理方案
为了简化和标准化错误处理,编解码器可以通过接受 errors 字符串参数来实现不同的错误处理方案。 所有标准的 Python 编解码器都定义并实现了以下字符串值:

含义

'strict'

引发 UnicodeError (或其子类);这是默认的方案。 在 strict_errors() 中实现。

'ignore'

忽略错误格式的数据并且不加进一步通知就继续执行。 在 ignore_errors() 中实现。

以下错误处理方案仅适用于 文本编码:

含义

'replace'

使用适当的替换标记进行替换;Python 内置编解码器将在解码时使用官方 U+FFFD 替换字符,而在编码时使用 '?' 。 在 replace_errors() 中实现。

'xmlcharrefreplace'

使用适当的 XML 字符引用进行替换(仅在编码时)。 在 xmlcharrefreplace_errors() 中实现。

'backslashreplace'

使用带反斜杠的转义序列进行替换。 在 backslashreplace_errors() 中实现。

'namereplace'

使用 \N{...} 转义序列进行替换(仅在编码时)。 在 namereplace_errors() 中实现。

'surrogateescape'

在解码时,将字节替换为 U+DC80 至 U+DCFF 范围内的单个代理代码。 当在编码数据时使用 'surrogateescape' 错误处理方案时,此代理将被转换回相同的字节。 (请参阅 PEP 383 了解详情。)

此外,以下错误处理方案被专门用于指定的编解码器:

编解码器

含义

'surrogatepass'

utf-8, utf-16, utf-32, utf-16-be, utf-16-le, utf-32-be, utf-32-le

允许编码和解码代理代码。 这些编解码器通常会将出现的代理代码视为错误。

3.1 新版功能: 'surrogateescape' 和 'surrogatepass' 错误处理方案。

在 3.4 版更改: 'surrogatepass' 错误处理方案现在适用于 utf-16 和 utf-32 编解码器。

3.5 新版功能: 'namereplace' 错误处理方案。

在 3.5 版更改: 'backslashreplace' 错误处理方案现在适用于解码和转换。

允许的值集合可以通过注册新命名的错误处理方案来扩展:

codecs.register_error(name, error_handler)
在名称 name 之下注册错误处理函数 error_handler。 当 name 被指定为错误形参时,error_handler 参数所指定的对象将在编码和解码期间发生错误的情况下被调用,

对于编码操作,将会调用 error_handler 并传入一个 UnicodeEncodeError 实例,其中包含有关错误位置的信息。 错误处理程序必须引发此异常或别的异常,或者也可以返回一个元组,其中包含输入的不可编码部分的替换对象,以及应当继续进行编码的位置。 替换对象可以为 str 或 bytes 类型。 如果替换对象为字节串,编码器将简单地将其复制到输出缓冲区。 如果替换对象为字符串,编码器将对替换对象进行编码。 对原始输入的编码操作会在指定位置继续进行。 负的位置值将被视为相对于输入字符串的末尾。 如果结果位置超出范围则将引发 IndexError。

解码和转换的做法很相似,不同之处在于将把 UnicodeDecodeError 或 UnicodeTranslateError 传给处理程序,并且来自错误处理程序的替换对象将被直接放入输出。

之前注册的错误处理方案(包括标准错误处理方案)可通过名称进行查找:

codecs.lookup_error(name)
返回之前在名称 name 之下注册的错误处理方案。

在处理方案无法找到时将引发 LookupError。

以下标准错误处理方案也可通过模块层级函数的方式来使用:

codecs.strict_errors(exception)
实现 'strict' 错误处理方案:每个编码或解码错误都会引发 UnicodeError。

codecs.replace_errors(exception)
实现 'replace' 错误处理方案 (仅用于 文本编码):编码错误替换为 '?' (并由编解码器编码),解码错误替换为 '\ufffd' (Unicode 替换字符)。

codecs.ignore_errors(exception)
实现 'ignore' 错误处理方案:忽略错误格式的数据并且不加进一步通知就继续执行。

codecs.xmlcharrefreplace_errors(exception)
实现 'xmlcharrefreplace' 错误处理方案 (仅用于 文本编码 的编码过程):不可编码的字符将以适当的 XML 字符引用进行替换。

codecs.backslashreplace_errors(exception)
实现 'backslashreplace' 错误处理方案 (仅用于 文本编码):错误格式的数据将以带反斜杠的转义序列进行替换。

codecs.namereplace_errors(exception)
实现 'namereplace' 错误处理方案 (仅用于 文本编码 的编码过程):不可编码的字符将以 \N{...} 转义序列进行替换。

3.5 新版功能.