Python 3.12 C-API迁移指南：替代已移除的 u# 格式符-Python教程-PHP中文网

Python 3.12 移除了 u# 等基于 Py_UNICODE 的旧式 Unicode 解析格式符，需改用 s# 结合 PyUnicode_AsWideCharString() 获取宽字符缓冲区，并注意手动内存管理。

python 3.12 移除了 `u#` 等基于 `py_unicode` 的旧式 unicode 解析格式符，需改用 `s#` 结合 `pyunicode_aswidecharstring()` 获取宽字符缓冲区，并注意手动内存管理。

在 Python 3.12 中，C-API 彻底移除了 u、u#、Z 和 Z# 等依赖已废弃 Py_UNICODE 类型（即 wchar_t 别名）的格式字符。这意味着原有使用 PyArg_ParseTuple(args, "u#", &input, &length) 直接获取 wchar_t* 指针的代码将编译失败或运行时报错 bad-format-character。虽然 Py_UNICODE 本身与 wchar_t 兼容，但关键问题在于：u# 不再存在，且 C-API 不再提供“零拷贝”方式直接暴露内部宽字符串缓冲区。

✅ 推荐迁移路径：两步解耦处理

先用 s# 安全解析 Unicode 字符串为 UTF-8 字节序列（兼容所有 str 输入，包括含非 BMP 字符的字符串）；
*再调用 PyUnicode_AsWideCharString() 显式转换为 `wchar_t` 缓冲区**（按需分配，需手动释放）。

以下是完整迁移示例：

macOS UI 自动化技能包 —— 用 Python 控制你的 Mac

让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限

下载

static PyObject *
foo(PyObject *self, PyObject *args) {
    const char *utf8_bytes;
    Py_ssize_t utf8_len;

    // Step 1: 使用 s# 安全解析 —— 支持任意 str 对象，返回 UTF-8 编码字节和长度
    if (!PyArg_ParseTuple(args, "s#", &utf8_bytes, &utf8_len)) {
        return NULL;
    }

    // Step 2: 将 str 对象转为 wchar_t*（注意：需先从 args 中重新获取 PyObject*）
    // 因为 s# 不提供对象引用，我们需显式提取第一个参数
    PyObject *arg0 = PyTuple_GetItem(args, 0);  // borrowed ref
    if (arg0 == NULL) {
        return NULL;
    }
    if (!PyUnicode_Check(arg0)) {
        PyErr_SetString(PyExc_TypeError, "expected a string");
        return NULL;
    }

    Py_ssize_t wide_len;
    wchar_t *wide_buffer = PyUnicode_AsWideCharString(arg0, &wide_len);
    if (wide_buffer == NULL) {
        // 异常已由 PyUnicode_AsWideCharString 设置，直接返回
        return NULL;
    }

    // ✅ 此时 wide_buffer 是有效的 wchar_t 数组，长度为 wide_len（不含终止 null）
    // 可安全用于原有逻辑（如调用 Windows API、legacy wchar_t 处理函数等）

    // ... your legacy logic using wide_buffer and wide_len ...

    // ⚠️ 必须显式释放：PyUnicode_AsWideCharString 分配的内存由 PyMem_Free 管理
    PyMem_Free(wide_buffer);

    Py_RETURN_NONE;
}

? 关键注意事项

s# 并非“不支持 Unicode”：它接受 str 对象并返回其 UTF-8 编码视图，完全兼容所有合法 Unicode 字符（包括 emoji、中文、代理对等），是 Python 3.x 中推荐的字节级接口。
PyUnicode_AsWideCharString() 返回新分配内存：不同于旧 u# 的零拷贝行为，该函数总是分配堆内存，必须配对调用 PyMem_Free()，否则导致内存泄漏。
避免重复解析：若函数仅需宽字符，可跳过 s#，直接用 PyArg_ParseTuple(args, "O", &obj) 获取 PyObject* 后调用 PyUnicode_AsWideCharString() —— 更简洁且语义清晰。
PyUnicode_AsWideChar() 已弃用：不要使用该函数（它需要预分配缓冲区且易出界），PyUnicode_AsWideCharString() 是其现代替代品，自动计算所需大小并分配。

✅ 总结

迁移到 Python 3.12 的核心原则是：放弃对内部 Py_UNICODE 表示的假设，拥抱显式、安全、可维护的 Unicode 转换流程。u# 的移除并非限制能力，而是推动开发者采用更健壮的 API 模式。通过 s# + PyUnicode_AsWideCharString() 组合，你不仅能平滑升级，还能获得更好的错误隔离性与跨平台一致性（例如，在 Linux/macOS 上 wchar_t 为 4 字节，而旧 Py_UNICODE 在 Windows 上为 2 字节，新方案统一抽象了差异）。