如何为类字典对象指定正确的Python类型注解？

这个问题我之前也踩过坑！你用Dict[str, str]做类型注解会触发警告，是因为Dict对应的是Python内置的dict类本身，而像Shelf这种类字典对象只是实现了字典的核心接口，并不是dict的子类，所以类型检查工具（比如mypy）会判定类型不匹配。

下面给你几个实用的解决方案，根据你的函数操作场景来选：

只读场景：用Mapping[str, str] #

如果你的函数只需要读取类字典对象里的内容（比如用x["key"]、x.get("key")这类操作），完全不需要修改它，那collections.abc.Mapping（Python 3.3+可用）是最佳选择。它是一个抽象基类，所有实现了只读字典接口的对象（包括Shelf、defaultdict、OrderedDict等）都会和它兼容。

代码示例：

from collections.abc import Mapping

def handle(x: Mapping[str, str]):
    # 这里只做只读操作
    example_value = x.get("example_key", "default")
    print(example_value)
    pass

如果你的Python版本在3.8及以下，也可以用typing.Mapping，效果完全一致。

可写场景：用MutableMapping[str, str] #

要是你的函数需要修改这个类字典对象（比如添加键值对、删除键、修改值），那就得用MutableMapping——它是Mapping的子类，支持所有字典的读写操作，类字典对象比如Shelf也都实现了这个接口。

代码示例：

from collections.abc import MutableMapping

def handle(x: MutableMapping[str, str]):
    # 这里可以做修改操作
    x["new_key"] = "new_value"
    del x["old_key"]
    pass

定制化需求：自定义Protocol（可选） #

如果你只需要类字典对象的某几个特定方法，不想依赖完整的字典接口，可以自己定义一个Protocol（Python 3.8+支持）。这种方式更灵活，能精准匹配你的函数实际用到的操作。

代码示例：

from typing import Protocol

# 只定义函数实际需要的方法
class StringDictLike(Protocol):
    def __getitem__(self, key: str) -> str: ...
    def get(self, key: str, default: str = "") -> str: ...

def handle(x: StringDictLike):
    value = x.get("test_key")
    pass

一般情况下，用前两种标准库的抽象基类就足够覆盖绝大多数场景了，类型检查工具也能完美识别这些注解，不会再给你报类型不匹配的警告啦。

备注：内容来源于stack exchange，提问作者Richie Bendall