拒绝通知

2024 年指导委员会拒绝的原因包括

• 我们没有找到证据表明这个功能在标准库中存在强烈共识，尽管一些支持者主张为了减少他们对第三方包的依赖而支持它。对于那些需要这种功能的人，我们认为那些现有的第三方库，如 attrs 和 Pydantic（PEP 中引用），是可以接受的替代方案。
• 在我们看来，这个功能似乎是标准库中可能被认为是更多“杂质”的积累，它让我们越来越远离 dataclasses 最适合的“简单”用例。
• 阅读 PEP 中的“如何教授这一点”部分让我们停顿了一下，因为它的陷阱和意外情况很严重，其带来的困惑和复杂性远远超过了任何潜在的益处。
• PEP 似乎更侧重于帮助类型检查器而不是使用库的人。

摘要

PEP 557 将 dataclasses 添加到 Python 标准库中。 PEP 681 添加了 dataclass_transform() 来帮助类型检查器理解几个常见的类似 dataclass 的库，如 attrs、Pydantic 和对象关系映射 (ORM) 包，如 SQLAlchemy 和 Django。

其他库相对于标准库实现提供的一个常见功能是，库能够使用用户提供的转换函数将初始化时给定的参数转换为每个字段所期望的类型。

因此，此 PEP 在 dataclasses.field()（以及对 dataclasses.Field 和 dataclass_transform() 的必要更改）中添加了一个 converter 参数，以指定用于将每个字段的输入值转换为要存储在 dataclass 中的表示形式的函数。

动机

目前没有现成的标准方法可以使 dataclasses 或第三方类似 dataclass 的库以类型可检查的方式支持参数转换。为了解决这个限制，库作者/用户被迫选择

• 选择加入自定义 Mypy 插件。这些插件帮助 Mypy 理解转换语义，但不能帮助其他工具。
• 将转换职责转移到 dataclass 构造函数的调用者身上。这可能会使某些 dataclass 的构造变得不必要地冗长和重复。
• 提供自定义的 __init__，它声明“更宽”的参数类型，并在设置适当的属性时进行转换。这不仅会在转换器和 __init__ 之间重复类型注释，还会让用户放弃 dataclasses 提供的许多功能。
• 提供自定义的 __init__，但对于需要转换的参数类型没有有意义的类型注释。

这些选择都不理想。

基本原理

添加参数转换语义很有用且足够有益，以至于大多数类似 dataclass 的库都提供了支持。将此功能添加到标准库意味着更多用户能够选择使用这些功能，而无需使用第三方库。此外，第三方库能够通过在 dataclass_transform() 中添加支持来向类型检查器暗示自己的转换语义，这意味着这些库的用户也将从中受益。

规范

def str_or_none(x: Any) -> str | None:
  return str(x) if x is not None else None

@dataclasses.dataclass
class InventoryItem:
    # `converter` as a type (including a GenericAlias).
    id: int = dataclasses.field(converter=int)
    skus: tuple[int, ...] = dataclasses.field(converter=tuple[int, ...])
    # `converter` as a callable.
    vendor: str | None = dataclasses.field(converter=str_or_none))
    names: tuple[str, ...] = dataclasses.field(
      converter=lambda names: tuple(map(str.lower, names))
    )  # Note that lambdas are supported, but discouraged as they are untyped.

    # The default value is also converted; therefore the following is not a
    # type error.
    stock_image_path: pathlib.PurePosixPath = dataclasses.field(
      converter=pathlib.PurePosixPath, default="assets/unknown.png"
    )

    # Default value conversion extends to `default_factory`;
    # therefore the following is also not a type error.
    shelves: tuple = dataclasses.field(
      converter=tuple, default_factory=list
    )

item1 = InventoryItem(
  "1",
  [234, 765],
  None,
  ["PYTHON PLUSHIE", "FLUFFY SNAKE"]
)
# item1's repr would be (with added newlines for readability):
#   InventoryItem(
#     id=1,
#     skus=(234, 765),
#     vendor=None,
#     names=('PYTHON PLUSHIE', 'FLUFFY SNAKE'),
#     stock_image_path=PurePosixPath('assets/unknown.png'),
#     shelves=()
#   )

# Attribute assignment also participates in conversion.
item1.skus = [555]
# item1's skus attribute is now (555,).

向后兼容性

这些更改不会引入任何兼容性问题，因为它们只引入了选择加入的新功能。

安全隐患

这些更改没有直接的安全问题。

如何教授这一点

解释新参数和行为的文档和示例将被添加到文档网站的相关部分（主要是在 dataclasses 上），并从What’s New 文档链接到它们。

添加的文档/示例还将涵盖用户使用转换器时可能会遇到的“常见陷阱”。这些陷阱包括

• 需要处理 None/哨兵值。
• 需要处理已经是正确类型的的值。
• 避免为转换器使用 lambda 表达式，因为合成 __init__ 参数的类型将变为 Any。
• 忘记在冻结的 dataclass 中用户定义的 __init__ 的主体中转换值。
• 忘记在非冻结的 dataclass 中用户定义的 __setattr__ 的主体中转换值。

此外，还应涵盖可能令人困惑的模式匹配语义

@dataclass
class Point:
    x: int = field(converter=int)
    y: int

match Point(x="0", y=0):
    case Point(x="0", y=0):  # Won't be matched
        ...
    case Point():  # Will be matched
        ...
    case _:
        ...

但是，值得注意的是，这种行为对在其初始化程序中进行转换的任何类型都是正确的，类型检查器应该能够捕获这个陷阱。

match int("0"):
  case int("0"):  # Won't be matched
      ...
  case _:  # Will be matched
      ...

参考实现

attrs 库已经包含一个converter参数，在使用@define类装饰器时，表现出相同的转换语义（在初始化器和属性设置时转换）。

CPython 支持是在作者分支上的一个分支上实现的。

被拒绝的想法

版权

本文档置于公共领域或根据 CC0-1.0-Universal 许可证，以更宽松的方式使用。