CPython 3.19 C API 废弃解读PEP 456 字符串哈希方案定制支持Embedder Support的移除【免费下载链接】cpythonThe Python programming language项目地址: https://gitcode.com/GitHub_Trending/cp/cpython本篇技术解读基于 CPython 仓库中的废弃公告文件 c-api-pending-removal-in-3.19.rst。该文档宣布在 Python 3.19 中将移除「PEP 456 为嵌入方embedder提供的字符串哈希方案定义支持」。读完后你将理解 PEP 456 曾向 C 嵌入层暴露了哪些哈希定制接口、这些接口在 CPython 源码中的具体落点以及嵌入式集成方自定义 Python 宿主应用、C 扩展构建系统在 3.19 到来前应如何完成迁移。一、公告本身一行声明背后的含义CPython 仓库在Doc/deprecations/目录下维护了一批按目标版本归类的 C API 废弃追踪文档。其中 c-api-pending-removal-in-3.19.rst 的完整内容只有一条条目Pending removal in Python 3.19 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * :pep:456 embedders support for the string hashing scheme definition.这条声明的技术含义是PEP 456 当年除了改变解释器内部的字符串哈希实现还额外开放了一组「让嵌入方在编译期定义字符串哈希方案」的 C 宏与 API。这一组面向 embedder 的定制能力而非 PEP 456 的哈希随机化本身将要在 3.19 中被删除。二、背景PEP 456 的 embedder 接口在 CPython 中的落点PEP 456随 Python 3.4 引入把 Python 字符串的哈希从固定的 DJBX33A 变体更换为抗碰撞攻击的 SipHash 系列算法并引入哈希随机化。与此同时它向嵌入层开放了三个定制维度全部集中在公开头文件 pyhash.h 中2.1 算法选择Py_HASH_ALGORITHM与四个取值pyhash.h 中定义了可选算法枚举及默认值选择逻辑#define Py_HASH_EXTERNAL 0 #define Py_HASH_SIPHASH24 1 #define Py_HASH_FNV 2 #define Py_HASH_SIPHASH13 3 #ifndef Py_HASH_ALGORITHM # ifndef HAVE_ALIGNED_REQUIRED # define Py_HASH_ALGORITHM Py_HASH_SIPHASH13 # else # define Py_HASH_ALGORITHM Py_HASH_FNV # endif #endif默认情况下支持对齐内存访问的平台使用 SipHash13不支持的平台回退到 FNV头文件注释明确指出「The values for Py_HASH_* are hard-coded in the configure script」即算法值由构建配置固化嵌入方此前可以通过在编译定义中强制Py_HASH_ALGORITHM例如设为Py_HASH_EXTERNAL来接管字符串哈希的计算。2.2 短字符串优化阈值Py_HASH_CUTOFFpyhash.h 还定义了短字符串快速哈希的截断长度/* Cutoff for small string DJBX33A optimization in range [1, cutoff). * * About 50% of the strings in a typical Python application are smaller than * 6 to 7 chars. However DJBX33A is vulnerable to hash collision attacks. * NEVER use DJBX33A for long strings! */ #ifndef Py_HASH_CUTOFF # define Py_HASH_CUTOFF 0 #elif (Py_HASH_CUTOFF 7 || Py_HASH_CUTOFF 0) # error Py_HASH_CUTOFF must in range 0...7. #endif取值被硬约束在 0..7 区间0 表示禁用短字符串优化越界会在编译期直接报错。注释同时说明了安全权衡短字符串用快速的 DJBX33A、长字符串用 SipHash以在典型负载约一半字符串长度小于 6~7 字符与抗碰撞攻击之间取得平衡。2.3 外部哈希实现注入PyHash_FuncDef真正属于「embedders support for the string hashing scheme definition」的核心 API 位于 cpython/pyhash.h该头文件仅在不定义Py_LIMITED_API时经 pyhash.h 间接包含/* hash function definition */ typedef struct { Py_hash_t (*const hash)(const void *, Py_ssize_t); const char *name; const int hash_bits; const int seed_bits; } PyHash_FuncDef; PyAPI_FUNC(PyHash_FuncDef*) PyHash_GetFuncDef(void);PyHash_FuncDef描述了当前字符串哈希函数指针、算法名称以及哈希位宽/种子位宽PyHash_GetFuncDef()允许嵌入方在运行时查询这些元信息。pyhash.h 的注释还给出了外部注入方式——当Py_HASH_ALGORITHM为Py_HASH_EXTERNAL时嵌入方可提供PyHash_FuncDef PyHash_Func {...};这一声明路径在实现层有直接对应pyhash.c 开头即有#if Py_HASH_ALGORITHM Py_HASH_EXTERNAL分支外部模式下哈希计算委托给嵌入方提供的实现而 SipHash13/SipHash24/FNV 各实现则分别位于该文件后续的条件编译块中。2.4 运行时可观测性sys.hash_info哈希方案的当前状态还通过 C API 暴露到解释器运行时。例如 sysmodule.c 在构建sys.hash_info时会写入 cutoff 值SET_HASH_INFO_ITEM(PyLong_FromLong(Py_HASH_CUTOFF))。从源码结构看一旦 embedder 定制接口移除sys.hash_info中将只反映内置算法的状态不再存在由外部注入的算法名。三、3.19 之后嵌入方还能做什么需要澄清一个关键边界被移除的只是「方案定义/替换」能力而非哈希随机化本身。字符串哈希仍由 CPython 内置算法计算哈希值在不同进程间的随机性继续由PYTHONHASHSEED环境变量控制该机制在官方参考文档 datamodel.rst 中有专门章节说明。对嵌入集成方而言迁移要点如下清理构建定义从 C 编译参数中移除对Py_HASH_ALGORITHM、Py_HASH_CUTOFF的自定义覆盖。这两个宏在 3.19 中不再有「由嵌入方定义方案」的语义价值移除外部哈希实现删除自实现的PyHash_Func变量、PyHash_FuncDef结构填充代码以及任何依赖PyHash_GetFuncDef()返回值的hash_bits/seed_bits字段做分支适配的逻辑替代策略若当初选择Py_HASH_EXTERNAL是为了跨进程/跨版本保证哈希值稳定改用固定PYTHONHASHSEED即可获得等价的确定性若当初是出于性能原因替换为更快但可碰撞的算法3.19 后该权衡不再开放给嵌入方需接受内置算法的性能特征注意稳定 ABI 面PyHash_FuncDef/PyHash_GetFuncDef属于非有限 API需包含完整 CPython 头文件且未定义Py_LIMITED_API才可见Limited API 使用方本就不应依赖无需迁移。四、版本边界与仓库现状截至当前仓库快照pyhash.h 与 cpython/pyhash.h 中的上述宏和 API 仍然完整存在pyhash.c 也仍保留Py_HASH_EXTERNAL分支。这与废弃公告的「Pending removal in Python 3.19」措辞一致这些接口在 3.19 之前的版本中仍可用且未标注 deprecation 警告到 3.19 才会被移除。嵌入方在针对 3.19 及以后版本编译时应假定这些符号不存在。五、参考路径索引内容路径废弃公告本文主体Doc/deprecations/c-api-pending-removal-in-3.19.rst算法选择与 cutoff 宏Include/pyhash.hPyHash_FuncDef/PyHash_GetFuncDefInclude/cpython/pyhash.h哈希算法实现与 EXTERNAL 分支Python/pyhash.csys.hash_info构建Python/sysmodule.cPYTHONHASHSEED说明Doc/reference/datamodel.rst【免费下载链接】cpythonThe Python programming language项目地址: https://gitcode.com/GitHub_Trending/cp/cpython创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 CPython 3.19 C API 废弃解读：PEP 456 字符串哈希方案定制支持（Embedder Support）的移除
CPython 3.19 C API 废弃解读PEP 456 字符串哈希方案定制支持Embedder Support的移除【免费下载链接】cpythonThe Python programming language项目地址: https://gitcode.com/GitHub_Trending/cp/cpython本篇技术解读基于 CPython 仓库中的废弃公告文件 c-api-pending-removal-in-3.19.rst。该文档宣布在 Python 3.19 中将移除「PEP 456 为嵌入方embedder提供的字符串哈希方案定义支持」。读完后你将理解 PEP 456 曾向 C 嵌入层暴露了哪些哈希定制接口、这些接口在 CPython 源码中的具体落点以及嵌入式集成方自定义 Python 宿主应用、C 扩展构建系统在 3.19 到来前应如何完成迁移。一、公告本身一行声明背后的含义CPython 仓库在Doc/deprecations/目录下维护了一批按目标版本归类的 C API 废弃追踪文档。其中 c-api-pending-removal-in-3.19.rst 的完整内容只有一条条目Pending removal in Python 3.19 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * :pep:456 embedders support for the string hashing scheme definition.这条声明的技术含义是PEP 456 当年除了改变解释器内部的字符串哈希实现还额外开放了一组「让嵌入方在编译期定义字符串哈希方案」的 C 宏与 API。这一组面向 embedder 的定制能力而非 PEP 456 的哈希随机化本身将要在 3.19 中被删除。二、背景PEP 456 的 embedder 接口在 CPython 中的落点PEP 456随 Python 3.4 引入把 Python 字符串的哈希从固定的 DJBX33A 变体更换为抗碰撞攻击的 SipHash 系列算法并引入哈希随机化。与此同时它向嵌入层开放了三个定制维度全部集中在公开头文件 pyhash.h 中2.1 算法选择Py_HASH_ALGORITHM与四个取值pyhash.h 中定义了可选算法枚举及默认值选择逻辑#define Py_HASH_EXTERNAL 0 #define Py_HASH_SIPHASH24 1 #define Py_HASH_FNV 2 #define Py_HASH_SIPHASH13 3 #ifndef Py_HASH_ALGORITHM # ifndef HAVE_ALIGNED_REQUIRED # define Py_HASH_ALGORITHM Py_HASH_SIPHASH13 # else # define Py_HASH_ALGORITHM Py_HASH_FNV # endif #endif默认情况下支持对齐内存访问的平台使用 SipHash13不支持的平台回退到 FNV头文件注释明确指出「The values for Py_HASH_* are hard-coded in the configure script」即算法值由构建配置固化嵌入方此前可以通过在编译定义中强制Py_HASH_ALGORITHM例如设为Py_HASH_EXTERNAL来接管字符串哈希的计算。2.2 短字符串优化阈值Py_HASH_CUTOFFpyhash.h 还定义了短字符串快速哈希的截断长度/* Cutoff for small string DJBX33A optimization in range [1, cutoff). * * About 50% of the strings in a typical Python application are smaller than * 6 to 7 chars. However DJBX33A is vulnerable to hash collision attacks. * NEVER use DJBX33A for long strings! */ #ifndef Py_HASH_CUTOFF # define Py_HASH_CUTOFF 0 #elif (Py_HASH_CUTOFF 7 || Py_HASH_CUTOFF 0) # error Py_HASH_CUTOFF must in range 0...7. #endif取值被硬约束在 0..7 区间0 表示禁用短字符串优化越界会在编译期直接报错。注释同时说明了安全权衡短字符串用快速的 DJBX33A、长字符串用 SipHash以在典型负载约一半字符串长度小于 6~7 字符与抗碰撞攻击之间取得平衡。2.3 外部哈希实现注入PyHash_FuncDef真正属于「embedders support for the string hashing scheme definition」的核心 API 位于 cpython/pyhash.h该头文件仅在不定义Py_LIMITED_API时经 pyhash.h 间接包含/* hash function definition */ typedef struct { Py_hash_t (*const hash)(const void *, Py_ssize_t); const char *name; const int hash_bits; const int seed_bits; } PyHash_FuncDef; PyAPI_FUNC(PyHash_FuncDef*) PyHash_GetFuncDef(void);PyHash_FuncDef描述了当前字符串哈希函数指针、算法名称以及哈希位宽/种子位宽PyHash_GetFuncDef()允许嵌入方在运行时查询这些元信息。pyhash.h 的注释还给出了外部注入方式——当Py_HASH_ALGORITHM为Py_HASH_EXTERNAL时嵌入方可提供PyHash_FuncDef PyHash_Func {...};这一声明路径在实现层有直接对应pyhash.c 开头即有#if Py_HASH_ALGORITHM Py_HASH_EXTERNAL分支外部模式下哈希计算委托给嵌入方提供的实现而 SipHash13/SipHash24/FNV 各实现则分别位于该文件后续的条件编译块中。2.4 运行时可观测性sys.hash_info哈希方案的当前状态还通过 C API 暴露到解释器运行时。例如 sysmodule.c 在构建sys.hash_info时会写入 cutoff 值SET_HASH_INFO_ITEM(PyLong_FromLong(Py_HASH_CUTOFF))。从源码结构看一旦 embedder 定制接口移除sys.hash_info中将只反映内置算法的状态不再存在由外部注入的算法名。三、3.19 之后嵌入方还能做什么需要澄清一个关键边界被移除的只是「方案定义/替换」能力而非哈希随机化本身。字符串哈希仍由 CPython 内置算法计算哈希值在不同进程间的随机性继续由PYTHONHASHSEED环境变量控制该机制在官方参考文档 datamodel.rst 中有专门章节说明。对嵌入集成方而言迁移要点如下清理构建定义从 C 编译参数中移除对Py_HASH_ALGORITHM、Py_HASH_CUTOFF的自定义覆盖。这两个宏在 3.19 中不再有「由嵌入方定义方案」的语义价值移除外部哈希实现删除自实现的PyHash_Func变量、PyHash_FuncDef结构填充代码以及任何依赖PyHash_GetFuncDef()返回值的hash_bits/seed_bits字段做分支适配的逻辑替代策略若当初选择Py_HASH_EXTERNAL是为了跨进程/跨版本保证哈希值稳定改用固定PYTHONHASHSEED即可获得等价的确定性若当初是出于性能原因替换为更快但可碰撞的算法3.19 后该权衡不再开放给嵌入方需接受内置算法的性能特征注意稳定 ABI 面PyHash_FuncDef/PyHash_GetFuncDef属于非有限 API需包含完整 CPython 头文件且未定义Py_LIMITED_API才可见Limited API 使用方本就不应依赖无需迁移。四、版本边界与仓库现状截至当前仓库快照pyhash.h 与 cpython/pyhash.h 中的上述宏和 API 仍然完整存在pyhash.c 也仍保留Py_HASH_EXTERNAL分支。这与废弃公告的「Pending removal in Python 3.19」措辞一致这些接口在 3.19 之前的版本中仍可用且未标注 deprecation 警告到 3.19 才会被移除。嵌入方在针对 3.19 及以后版本编译时应假定这些符号不存在。五、参考路径索引内容路径废弃公告本文主体Doc/deprecations/c-api-pending-removal-in-3.19.rst算法选择与 cutoff 宏Include/pyhash.hPyHash_FuncDef/PyHash_GetFuncDefInclude/cpython/pyhash.h哈希算法实现与 EXTERNAL 分支Python/pyhash.csys.hash_info构建Python/sysmodule.cPYTHONHASHSEED说明Doc/reference/datamodel.rst【免费下载链接】cpythonThe Python programming language项目地址: https://gitcode.com/GitHub_Trending/cp/cpython创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考