Classes

Today, there are three major ways of achieving read-only attributes, honored by type checkers:

• annotating the attribute with 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
  

  • Supported by dataclasses (and type checkers since typing#1669).
  • Overriding number is not possible - the specification of Final imposes that the name cannot be overridden in subclasses.
• read-only proxy via @property:

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

  • Overriding number is possible. Type checkers disagree about the specific rules. [1]
  • Read-only at runtime. [2]
  • Requires extra boilerplate.
  • Supported by dataclasses, but does not compose well - the synthesized __init__ and __repr__ will use _number as the parameter/attribute name.
• using a “freezing” mechanism, such as dataclasses.dataclass() or typing.NamedTuple:

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

  • Overriding number is possible in the @dataclass case.
  • Read-only at runtime. [2]
  • No per-attribute control - these mechanisms apply to the whole class.
  • Frozen dataclasses incur some runtime overhead.
  • NamedTuple is still a tuple. Most classes do not need to inherit indexing, iteration, or concatenation.

Protocols

A read-only attribute name: T on a Protocol in principle defines two requirements:

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

Those requirements are satisfiable at runtime by all of the following:

• an object with an attribute name: T,
• a class with a class variable name: ClassVar[T],
• an instance of the class above,
• an object with a @property def name(self) -> T,
• an object with a custom descriptor, such as functools.cached_property().

The current typing spec allows creation of such protocol members using (abstract) properties:

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

This syntax has several drawbacks:

• It is somewhat verbose.
• It is not obvious that the quality conveyed here is the read-only character of a property.
• It is not composable with type qualifiers.
• Not all type checkers agree [3] that all of the above five objects are assignable to this structural type.

Initialization

Assignment to a read-only attribute can only occur in the class declaring the attribute. There is no restriction to how many times the attribute can be assigned to. The assignment must be allowed in the following contexts:

• In __init__, on the instance received as the first parameter (likely, self).
• In __new__, on instances of the declaring class created via a call to a super-class’ __new__ method.
• At declaration in the body of the class.

Additionally, a type checker may choose to allow the assignment:

• In __new__, on instances of the declaring class, without regard to the origin of the instance. (This choice trades soundness, as the instance may already be initialized, for the simplicity of implementation.)
• In @classmethods, on instances of the declaring class created via a call to the class’ or super-class’ __new__ method.

Note that a child class cannot assign to any read-only attributes of a parent class in any of the aforementioned contexts, unless the attribute is redeclared.

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

When a class-level declaration has an initializing value, it can serve as a flyweight default for instances:

class Patient:
    number: ReadOnly[int] = 0

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

Type checkers may choose to warn on read-only attributes which could be left uninitialized after an instance is created (except in stubs, protocols or ABCs):

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

Subtyping

Read-only attributes are covariant. This has a few subtyping implications. Borrowing from PEP 705:

• Read-only attributes can be redeclared as writable attributes, descriptors or class variables:

  @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"
  

• If a read-only attribute is not redeclared, it remains read-only:

  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
  

• Subtypes can narrow the type of read-only attributes:

  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]
  

• Nominal subclasses of protocols and ABCs should redeclare read-only attributes in order to implement them, unless the base class initializes them in some way:

  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)
  

• In a protocol attribute declaration, name: ReadOnly[T] indicates that a structural subtype must support .name access, and the returned value is assignable to 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()
  

Interaction with Other Type Qualifiers

ReadOnly can be used with ClassVar and Annotated in any nesting order:

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)]]

This is consistent with the interaction of ReadOnly and typing.TypedDict defined in PEP 705.

An attribute annotated as both ReadOnly and ClassVar can only be assigned to at declaration in the class body.

An attribute cannot be annotated as both ReadOnly and Final, as the two qualifiers differ in semantics, and Final is generally more restrictive. Final remains allowed as an annotation of attributes that are only implied to be read-only. It can be also used to redeclare a ReadOnly attribute of a base class.

Clarifying Interaction of @property and Protocols

The Protocols section mentions an inconsistency between type checkers in the interpretation of properties in protocols. The problem could be fixed by amending the typing specification, clarifying what implements the read-only quality of such properties.

This PEP makes ReadOnly a better alternative for defining read-only attributes in protocols, superseding the use of properties for this purpose.

Assignment Only in __init__ and Class Body

An earlier version of this PEP proposed that read-only attributes could only be assigned to in __init__ and the class’ body. A later discussion revealed that this restriction would severely limit the usability of ReadOnly within immutable classes, which typically do not define __init__.

fractions.Fraction is one example of an immutable class, where the initialization of its attributes happens within __new__ and classmethods. However, unlike in __init__, the assignment in __new__ and classmethods is potentially unsound, as the instance they work on can be sourced from an arbitrary place, including an already finalized instance.

We find it imperative that this type checking feature is useful to the foremost use site of read-only attributes - immutable classes. Thus, the PEP has changed since to allow assignment in __new__ and classmethods under a set of rules described in the Initialization section.

Extending Initialization

Mechanisms such as dataclasses.__post_init__() or attrs’ initialization hooks augment object creation by providing a set of special hooks which are called during initialization.

The current initialization rules defined in this PEP disallow assignment to read-only attributes in such methods. It is unclear whether the rules could be satisfyingly shaped in a way that is inclusive of those 3rd party hooks, while upkeeping the invariants associated with the read-only-ness of those attributes.

The Python type system has a long and detailed specification regarding the behavior of __new__ and __init__. It is rather unfeasible to expect the same level of detail from 3rd party hooks.

A potential solution would involve type checkers providing configuration in this regard, requiring end users to manually specify a set of methods they wish to allow initialization in. This however could easily result in users mistakenly or purposefully breaking the aforementioned invariants. It is also a fairly big ask for a relatively niche feature.

ReadOnly[ClassVar[...]] and __init_subclass__

Should read-only class variables be assignable to within the declaring class’ __init_subclass__?

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

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

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