Sphinx扩展sphinxprettysearchresults报错：name 'unicode' is not defined

环境信息 #

• Windows 10系统
• Python 3.12.1
• Sphinx 7.2.6
• 执行命令：sphinx-build -E d:\Luxoft\root\myrepo\en ...\root\myrepo-build\output\en

错误详情 #

执行构建命令时触发扩展错误：

Extension error (sphinxprettysearchresults):
Handler <function build_search_snippets at 0x0000022451ACBF60> for event 'build-finished' threw an exception (exception: name 'unicode' is not defined)

完整构建输出：

Running Sphinx v7.2.6
...\Python\Lib\site-packages\sphinxcontrib\images.py:32: RemovedInSphinx80Warning: The alias     'sphinx.util.status_iterator' is deprecated, use 'sphinx.util.display.status_iterator' instead. Check CHANGES for Sphinx API modifications.
 from sphinx.util import status_iterator
Initiated sphinxcontrib-images backend: `sphinxcontrib_images_lightbox2.lightbox2:LightBox2`
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 925 source files that are out of date
updating environment: [new config] 925 added, 0 changed, 0 removed
reading sources... [100%] usd_hydra/hydra
Downloading remote images...
Copying static files for sphinxcontrib-images...[100%] lightbox2-customize/jquery-noconflict.js
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
copying assets... copying static files... done
copying extra files... done
done
writing output... [  0%] amd_renderstudio/about
Extension error (sphinxprettysearchresults):
Handler <function build_search_snippets at 0x000001C9701CBF60> for event 'build-finished' threw an exception (exception: name 'unicode' is not defined)

问题原因 #

unicode是Python 2专属的类型，Python 3已将其合并到str类型中，该扩展的代码未适配Python 3环境，导致构建时找不到unicode名称。

解决方法 #

方法1：添加Python 3兼容代码 #

找到扩展主文件：Python\Lib\site-packages\sphinxprettysearchresults\__init__.py，在文件开头（可放在你之前添加的import os等代码之后）加入以下代码：

import sys
# 适配Python 3，将unicode映射为str
if sys.version_info >= (3, 0):
    unicode = str

方法2：直接替换代码中的unicode为str #

打开上述__init__.py文件，搜索所有unicode()的调用，直接替换为str()。例如将unicode(some_content)改成str(some_content)。

补充说明 #

你之前解决os未定义问题的思路是正确的，都是通过修改扩展源码适配当前Python环境，这次同样是扩展的版本兼容性问题，按上述方法修改后即可正常执行构建。

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