Readthedocs构建时pyneb依赖numpy遇ModuleNotFoundError求助

问题背景 #

尝试将specsy库文档上传至Readthedocs，本地Sphinx文档可正常编译，但Readthedocs构建失败，核心原因是依赖库PyNeb在安装过程中无法找到numpy；移除PyNeb后依赖可正常安装，但后续文档构建会因autodoc失败。

错误日志 #

Processing /home/docs/checkouts/readthedocs.org/user_builds/specsy/checkouts/latest
  Preparing metadata (setup.py): started
  Preparing metadata (setup.py): finished with status 'done'
Collecting numpy
  Downloading numpy-1.23.3-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (17.1 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 17.1/17.1 MB 142.8 MB/s eta 0:00:00
Collecting matplotlib
  Downloading matplotlib-3.5.3-cp38-cp38-manylinux_2_5_x86_64.manylinux1_x86_64.whl (11.3 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 11.3/11.3 MB 144.7 MB/s eta 0:00:00
Collecting pandas
  Downloading pandas-1.4.4-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (11.7 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 11.7/11.7 MB 141.7 MB/s eta 0:00:00
Collecting astropy
  Downloading astropy-5.1-cp38-cp38-manylinux_2_12_x86_64.manylinux2010_x86_64.whl (11.1 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 11.1/11.1 MB 146.2 MB/s eta 0:00:00
Collecting lime
  Downloading lime-0.2.0.1.tar.gz (275 kB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 275.7/275.7 kB 252.6 MB/s eta 0:00:00
  Preparing metadata (setup.py): started
  Preparing metadata (setup.py): finished with status 'done'
Collecting pyneb
  Downloading PyNeb-1.1.15.tar.gz (25.1 MB)
     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 25.1/25.1 MB 141.3 MB/s eta 0:00:00
  Preparing metadata (setup.py): started
  Preparing metadata (setup.py): finished with status 'error'
  error: subprocess-exited-with-error
  
  × python setup.py egg_info did not run successfully.
  │ exit code: 1
  ╰─> [15 lines of output]
      Traceback (most recent call last):
        File "/tmp/pip-install-ly67tghn/pyneb_2849cf71307b466b98eb4ad9a85cdddb/pyneb/__init__.py", line 21, in <module>
          from numpy.version import version as numpy_version
      ModuleNotFoundError: No module named 'numpy'
      
      During handling of the above exception, another exception occurred:
      
      Traceback (most recent call last):
        File "<string>", line 2, in <module>
        File "<pip-setuptools-caller>", line 34, in <module>
        File "/tmp/pip-install-ly67tghn/pyneb_2849cf71307b466b98eb4ad9a85cdddb/setup.py", line 14, in <module>
          from pyneb.version import __version__
        File "/tmp/pip-install-ly67tghn/pyneb_2849cf71307b466b98eb4ad9a85cdddb/pyneb/__init__.py", line 25, in <module>
          log_.warn('I do not understand what is your version of numpy: {0}, report this to PyNeb group'.format(numpy_version), calling='PyNeb')
      NameError: name 'numpy_version' is not defined
      [end of output]
  
  note: This error originates from a subprocess, and is likely not a problem with pip.
error: metadata-generation-failed

× Encountered error while generating package metadata.
╰─> See above for output.

note: This is an issue with the package mentioned above, not pip.
hint: See above for details.

PyNeb的代码问题 #

PyNeb的__init__.py在执行时会直接尝试导入numpy，且异常处理存在漏洞：当numpy未安装时，numpy_version变量未定义，但except块仍尝试引用该变量，导致NameError。相关代码片段如下：

"""
PyNeb - python package for the analysis of emission lines
"""

__all__ = []
from .version import __version__

import sys
__pyversion__ = sys.version_info[0]

from .utils.Config import _Config
config = _Config()
log_ = config.log_
log_.message('Starting PyNeb version %s' % __version__, calling='PyNeb')


if sys.version_info[0:2] < (2, 6):
    log_.warn('Python version >= 2.6 needed, seems you have {0}'.format(sys.version_info), calling='PyNeb')

try:
    from numpy.version import version as numpy_version    
    if [int(n) for n in (numpy_version.split('.')[:3])] < [1, 5, 1] :
        log_.warn('Numpy version >= 1.5.1 needed, seems you have {0}'.format(numpy_version), calling='PyNeb')
except:
    log_.warn('I do not understand what is your version of numpy: {0}, report this to PyNeb group'.format(numpy_version), calling='PyNeb')

解决方案 #

方案一：提前通过requirements文件安装numpy #

1. 在项目根目录创建requirements-docs.txt文件，内容为：

   numpy>=1.5.1
   

2. 进入Readthedocs项目设置页面，找到Build -> Requirements file，选择刚创建的requirements-docs.txt。
3. 重新触发构建，Readthedocs会先安装numpy，再处理其他依赖。

方案二：修复PyNeb的异常处理逻辑（需修改PyNeb代码） #

如果可以fork PyNeb仓库并修改代码，将__init__.py中的异常处理部分调整为：

try:
    from numpy.version import version as numpy_version    
    if [int(n) for n in (numpy_version.split('.')[:3])] < [1, 5, 1] :
        log_.warn('Numpy version >= 1.5.1 needed, seems you have {0}'.format(numpy_version), calling='PyNeb')
except ImportError:
    log_.warn('Numpy is not installed. Please install numpy >=1.5.1 first.', calling='PyNeb')
except Exception as e:
    log_.warn(f'Unexpected error checking numpy version: {str(e)}', calling='PyNeb')

之后在项目依赖中指向修改后的PyNeb版本。

方案三：自定义Readthedocs构建命令 #

1. 进入Readthedocs项目设置的Advanced Settings页面。
2. 在Build Command中替换为：

   pip install numpy>=1.5.1 && python -m sphinx -T -b html docs/source docs/build/html
   

3. 重新触发构建，该命令会先安装numpy，再执行Sphinx文档构建。

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