Python3.10升级Flask应用遇PyJadeExtension模块导入错误求助

问题场景 #

将Flask应用从Python3.8升级到Python3.10时，执行添加PyJadeExtension的代码行抛出异常：

app = Flask(__name__)
app.jinja_env.add_extension('pyjade.ext.jinja.PyJadeExtension') # <-- 该行报错

异常堆栈信息：

Traceback (most recent call last):
  File "/usr/local/anaconda3/envs/py10/lib/python3.10/site-packages/pyjade/runtime.py", line 8, in <module>
    from collections import Mapping as MappingType
ImportError: cannot import name 'Mapping' from 'collections' (/usr/local/anaconda3/envs/py10/lib/python3.10/collections/__init__.py)

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/Users/manmohansinghvirdi/GitHub/qa-cp-simulator/CPStationSimulator/qawebserver/qawebserver.py", line 27, in <module>
    app.jinja_env.add_extension('pyjade.ext.jinja.PyJadeExtension')
  File "/usr/local/anaconda3/envs/py10/lib/python3.10/site-packages/jinja2/environment.py", line 375, in add_extension
    self.extensions.update(load_extensions(self, [extension]))
  File "/usr/local/anaconda3/envs/py10/lib/python3.10/site-packages/jinja2/environment.py", line 119, in load_extensions
    extension = t.cast(t.Type["Extension"], import_string(extension))
  File "/usr/local/anaconda3/envs/py10/lib/python3.10/site-packages/jinja2/utils.py", line 149, in import_string
    return getattr(__import__(module, None, None, [obj]), obj)
  File "/usr/local/anaconda3/envs/py10/lib/python3.10/site-packages/pyjade/__init__.py", line 4, in <module>
    from .utils import process
  File "/usr/local/anaconda3/envs/py10/lib/python3.10/site-packages/pyjade/utils.py", line 224, in <module>
    from .ext.html import Compiler as HTMLCompiler
  File "/usr/local/anaconda3/envs/py10/lib/python3.10/site-packages/pyjade/ext/html.py", line 6, in <module>
    from pyjade.runtime import is_mapping, iteration, escape
  File "/usr/local/anaconda3/envs/py10/lib/python3.10/site-packages/pyjade/runtime.py", line 10, in <module>
    import UserDict
ModuleNotFoundError: No module named 'UserDict'

问题原因 #

PyJade项目已长期未维护，其代码依赖Python3.8及更早版本的collections模块结构：

• Python3.10中，Mapping、MutableMapping等抽象基类已从collections模块迁移至collections.abc
• UserDict模块在Python3中已被整合到collections.abc，不再作为独立模块存在

解决方案 #

方案1：使用猴子补丁（Monkey Patch）快速兼容 #

在加载PyJade扩展前，通过补丁修复旧的导入逻辑，无需修改第三方包代码，适合CI/CD流水线部署：

# 在app.py最顶部添加以下代码
import sys
from collections.abc import Mapping, MutableMapping

# 给collections模块补全旧版本的导出项
import collections
collections.Mapping = Mapping
collections.MutableMapping = MutableMapping

# 模拟UserDict模块，适配PyJade的导入逻辑
class MockUserDict:
    class DictMixin(MutableMapping):
        pass

sys.modules['UserDict'] = MockUserDict

# 之后再初始化Flask并加载扩展
app = Flask(__name__)
app.jinja_env.add_extension('pyjade.ext.jinja.PyJadeExtension')

优点：无需修改第三方依赖，快速解决问题；不影响现有CI/CD流程
缺点：属于临时兼容方案，若PyJade后续有其他兼容性问题可能失效

方案2：安装社区维护的兼容分支 #

寻找社区中已修复Python3.10兼容性问题的PyJade分支，通过git直接安装该分支版本：

pip install git+<社区修复分支的git地址>

安装完成后，保持原有扩展引用代码不变即可。

优点：基于官方代码修复，兼容性更可靠
缺点：依赖第三方分支，需确认分支的维护状态

方案3：迁移至活跃维护的模板引擎 #

由于PyJade已停止维护，长远来看建议迁移至其他支持Python3.10的模板引擎，例如：

• 改用Jinja2原生模板语法（无需额外扩展）
• 使用活跃维护的Pug/Jade风格模板扩展

优点：彻底解决兼容性问题，获得长期维护支持
缺点：需要修改现有模板代码，迁移成本较高

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