Cython库导入报错：父模块未加载及编译产物存子目录问题

这两个问题其实是紧密关联的，咱们拆开来理清楚：

一、为什么编译产物会被写入子目录？ #

这通常是setuptools（或distutils）的默认行为导致的：

• 如果你的项目是一个Python包结构（也就是包含__init__.py的子目录），并且在setup.py里通过packages参数声明了这个包（比如packages=["mypackage"]），编译后的Cython扩展会自动生成在对应包结构的子目录下（比如build/lib.xxx/mypackage/）。
• 这么做的目的是为了保持包的层级一致性，确保后续安装（python setup.py install或pip install .）后，扩展模块能和包内的其他.py文件一起被放到正确的位置（比如系统的site-packages目录下的对应包文件夹），保证模块导入路径的正确性。

二、移出子目录后导入报错的原因 #

Cython编译的扩展模块会保留原有的包层级信息：

• 当你在setup.py里把扩展的name设为类似mypackage.myextension时，Cython在生成底层C代码时会写入这个完整的模块名称。
• 当你把编译好的.so（或.pyd）文件单独移到根目录后，Python尝试导入它时，会发现这个模块预期的父模块mypackage并没有被加载，也找不到对应的包结构，于是就抛出了Parent module not loaded for Cython library的错误——简单说就是模块的“身份信息”和它实际所在的路径不匹配了。

解决建议 #

1. 推荐做法：不要手动移动文件
   直接用python setup.py install或者pip install -e .（开发模式安装）来处理编译和安装，setuptools会自动把扩展放到正确的位置，导入时直接用from mypackage import myextension就能正常工作。
2. 本地测试无需安装的情况
   直接在项目根目录运行你的驱动程序，只要包目录（比如mypackage/）存在且包含__init__.py，Python的模块搜索路径会自动找到子目录里的编译扩展，无需移动。
3. 强制生成顶层模块（不推荐，除非特殊需求）
   修改setup.py里的扩展配置，把name参数改成顶层模块名（比如myextension而不是mypackage.myextension），同时移除packages参数（如果不需要包结构）。这样编译后的模块就是顶层模块，放到根目录也能直接导入。

内容的提问来源于stack exchange，提问作者Don Kirkby