Python 3.12 移除了 u# 等基于 Py_UNICODE 的旧式 Unicode 解析格式，本文详解如何在不修改 Python 层调用的前提下，安全、高效地迁移 C 扩展中依赖 u# 的字符串解析逻辑。
python 3.12 移除了 `u#` 等基于 `py_unicode` 的旧式 unicode 解析格式，本文详解如何在不修改 python 层调用的前提下，安全、高效地迁移 c 扩展中依赖 `u#` 的字符串解析逻辑。
在 Python 3.12 中，C API 正式废弃并移除了所有以 u 和 Z 开头的格式字符（如 u, u#, Z, Z#），原因是其底层依赖已被弃用的 Py_UNICODE 类型（等价于 wchar_t，但语义模糊、平台行为不一致）。这意味着以下经典写法将编译失败或运行时报错：
static PyObject *
foo(PyObject *self, PyObject *args) {
Py_UNICODE *input; // ❌ 已弃用类型
Py_ssize_t length;
if (!PyArg_ParseTuple(args, "u#", &input, &length)) { // ❌ 'u#' 格式字符不存在
return NULL;
}
// ... 使用 input
}✅ 正确迁移路径：两步走策略
第一步：用 s# 安全接收 Unicode 字符串（推荐默认方案）
尽管 s# 原本用于字节串（bytes），但它完全兼容 Unicode 字符串对象——当传入 str 时，PyArg_ParseTuple 会自动将其编码为 UTF-8，并返回 char* + 长度。这是最轻量、最符合现代 Python Unicode 模型的做法：
static PyObject *
foo(PyObject *self, PyObject *args) {
const char *utf8_bytes;
Py_ssize_t size;
if (!PyArg_ParseTuple(args, "s#", &utf8_bytes, &size)) {
return NULL; // 自动处理 str → UTF-8 / bytes → raw bytes
}
// ✅ 安全使用 utf8_bytes（长度为 size），无需内存管理
// 示例：打印 UTF-8 内容（注意：仅作演示，实际应做错误检查）
printf("UTF-8 string (%zd bytes): %.*s\n", size, (int)size, utf8_bytes);
Py_RETURN_NONE;
}✅ 优势：零额外内存分配、无手动释放负担、跨平台 UTF-8 语义明确、性能最优。
⚠️ 注意：若原有逻辑强依赖 wchar_t 字符数组（如调用 Windows WinAPI 或旧版 ICU），才需第二步。
第二步：按需转换为宽字符（wchar_t*）
当确实需要 wchar_t 表示（例如对接系统 API 或遗留代码），应显式调用 PyUnicode_AsWideCharString，它将 str 对象转换为以 null 结尾的 wchar_t* 缓冲区：
static PyObject *
foo(PyObject *self, PyObject *args) {
PyObject *str_obj;
// 先用通用格式接收任意字符串对象（str 或 bytes）
if (!PyArg_ParseTuple(args, "O!", &PyUnicode_Type, &str_obj)) {
return NULL;
}
// 转换为 wchar_t*（自动处理编码、分配内存）
Py_ssize_t wlen;
wchar_t *wstr = PyUnicode_AsWideCharString(str_obj, &wlen);
if (wstr == NULL) {
// ❗ 转换失败（如内存不足或无法表示），异常已设置
return NULL;
}
// ✅ 此时 wstr 是有效的 wchar_t 数组，长度为 wlen（不含结尾 L'\0'）
// 注意：wstr 末尾有隐式 L'\0'，但 wlen 不包含它（与 u# 时代一致）
// ... 执行依赖 wchar_t 的业务逻辑 ...
// ✅ 必须释放！PyMem_Free 是唯一正确方式
PyMem_Free(wstr);
Py_RETURN_NONE;
}? 关键要点：
立即学习“Python免费学习笔记（深入）”；
- PyUnicode_AsWideCharString 返回的内存必须由 PyMem_Free() 释放（非 free() 或 PyMem_Del()）；
- wlen 表示 Unicode 字符数（即 wcslen(wstr)），不包括结尾空字符；
- 若输入是 bytes，该函数会尝试按默认编码（locale.getpreferredencoding()）解码，失败则报 UnicodeDecodeError；
- 该函数在 Python 3.2+ 即已存在，完全兼容 3.12，是官方推荐替代方案。
? 总结与最佳实践
| 场景 | 推荐方案 | 是否需手动内存管理 |
|---|---|---|
| 通用文本处理（日志、解析、网络传输等） | s# + UTF-8 | 否 |
| 需调用 wchar_t 接口（Windows API、旧库） | PyUnicode_AsWideCharString | 是（PyMem_Free） |
| 需精确控制编码（如强制 GBK） | PyUnicode_AsEncodedString + PyBytes_AsStringAndSize | 是（Py_DECREF） |
最后提醒：
- 彻底避免使用 Py_UNICODE 相关类型和宏（如 PyUnicode_AsUnicode），它们已在 3.12 中删除；
- 所有字符串操作优先面向 PyObject*（PyUnicode_Check + PyUnicode_* 系列函数），而非假设底层表示；
- 在升级前，务必对 C 扩展进行完整测试，尤其关注多语言字符串（中文、emoji、组合字符）的边界行为。
遵循上述方法，即可平滑完成 Python 3.12 C API 的 Unicode 迁移，兼顾兼容性、安全性和可维护性。
