Python 3.12 移除了 u# 等基于 Py_UNICODE 的 C-API 解析格式，本文详解如何在不修改 Python 层调用的前提下，安全、高效地迁移旧代码以兼容新版本。
python 3.12 移除了 `u#` 等基于 `py_unicode` 的 c-api 解析格式，本文详解如何在不修改 python 层调用的前提下，安全、高效地迁移旧代码以兼容新版本。
在 Python 3.12 中，C 扩展开发中长期依赖的 u#（用于解析 Unicode 字符串并获取 Py_UNICODE* 指针及长度）已被正式移除。这一变更源于 Py_UNICODE 类型及其底层 wchar_t 表示的全面弃用——Python 自 3.3 起已转向更健壮、跨平台一致的 UTF-8 内部表示，而 u# 所代表的宽字符接口不再符合现代 Unicode 抽象模型。
✅ 推荐迁移方案：使用 s# + PyUnicode_AsWideCharString
虽然 s# 返回的是 UTF-8 编码的 char* 和长度，但它完全支持所有合法 Unicode 字符串输入 （包括含 emoji、中文、组合字符等），且是 Python 3.12 中最直接、最安全的替代入口。若业务逻辑 必须依赖 wchar_t*（即原 Py_UNICODE*）格式的宽字符缓冲区（例如对接旧版 Windows API、第三方 C 库或遗留文本处理函数），则应分两步实现：
- 先用 s# 安全提取 Python 字符串对象；
- 再调用 PyUnicode_AsWideCharString() 将其转换为 wchar_t* 缓冲区。
以下是完整迁移示例：
static PyObject * foo(PyObject *self, PyObject *args) {const char *utf8_bytes; Py_ssize_t utf8_len; // ✅ 第一步：用 s# 安全接收任意 Unicode 字符串（兼容 str/bytes）if (!PyArg_ParseTuple(args, "s#", &utf8_bytes, &utf8_len)) {return NULL; // 自动设置 TypeError 或其他异常} // ✅ 第二步：从 Python 字符串对象构造 wchar_t*（注意：需先获取对象）// 因为 s# 不提供 PyObject*，我们改用 O! + 显式转换（更健壮）PyObject *py_str = NULL; if (!PyArg_ParseTuple(args, "O!", &PyUnicode_Type, &py_str)) {return NULL;} Py_ssize_t wide_len; wchar_t *wide_buffer = PyUnicode_AsWideCharString(py_str, &wide_len); if (wide_buffer == NULL) {// ❗ 转换失败（如内存不足、无法编码为 wchar_t），异常已由 C-API 设置 return NULL;} // ? 此处可安全使用 wide_buffer 和 wide_len（单位：wchar_t 个数）// 示例：打印长度或传递给旧版 wchar_t 接口 printf("Wide string length: %zdn", wide_len); // ⚠️ 关键：必须手动释放，否则内存泄漏！PyMem_Free(wide_buffer); Py_RETURN_NONE; }⚠️ 注意事项与最佳实践
- 不要尝试强制类型转换 ：s# 返回的 char* 是 UTF-8，* 绝不可将其 `(wchar_t)` 强转使用 **——这将导致乱码、越界访问甚至崩溃。
- PyUnicode_AsWideCharString 的行为说明：
- 返回的 wchar_t* 缓冲区以 结尾（null-terminated），长度 wide_len 不包含结尾 ；
- 若输入字符串为空，返回非 NULL 的空缓冲区（wide_len == 0）；
- 必须配对调用 PyMem_Free()；不可用 free() 或 delete。
- 性能考量：该函数会执行一次完整的 Unicode 编码转换（UTF-8 → wchar_t），对超长字符串有开销。如高频调用且无需 wchar_t，应优先重构逻辑以直接操作 PyUnicodeObject* 或 UTF-8 数据。
- 替代思路（推荐长期演进）：彻底放弃 wchar_t 依赖，改用 PyUnicode_16BitAs… / PyUnicode_32BitAs… 或 PyUnicode_ReadChar() 等现代 Unicode API，实现零拷贝、按需访问。
✅ 总结
u# 的移除不是功能倒退，而是 Python C-API 向更可靠、更可移植的 Unicode 模型演进的关键一步。对于必须保留宽字符接口的场景，PyUnicode_AsWideCharString 是官方指定、语义明确的替代方案；而对于新开发或重构项目，应主动拥抱 UTF-8 原生处理范式，从根本上规避宽窄字符转换开销与平台差异风险。迁移时务必同步更新内存管理逻辑，并通过充分测试验证多语言边界用例（如 surrogates、BMP 外字符、NFD/NFC 归一化字符串）。
立即学习“Python 免费学习笔记（深入）”；
