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

Python 3.12 C-API 迁移指南：替代已移除的 u# 格式字符

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 Hardener
通过完整的安全审查、代码整洁重构、健壮的错误处理、正确的日志记录以及完整的文档字符串覆盖，强化 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）