build-cython-ext

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Build Cython Extensions

构建Cython扩展

This skill provides guidance for building Cython extensions and resolving compatibility issues, with particular focus on numpy version compatibility problems.

本技能提供构建Cython扩展及解决兼容性问题的指南，重点关注numpy版本兼容性问题。

When to Use This Skill

何时使用本技能

Building or compiling Cython extensions (
```
.pyx
```
files)
Fixing numpy compatibility issues in Cython code
Migrating Cython projects to work with numpy 2.0+
Resolving deprecated numpy type errors (
```
np.int
```
,
```
np.float
```
,
```
np.bool
```
, etc.)
Troubleshooting Cython compilation failures

构建或编译Cython扩展（
```
.pyx
```
文件）
修复Cython代码中的numpy兼容性问题
将Cython项目迁移至numpy 2.0+版本
解决已弃用的numpy类型错误（
```
np.int
```
、
```
np.float
```
、
```
np.bool
```
等）
排查Cython编译失败问题

Key File Types to Examine

需要检查的关键文件类型

When working with Cython projects, always examine ALL relevant file types:

Extension	Description	Must Check
`.pyx`	Cython implementation files	Critical - Often contain numpy calls
`.pxd`	Cython declaration files	Yes - May contain type declarations
`.py`	Python files	Yes - May use deprecated types
`setup.py`	Build configuration	Yes - Defines compilation settings
`.c` / `.cpp`	Generated C/C++ files	Only if debugging compilation

Critical Pitfall: Never limit searches to only

.py

files when fixing numpy compatibility. The

.pyx

files are Cython source code and frequently contain the same deprecated numpy type references.

处理Cython项目时，务必检查所有相关文件类型：

扩展名	描述	必须检查
`.pyx`	Cython实现文件	关键 - 通常包含numpy调用
`.pxd`	Cython声明文件	是 - 可能包含类型声明
`.py`	Python文件	是 - 可能使用已弃用类型
`setup.py`	构建配置	是 - 定义编译设置
`.c` / `.cpp`	生成的C/C++文件	仅在调试编译问题时需要

关键陷阱：修复numpy兼容性问题时，切勿将搜索范围仅局限于

.py

文件。

.pyx

文件是Cython源代码，经常包含相同的已弃用numpy类型引用。

Approach for Numpy 2.0+ Compatibility

numpy 2.0+兼容性处理方法

Deprecated Types to Replace

需要替换的已弃用类型

Deprecated	Replacement
`np.int`	`np.int_` or `int`
`np.float`	`np.float64` or `float`
`np.bool`	`np.bool_` or `bool`
`np.complex`	`np.complex128` or `complex`
`np.object`	`np.object_` or `object`
`np.str`	`np.str_` or `str`

已弃用类型	替代方案
`np.int`	`np.int_` 或 `int`
`np.float`	`np.float64` 或 `float`
`np.bool`	`np.bool_` 或 `bool`
`np.complex`	`np.complex128` 或 `complex`
`np.object`	`np.object_` 或 `object`
`np.str`	`np.str_` 或 `str`

Search Strategy

搜索策略

Search without file type restrictions to capture all occurrences:
```
Grep for patterns like "np\.int[^0-9_]" across all files
```

Explicitly search Cython files:

Search specifically in *.pyx and *.pxd files

Check import statements in
```
.pyx
```
files - they often import numpy and use deprecated types

不限制文件类型进行搜索，以捕获所有出现的情况：
```
Grep for patterns like "np\.int[^0-9_]" across all files
```

明确搜索Cython文件：

Search specifically in *.pyx and *.pxd files

检查
.pyx
文件中的导入语句——它们通常会导入numpy并使用已弃用类型

Fix and Recompile Workflow

修复与重新编译流程

Identify all
```
.pyx
```
files in the project
Search each file for deprecated numpy types
Apply fixes to ALL files (both
```
.py
```
and
```
.pyx
```
)
Recompile the Cython extensions after making changes to
```
.pyx
```
files
Run verification tests

识别项目中所有
```
.pyx
```
文件
在每个文件中搜索已弃用的numpy类型
对所有文件（
```
.py
```
和
```
.pyx
```
）应用修复
修改
.pyx
文件后重新编译Cython扩展
运行验证测试

Verification Strategy

验证策略

Import Testing Is Insufficient

仅导入测试并不足够

Simply testing that a compiled module imports successfully does not verify the code works correctly. A module can import but fail when its functions are called.

仅测试已编译模块能否成功导入，并不能验证代码是否正常工作。模块可能导入成功，但调用其函数时会失败。

Recommended Verification Steps

Test Coverage Awareness

测试覆盖范围注意事项

Repository tests may not cover all Cython code paths
Passing tests does not guarantee all Cython functionality works
Explicitly test functions that use numpy types

仓库测试可能未覆盖所有Cython代码路径
测试通过并不保证所有Cython功能都能正常工作
明确测试使用numpy类型的函数

Common Pitfalls

常见陷阱

Narrow Search Scope: Using file type filters (e.g.,
```
type: "py"
```
) that exclude
```
.pyx
```
files
Premature Success Declaration: Assuming success after imports work or basic tests pass
Missing Recompilation: Forgetting to recompile after fixing
```
.pyx
```
files
Incomplete Pattern Matching: Missing variations like
```
numpy.int
```
vs
```
np.int
```
Ignoring Warning Signs: If compilation succeeds "surprisingly" easily, verify the compiled code actually runs correctly

搜索范围过窄：使用文件类型过滤器（如
```
type: "py"
```
）排除
```
.pyx
```
文件
过早宣告成功：假设导入成功或基础测试通过就代表任务完成
忘记重新编译：修复
```
.pyx
```
文件后忘记重新编译
模式匹配不完整：遗漏
```
numpy.int
```
与
```
np.int
```
等变体
忽略警告信号：如果编译异常顺利完成，需验证已编译代码是否真的能正常运行

Systematic Workflow

系统化流程

Discovery Phase
- List all
```
.pyx
```
  ,
```
.pxd
```
  , and
```
.py
```
  files
- Identify the build system (setup.py, pyproject.toml, etc.)
- Check numpy version requirements
Analysis Phase
- Search ALL source files for deprecated patterns
- Document every occurrence before fixing
- Note which files need recompilation
Fix Phase
- Apply fixes to all identified locations
- Ensure consistency in replacement types
- Update any type annotations or docstrings
Build Phase
- Clean previous build artifacts
- Recompile all Cython extensions
- Watch for compilation warnings
Verification Phase
- Test each Cython module individually
- Run the full test suite
- Execute functions with real numpy data
- Verify no runtime AttributeError for numpy types

发现阶段
- 列出所有
```
.pyx
```
  、
```
.pxd
```
  和
```
.py
```
  文件
- 识别构建系统（setup.py、pyproject.toml等）
- 检查numpy版本要求
分析阶段
- 在所有源文件中搜索已弃用模式
- 修复前记录所有出现的位置
- 标记需要重新编译的文件
修复阶段
- 对所有已识别的位置应用修复
- 确保替换类型的一致性
- 更新任何类型注解或文档字符串
构建阶段
- 清理之前的构建产物
- 重新编译所有Cython扩展
- 留意编译警告
验证阶段
- 逐个测试每个Cython模块
- 运行完整测试套件
- 使用真实numpy数据执行函数
- 验证不存在numpy类型相关的运行时AttributeError