导入flask_socketio报错：AttributeError: module 'collections' has no attribute 'MutableMapping'

问题场景 #

当Python文件仅包含以下代码时：

from flask_socketio import SocketIO

运行后出现如下错误：

> python .\app.py
Traceback (most recent call last):
  File "C:\{...}\server\app.py", line 127, in <module>
    from flask_socketio import SocketIO
  File "C:\{...}\Python310\lib\site-packages\flask_socketio\__init__.py", line 9, in <module>
    from socketio import socketio_manage  # noqa: F401
  File "C:\{...}\Python310\lib\site-packages\socketio\__init__.py", line 9, in <module>
    from .zmq_manager import ZmqManager
  File "C:\{...}\Python310\lib\site-packages\socketio\zmq_manager.py", line 5, in <module>
    import eventlet.green.zmq as zmq
  File "C:\{...}\Python310\lib\site-packages\eventlet\__init__.py", line 17, in <module>
    from eventlet import convenience
  File "C:\{...}\Python310\lib\site-packages\eventlet\convenience.py", line 7, in <module>
    from eventlet.green import socket
  File "C:\{...}\Python310\lib\site-packages\eventlet\green\socket.py", line 21, in <module>
    from eventlet.support import greendns
  File "C:\{...}\Python310\lib\site-packages\eventlet\support\greendns.py", line 79, in <module>
    setattr(dns, pkg, import_patched('dns.' + pkg))
  File "C:\{...}\Python310\lib\site-packages\eventlet\support\greendns.py", line 61, in import_patched
    return patcher.import_patched(module_name, **modules)
  File "C:\{...}\Python310\lib\site-packages\eventlet\patcher.py", line 132, in import_patched
    return inject(
  File "C:\{...}\Python310\lib\site-packages\eventlet\patcher.py", line 109, in inject
    module = __import__(module_name, {}, {}, module_name.split('.')[:-1])
  File "C:\{...}\Python310\lib\site-packages\dns\namedict.py", line 35, in <module>
    class NameDict(collections.MutableMapping):
AttributeError: module 'collections' has no attribute 'MutableMapping'

已知在Python >=3.1版本中，collections.MutableMapping已迁移至collections.abc.MutableMapping，且已尝试以下无效解决方案：

• 升级基础依赖包：

  pip install --upgrade pip
  pip install --upgrade wheel
  pip install --upgrade setuptools
  pip install --upgrade requests
  

• 重新安装flask-socketio：

  pip install flask-socketio
  

• 升级eventlet依赖：

  pip install --upgrade eventlet
  # 执行后返回：
  Requirement already satisfied: eventlet in c:\...\python\python310\lib\site-packages (0.33.3)
  Requirement already satisfied: greenlet>=0.3 in c:\...\python\python310\lib\site-packages (from eventlet) (2.0.2)
  Requirement already satisfied: dnspython>=1.15.0 in c:\...\python\python310\lib\site-packages (from eventlet) (1.16.0)
  Requirement already satisfied: six>=1.10.0 in c:\...\python\python310\lib\site-packages (from eventlet) (1.16.0)
  

有效修复方案 #

1. 升级dnspython到兼容版本 #

错误根源是当前安装的dnspython 1.16.0版本不兼容Python3.10，仍在使用已被移除的collections.MutableMapping。执行以下命令升级：

pip install --upgrade dnspython

升级后的dnspython会自动使用collections.abc.MutableMapping，彻底解决该属性错误。

2. 替换eventlet为gevent（备选方案） #

如果升级dnspython后仍存在问题，可以尝试更换flask-socketio的异步依赖，避免eventlet对dns模块的patch引发冲突：

pip uninstall eventlet
pip install gevent gevent-websocket

随后在代码中指定使用gevent模式：

from flask import Flask
from flask_socketio import SocketIO

app = Flask(__name__)
socketio = SocketIO(app, async_mode='gevent')

3. 临时修改dnspython文件（不推荐） #

若无法升级依赖，可手动修改dnspython的源码文件应急：
找到路径C:\{...}\Python310\lib\site-packages\dns\namedict.py，修改第35行代码：

# 原代码
class NameDict(collections.MutableMapping):
# 修改为
from collections.abc import MutableMapping
class NameDict(MutableMapping):

注意：该方法在依赖包升级后会被覆盖，仅作为临时应急手段。

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