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

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

Python 3.12 移除了 u# 等 Unicode 相关 C-API 格式符，本文详解如何在不依赖 Py_UNICODE* 的前提下安全解析 Unicode 字符串参数，并提供兼容、可维护的迁移方案。

python 3.12 移除了 `u#` 等 unicode 相关 c-api 格式符，本文详解如何在不依赖 `py_unicode*` 的前提下安全解析 unicode 字符串参数，并提供兼容、可维护的迁移方案。

在 Python 3.12 中，C 扩展开发中曾广泛使用的 u#（用于解析 Py_UNICODE* + 长度）已被正式移除，原因是其底层依赖已废弃的 Py_UNICODE 类型（等价于 wchar_t，且跨平台行为不一致）。这意味着如下经典代码将无法编译或运行：

static PyObject *
foo(PyObject *self, PyObject *args) {
    Py_UNICODE *input;      // ❌ 错误：Py_UNICODE 已弃用
    Py_ssize_t length;

    if (!PyArg_ParseTuple(args, "u#", &input, &length)) {
        return NULL;
    }
    // ...
}

✅ 推荐迁移路径：优先使用 s# + UTF-8，按需转换为宽字符

关键事实：s# 格式符在 Python 3.x 中完全支持 Unicode 字符串——它会自动将 str 对象编码为 UTF-8 字节序列，并返回 char* 和长度。绝大多数场景（如日志、序列化、与 C 库交互）可直接使用 UTF-8，无需宽字符。这是最轻量、最安全、最符合现代 Python 设计的选择。

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

    if (!PyArg_ParseTuple(args, "s#", &utf8_bytes, &len)) {
        return NULL;
    }

    // ✅ 安全使用 utf8_bytes[0..len-1] —— 已验证为合法 UTF-8
    printf("Received %zd UTF-8 bytes: %.*s\n", len, (int)len, utf8_bytes);
    // ... 其他逻辑
    Py_RETURN_NONE;
}

⚠️ 注意：s# 不会接受 bytes 对象（除非显式启用 y# 或使用 O& 自定义转换器），它专为 str 设计，内部自动完成 str → UTF-8 转换，并保证结果有效。

? 若必须使用 wchar_t*（如调用 Windows API 或遗留 wchar 接口）

当确实需要 wchar_t*（即宽字符缓冲区）时，不应再尝试复用旧的 u# 行为，而应通过 PyUnicode_AsWideCharString() 显式转换。该函数返回新分配的 wchar_t* 缓冲区，调用者负责释放：

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

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

下载

static PyObject *
foo(PyObject *self, PyObject *args) {
    PyObject *str_obj = NULL;

    // Step 1: 使用 O 格式符获取原始 str 对象（不转换）
    if (!PyArg_ParseTuple(args, "O", &str_obj)) {
        return NULL;
    }

    // Step 2: 验证是否为字符串
    if (!PyUnicode_Check(str_obj)) {
        PyErr_SetString(PyExc_TypeError, "expected str");
        return NULL;
    }

    // Step 3: 转换为 wchar_t*（含空终止符）
    Py_ssize_t size;
    wchar_t *wchar_buf = PyUnicode_AsWideCharString(str_obj, &size);
    if (!wchar_buf) {
        // ❗ 转换失败（如内存不足或非 BMP 字符在窄 wchar_t 平台）
        return NULL;
    }

    // ✅ 此时 wchar_buf 指向 size 个 wchar_t 的缓冲区（不含末尾 \0？注意文档！）
    // 实际长度为 size；若需空终止，可传 -1 作为 size 参数（见下文说明）

    // ... 使用 wchar_buf 进行业务处理 ...

    // Step 4: 必须手动释放！
    PyMem_Free(wchar_buf);
    Py_RETURN_NONE;
}

? 重要细节说明：

PyUnicode_AsWideCharString(obj, &size) 返回的缓冲区长度为 size，不包含隐式空终止符（即 wchar_buf[size] 未定义）。若需空终止，请传入 &size 并确保后续使用 wcslen 或手动追加 \0。
更安全的空终止用法：wchar_t *buf = PyUnicode_AsWideCharString(obj, NULL); —— 此时函数返回带 \0 结尾的缓冲区，size 可设为 NULL，但需注意 NULL 返回值仍表示错误。
该函数在 wchar_t 为 2 字节的平台（如 Windows MSVC）上对超出 BMP 的字符（如 emoji）可能失败，此时应改用 PyUnicode_AsUCS4() 或 UTF-8 路径。

? 总结与最佳实践

场景	推荐方案	关键优势
通用文本处理、网络/磁盘 I/O、多数 C 库	s# + UTF-8 char*	零拷贝（仅编码）、跨平台一致、无内存管理负担、性能最优
必须调用 wchar_t 接口（如 Windows CreateFileW）	PyUnicode_AsWideCharString() + PyMem_Free()	明确所有权、错误可检测、符合 3.12+ 规范
需要 UCS-4 精确码点访问（如文本分析）	PyUnicode_AsUCS4() 或 PyUnicode_ReadChar()	支持完整 Unicode 空间，规避 wchar_t 平台差异