添加tqdm依赖后ReadTheDocs构建出现无法本地复现的AttributeError错误
问题原因
- 核心冲突为旧版本
pydata-sphinx-theme与高版本docutils不兼容:docutils 0.18及以上版本将_table_row_index属性调整为只读属性,而0.9.0版本以下的pydata-sphinx-theme仍然尝试直接修改该属性,最终抛出AttributeError: can't set attribute错误。 - 新增
tqdm依赖触发问题的原因:较新版本的tqdm会自动依赖0.18及以上版本的docutils,你此前的构建环境中docutils版本较低,没有触发兼容性问题。 - 本地无法复现的原因:你本地环境中要么
pydata-sphinx-theme版本已经升级到兼容版本,要么docutils版本停留在0.17及以下,和ReadTheDocs每次构建默认拉取最新依赖的环境不一致。
解决方法
- 方案1:升级
pydata-sphinx-theme到0.9.0及以上版本,该版本已经修复了与高版本docutils的兼容性问题。你可以在文档依赖文件(通常为docs/requirements.txt或pyproject.toml的文档依赖配置段)中添加版本约束:pydata-sphinx-theme>=0.9.0。 - 方案2:如果暂时不需要升级主题,可以直接锁定docutils版本到0.17.x区间,避免tqdm拉取高版本docutils。在文档依赖中添加版本约束:
docutils<0.18。 - 补充建议:为避免后续出现同类依赖版本不一致问题,建议将文档构建的所有依赖都添加明确的版本约束,不要让ReadTheDocs自动拉取最新版依赖。
内容的提问来源于stack exchange,提问作者Radost Waszkiewicz
相关产品推荐
相关产品推荐

