Back to Details

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:
ExtensionDescriptionMust Check
.pyx
Cython implementation filesCritical - Often contain numpy calls
.pxd
Cython declaration filesYes - May contain type declarations
.py
Python filesYes - May use deprecated types
setup.py
Build configurationYes - Defines compilation settings
.c
/ 
.cpp
Generated C/C++ filesOnly 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

需要替换的已弃用类型

DeprecatedReplacement
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

搜索策略

  1. Search without file type restrictions to capture all occurrences:
    Grep for patterns like "np\.int[^0-9_]" across all files
  2. Explicitly search Cython files:
    Search specifically in *.pyx and *.pxd files
  3. Check import statements in 
    .pyx
    files - they often import numpy and use deprecated types
  1. 不限制文件类型进行搜索，以捕获所有出现的情况：
    Grep for patterns like "np\.int[^0-9_]" across all files
  2. 明确搜索Cython文件：
    Search specifically in *.pyx and *.pxd files
  3. 检查
    .pyx
    文件中的导入语句    ——它们通常会导入numpy并使用已弃用类型

Fix and Recompile Workflow

修复与重新编译流程

  1. Identify all 
    .pyx
    files in the project
  2. Search each file for deprecated numpy types
  3. Apply fixes to ALL files (both 
    .py
    and 
    .pyx
    )
  4. Recompile the Cython extensions after making changes to 
    .pyx
    files
  5. Run verification tests
  1. 识别项目中所有
    .pyx
    文件
  2. 在每个文件中搜索已弃用的numpy类型
  3. 对所有文件（
    .py
    和
    .pyx
    ）应用修复
  4. 修改
    .pyx
    文件后重新编译Cython扩展
  5. 运行验证测试

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

推荐的验证步骤

  1. Identify all Cython modules in the project
  2. For each module:
    • Verify import succeeds
    • Call at least one core function from each module
    • Pass actual data to exercise numpy operations
  3. Run the project's test suite if available
  4. Create a verification script that exercises key functionality:
    python
    # Example verification pattern
import numpy as np
from module import cython_function

# Test with actual numpy arrays
test_data = np.array([1, 2, 3], dtype=np.int64)
result = cython_function(test_data)
assert result is not None
  1. 识别项目中所有Cython模块
  2. 针对每个模块：
    • 验证导入是否成功
    • 调用每个模块中的至少一个核心函数
    • 传入实际数据以触发numpy操作
  3. 如果有项目测试套件，运行它
  4. 创建验证脚本以测试关键功能：
    python
    # Example verification pattern
import numpy as np
from module import cython_function

# Test with actual numpy arrays
test_data = np.array([1, 2, 3], dtype=np.int64)
result = cython_function(test_data)
assert result is not None

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

常见陷阱

  1. Narrow Search Scope: Using file type filters (e.g., 
    type: "py"
    ) that exclude 
    .pyx
    files
  2. Premature Success Declaration: Assuming success after imports work or basic tests pass
  3. Missing Recompilation: Forgetting to recompile after fixing 
    .pyx
    files
  4. Incomplete Pattern Matching: Missing variations like 
    numpy.int
    vs 
    np.int
  5. Ignoring Warning Signs: If compilation succeeds "surprisingly" easily, verify the compiled code actually runs correctly
  1. 搜索范围过窄：使用文件类型过滤器（如
    type: "py"
    ）排除
    .pyx
    文件
  2. 过早宣告成功：假设导入成功或基础测试通过就代表任务完成
  3. 忘记重新编译：修复
    .pyx
    文件后忘记重新编译
  4. 模式匹配不完整：遗漏
    numpy.int
    与
    np.int
    等变体
  5. 忽略警告信号：如果编译异常顺利完成，需验证已编译代码是否真的能正常运行

Systematic Workflow

系统化流程

  1. Discovery Phase
    • List all 
      .pyx
      , 
      .pxd
      , and 
      .py
      files
    • Identify the build system (setup.py, pyproject.toml, etc.)
    • Check numpy version requirements
  2. Analysis Phase
    • Search ALL source files for deprecated patterns
    • Document every occurrence before fixing
    • Note which files need recompilation
  3. Fix Phase
    • Apply fixes to all identified locations
    • Ensure consistency in replacement types
    • Update any type annotations or docstrings
  4. Build Phase
    • Clean previous build artifacts
    • Recompile all Cython extensions
    • Watch for compilation warnings
  5. 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
  1. 发现阶段
    • 列出所有
      .pyx
      、
      .pxd
      和
      .py
      文件
    • 识别构建系统（setup.py、pyproject.toml等）
    • 检查numpy版本要求
  2. 分析阶段
    • 在所有源文件中搜索已弃用模式
    • 修复前记录所有出现的位置
    • 标记需要重新编译的文件
  3. 修复阶段
    • 对所有已识别的位置应用修复
    • 确保替换类型的一致性
    • 更新任何类型注解或文档字符串
  4. 构建阶段
    • 清理之前的构建产物
    • 重新编译所有Cython扩展
    • 留意编译警告
  5. 验证阶段
    • 逐个测试每个Cython模块
    • 运行完整测试套件
    • 使用真实numpy数据执行函数
    • 验证不存在numpy类型相关的运行时AttributeError