类

目前，实现只读属性主要有三种方式，并被类型检查器所接受：

• 使用 typing.Final 标注属性

  class Foo:
      number: Final[int]
  
      def __init__(self, number: int) -> None:
          self.number = number
  
  
  class Bar:
      def __init__(self, number: int) -> None:
          self.number: Final = number
  

  • 由 dataclasses 支持（以及自 typing#1669 以来的类型检查器）。
  • 覆盖 number 是不可能的——Final 的规范规定名称不能在子类中被覆盖。
• 通过 @property 实现只读代理

  class Foo:
      _number: int
  
      def __init__(self, number: int) -> None:
          self._number = number
  
      @property
      def number(self) -> int:
          return self._number
  

  • 覆盖 number 是可能的。类型检查器对具体规则存在分歧。[1]
  • 在运行时只读。[2]
  • 需要额外的样板代码。
  • 由 dataclasses 支持，但组合性不佳——合成的 __init__ 和 __repr__ 将使用 _number 作为参数/属性名称。
• 使用“冻结”机制，例如 dataclasses.dataclass() 或 typing.NamedTuple

  @dataclass(frozen=True)
  class Foo:
      number: int  # implicitly read-only
  
  
  class Bar(NamedTuple):
      number: int  # implicitly read-only
  

  • 在 @dataclass 情况下，覆盖 number 是可能的。
  • 在运行时只读。[2]
  • 没有每属性控制——这些机制适用于整个类。
  • 冻结数据类会产生一些运行时开销。
  • NamedTuple 仍然是一个 tuple。大多数类不需要继承索引、迭代或拼接。

协议

假设一个 Protocol 成员 name: T 定义了两个要求

1. hasattr(obj, "name")
2. isinstance(obj.name, T)

这些要求在运行时可以通过以下所有方式满足

• 一个具有属性 name: T 的对象，
• 一个具有类变量 name: ClassVar[T] 的类，
• 上述类的一个实例，
• 一个具有 @property def name(self) -> T 的对象，
• 一个具有自定义描述符的对象，例如 functools.cached_property()。

当前的 类型规范 允许使用（抽象）属性创建此类协议成员

class HasName(Protocol):
    @property
    def name(self) -> T: ...

这种语法有几个缺点

• 它有些冗长。
• 不明显此处所表达的品质是属性的只读特性。
• 它不能与 类型限定符 组合使用。
• 并非所有类型检查器都同意 [3] 上述所有五个对象都可以赋值给此结构类型。

初始化

只读属性的赋值只能发生在声明该属性的类中。对该属性的赋值次数没有限制。根据属性的类型，它们可以在不同的位置被赋值

from collections import abc
from typing import ReadOnly


class Band:
    name: str
    songs: ReadOnly[list[str]]

    def __init__(self, name: str, songs: abc.Iterable[str] | None = None) -> None:
        self.name = name
        self.songs = []

        if songs is not None:
            self.songs = list(songs)  # multiple assignments are fine

    def clear(self) -> None:
        # error: assignment to read-only "songs" outside initialization
        self.songs = []


band = Band(name="Bôa", songs=["Duvet"])
band.name = "Python"           # ok: "name" is not read-only
band.songs = []                # error: "songs" is read-only
band.songs.append("Twilight")  # ok: list is mutable


class SubBand(Band):
    def __init__(self) -> None:
        self.songs = []  # error: cannot assign to a read-only attribute of a base class

# a simplified immutable Fraction class
class Fraction:
    numerator: ReadOnly[int]
    denominator: ReadOnly[int]

    def __new__(
        cls,
        numerator: str | int | float | Decimal | Rational = 0,
        denominator: int | Rational | None = None
    ) -> Self:
        self = super().__new__(cls)

        if denominator is None:
            if type(numerator) is int:
                self.numerator = numerator
                self.denominator = 1
                return self

            elif isinstance(numerator, Rational): ...

        else: ...

    @classmethod
    def from_float(cls, f: float, /) -> Self:
        self = super().__new__(cls)
        self.numerator, self.denominator = f.as_integer_ratio()
        return self

class URI:
    protocol: ReadOnly[ClassVar[str]] = ""

    def __init_subclass__(cls, protocol: str = "") -> None:
        cls.protocol = protocol

class File(URI, protocol="file"): ...

class Patient:
    number: ReadOnly[int] = 0

    def __init__(self, number: int | None = None) -> None:
        if number is not None:
            self.number = number

class Patient:
    id: ReadOnly[int]    # error: "id" is not initialized on all code paths
    name: ReadOnly[str]  # error: "name" is never initialized

    def __init__(self) -> None:
        if random.random() > 0.5:
            self.id = 123


class HasName(Protocol):
    name: ReadOnly[str]  # ok

子类型

无法重新赋值只读属性使它们具有协变性。这带来了一些子类型化影响。借鉴 PEP 705

• 只读属性可以重新声明为可写属性、描述符或类变量

  @dataclass
  class HasTitle:
      title: ReadOnly[str]
  
  
  @dataclass
  class Game(HasTitle):
      title: str
      year: int
  
  
  game = Game(title="DOOM", year=1993)
  game.year = 1994
  game.title = "DOOM II"  # ok: attribute is not read-only
  
  
  class TitleProxy(HasTitle):
      @functools.cached_property
      def title(self) -> str: ...
  
  
  class SharedTitle(HasTitle):
      title: ClassVar[str] = "Still Grey"
  

• 如果只读属性未重新声明，则保持只读

  class Game(HasTitle):
      year: int
  
      def __init__(self, title: str, year: int) -> None:
          super().__init__(title)
          self.title = title  # error: cannot assign to a read-only attribute of base class
          self.year = year
  
  
  game = Game(title="Robot Wants Kitty", year=2010)
  game.title = "Robot Wants Puppy"  # error: "title" is read-only
  

• 子类型可以 收窄 只读属性的类型

  class GameCollection(Protocol):
      games: ReadOnly[abc.Collection[Game]]
  
  
  @dataclass
  class GameSeries(GameCollection):
      name: str
      games: ReadOnly[list[Game]]  # ok: list[Game] is assignable to Collection[Game]
  

• 协议和 ABCs 的名义子类应重新声明只读属性以实现它们，除非基类以某种方式初始化它们

  class MyBase(abc.ABC):
      foo: ReadOnly[int]
      bar: ReadOnly[str] = "abc"
      baz: ReadOnly[float]
  
      def __init__(self, baz: float) -> None:
          self.baz = baz
  
      @abstractmethod
      def pprint(self) -> None: ...
  
  
  @final
  class MySubclass(MyBase):
      # error: MySubclass does not override "foo"
  
      def pprint(self) -> None:
          print(self.foo, self.bar, self.baz)
  

• 在协议属性声明中，name: ReadOnly[T] 表示结构子类型必须支持 .name 访问，并且返回的值可以赋值给 T

  class HasName(Protocol):
      name: ReadOnly[str]
  
  
  class NamedAttr:
      name: str
  
  class NamedProp:
      @property
      def name(self) -> str: ...
  
  class NamedClassVar:
      name: ClassVar[str]
  
  class NamedDescriptor:
      @cached_property
      def name(self) -> str: ...
  
  # all of the following are ok
  has_name: HasName
  has_name = NamedAttr()
  has_name = NamedProp()
  has_name = NamedClassVar
  has_name = NamedClassVar()
  has_name = NamedDescriptor()
  

与其他类型限定符的交互

ReadOnly 可以与 ClassVar 和 Annotated 以任何嵌套顺序使用

class Foo:
    foo: ClassVar[ReadOnly[str]] = "foo"
    bar: Annotated[ReadOnly[int], Gt(0)]

class Foo:
    foo: ReadOnly[ClassVar[str]] = "foo"
    bar: ReadOnly[Annotated[int, Gt(0)]]

这与 PEP 705 中定义的 ReadOnly 和 typing.TypedDict 的交互一致。

属性不能同时标注为 ReadOnly 和 Final，因为这两个限定符在语义上有所不同，且 Final 通常更具限制性。Final 仍然允许作为仅被隐含为只读的属性的注解。它也可以用来重新声明基类的 ReadOnly 属性。

澄清 @property 与协议的交互

协议 一节提到了类型检查器在解释协议中的属性时存在不一致。该问题可以通过修改类型规范来解决，阐明这些属性的只读性质是如何实现的。

本 PEP 使 ReadOnly 成为在协议中定义只读属性的更好替代方案，取代了为此目的使用属性。

仅在 __init__ 和类体中赋值

本 PEP 的早期版本曾提议只读属性只能在 __init__ 和类体中赋值。后来的讨论表明，此限制将严重限制 ReadOnly 在不可变类中的可用性，因为不可变类通常不定义 __init__。

fractions.Fraction 是一个不可变类的例子，其属性的初始化发生在 __new__ 和类方法中。然而，与 __init__ 不同，__new__ 和类方法中的赋值可能不健全，因为它们操作的实例可以来自任意位置，包括一个已完成初始化的实例。

我们认为此类型检查功能对只读属性最主要的用例——不可变类——至关重要。因此，本 PEP 随后进行了修改，允许在 初始化 部分描述的一组规则下，在 __new__ 和类方法中赋值。

扩展初始化

dataclasses.__post_init__() 或 attrs 的 初始化钩子 等机制通过提供一组在初始化期间调用的特殊钩子来增强对象创建。

本 PEP 中定义的当前初始化规则禁止在这些方法中对只读属性进行赋值。目前尚不清楚这些规则是否能够以令人满意的方式形成，既能包含这些第三方钩子，又能保持与这些属性的只读性相关的不变性。

Python 类型系统对 __new__ 和 __init__ 的行为有一个详细而冗长的 规范。期望第三方钩子达到相同的详细程度是相当不切实际的。

一个潜在的解决方案可能涉及类型检查器在此方面提供配置，要求最终用户手动指定他们希望允许初始化的方法集。然而，这很容易导致用户错误地或故意破坏上述不变性。对于一个相对小众的功能来说，这也是一个相当大的要求。