Rationale & specification

Author: Enegg

peps/pep-0763.rst

@@ -26,9 +26,9 @@ Motivation
 ==========
 
 Python type system lacks a single concise way to mark an attribute read-only.
-This feature is common in other object-oriented languages (such as C#), and is
-useful for restricting attribute mutation at a type checker level, as well as
-defining a broad interface for structural subtyping.
+This feature is common in other object-oriented languages (such as `C# <https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/readonly>`_),
+and is useful for restricting attribute mutation at a type checker level, as well
+as defining a broad interface for structural subtyping.
 
 Classes
 -------
@@ -37,32 +37,32 @@ There are 3 major ways of achieving read-only attributes, honored by type checke
 
 * annotating the attribute with :data:`typing.Final`::
 
-      class Foo:
-          number: Final[int]
+    class Foo:
+        number: Final[int]
 
-          def __init__(self, number: int) -> None:
-              self.number = number
+        def __init__(self, number: int) -> None:
+            self.number = number
 
 
-      class Bar:
-          def __init__(self, number: int) -> None:
-              self.number: Final = number
+    class Bar:
+        def __init__(self, number: int) -> None:
+            self.number: Final = number
 
   - Supported by :mod:`dataclasses` (since `typing#1669 <https://github.com/python/typing/pull/1669>`_).
   - Overriding ``number`` is not possible - the specification of ``Final``
     imposes the name cannot be overridden in subclasses.
 
 * read-only proxy via ``@property``::
 
-      class Foo:
-          _number: int
+    class Foo:
+        _number: int
 
-          def __init__(self, number: int) -> None:
-              self._number = number
+        def __init__(self, number: int) -> None:
+            self._number = number
 
-          @property
-          def number(self) -> int:
-              return self._number
+        @property
+        def number(self) -> int:
+            return self._number
 
   - Overriding ``number`` is possible. *Type checkers disagree about the specific rules*. [#overriding_property]_
   - Read-only at runtime. [#runtime]_
@@ -72,20 +72,22 @@ There are 3 major ways of achieving read-only attributes, honored by type checke
 
 * using a "freezing" mechanism, such as :func:`dataclasses.dataclass` or :class:`typing.NamedTuple`::
 
-      @dataclass(frozen=True)
-      class Foo:
-          number: int
+    @dataclass(frozen=True)
+    class Foo:
+        number: int
 
 
-      class Bar(NamedTuple):
-          number: int
+    class Bar(NamedTuple):
+        number: int
 
   - Overriding ``number`` is possible in the ``@dataclass`` case.
   - Read-only at runtime. [#runtime]_
   - No per-attribute control - these methods apply to the whole class.
   - Frozen dataclasses incur some runtime overhead.
   - Not all classes qualify to be a ``NamedTuple``.
 
+.. _protocols:
+
 Protocols
 ---------
 
@@ -122,13 +124,125 @@ Worse yet, all of that is multiplied for each additional read-only attribute.
 Rationale
 =========
 
-[Describe why particular design decisions were made.]
+This problem can be resolved by an attribute-level type qualifier. ``ReadOnly``
+has been chosen for this role, as its name conveys the intent well, and the newly
+proposed changes complement its semantics defined in :pep:`705`.
+
+A class with a read-only instance attribute can be now defined as such::
+
+    from typing import ReadOnly
+
+    class Member:
+        id: ReadOnly[int]
+
+        def __init__(self, id: int) -> None:
+            self.id = id
+
+...and a protocol as described in :ref:`protocols` is now just::
+
+    from typing import Protocol, ReadOnly
+
+    class HasName(Protocol):
+        name: ReadOnly[str]
+
+    def greet(obj: HasName, /) -> str:
+        return f"Hello, {obj.name}!"
+
+A subclass of ``Member`` can redefine ``id`` as a ``property`` or writable
+attribute, while staying compatible with the base class.
+
+The ``HasName`` protocol can be implemented by any mechanism allowing for ``.name`` access.
+
+The ``greet`` function can now accept a wide variety of compatible objects,
+while being explicit about no modifications being done to the input.
 
 
 Specification
 =============
 
-[Describe the syntax and semantics of any new language feature.]
+The :external+py3.13:data:`typing.ReadOnly` type qualifier becomes a valid annotation
+for attributes of classes and protocols.
+
+Classes
+-------
+
+In a class attribute declaration, ``ReadOnly`` indicates that assignment to the
+attribute can only occur as a part of the declaration, or within a set of
+initializing methods in the same class::
+
+    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:
+                # multiple assignments during initialization are fine
+                self.songs = list(songs)
+
+        def clear(self) -> None:
+            self.songs = []  # Type check error: "songs" is read only
+
+
+    band = Band("Boa", ["Duvet"])
+    band.name = "Emma"  # Ok: "name" is not read-only
+    band.songs = []  # Type check error: "songs" is read-only
+    band.songs.append("Twilight")  # Ok: list is mutable
+
+The set of initializing methods consists of ``__new__`` and ``__init__``.
+However, type checkers may permit assignment in additional `special methods <https://docs.python.org/3/glossary.html#term-special-method>`_
+to facilitate 3rd party mechanisms such as dataclasses' `__post_init__ <https://docs.python.org/3/library/dataclasses.html#dataclasses.__post_init__>`_.
+It should be non-ambiguous that those methods are not called outside initialization.
+
+A read-only attribute with an initializer remains assignable to during initialization::
+
+    class Foo:
+        number: ReadOnly[int] = 0
+
+        def __init__(self, number: int | None = None) -> None:
+            if number is not None:
+               self.number = number
+
+Note that this cannot be used in a class defining ``__slots__``, as slots prohibit
+the existence of class-level and instance-level attributes of same name.
+
+Protocols
+---------
+
+In a protocol attribute declaration, ``name: ReadOnly[T]`` indicates that a structural
+subtype must support ``.name`` access, and the returned value is compatible with ``T``.
+
+Interaction with other special types
+------------------------------------
+
+``ReadOnly`` can be used with ``ClassVar`` and ``Annotated`` in any nesting order:
+
+.. code-block:: python
+
+    class Foo:
+        foo: ClassVar[ReadOnly[str]] = "foo"
+        bar: Annotated[ReadOnly[int], Gt(0)]
+
+.. code-block:: python
+
+    class Foo:
+        foo: ReadOnly[ClassVar[str]] = "foo"
+        bar: ReadOnly[Annotated[int, Gt(0)]]
+
+This is consistent with the interaction of ``ReadOnly`` and :class:`typing.TypedDict`
+defined in :pep:`705`.
+
+The combination of ``ReadOnly`` and ``ClassVar`` imposes the attribute must be
+initialized in the class scope, as there are no other valid initialization scopes.
+
+``ReadOnly`` cannot be combined with ``Final``, as the two qualifiers define incompatible
+initialization rules, leading to ambiguity and/or significance of ordering.
 
 
 Backwards Compatibility