Add __new__ and precise initialization, TypeScript, ReadOnly must have a type, better immutability examples, yeet changes to Final

Author: Enegg

peps/pep-0767.rst

@@ -1,5 +1,5 @@
 PEP: 767
-Title: Classes & protocols: Read-only attributes
+Title: Read-only class and protocol attributes
 Author: <REQUIRED: list of authors' real names and optionally, email addrs>
 Sponsor: Carl Meyer <carl@oddbird.net>
 Discussions-To: <REQUIRED: URL of current canonical discussion thread>
@@ -20,17 +20,19 @@ This PEP proposes expanding the scope of ``ReadOnly`` to class and protocol
 attributes, as a single concise way to mark them read-only. Some parity changes
 are also made to :data:`typing.Final`.
 
-Akin to :pep:`705`, it makes no changes to setting attributes at runtime. Correct usage of
-read-only attributes is intended to be enforced only by static type checkers.
+Akin to the :pep:`705`, it makes no changes to setting attributes at runtime. Correct
+usage of read-only attributes is intended to be enforced only by static type checkers.
 
 
 Motivation
 ==========
 
 The Python type system lacks a single concise way to mark an :term:`attribute` read-only.
-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.
+This feature is present in other statically and gradually typed languages
+(such as `C# <https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/readonly>`_
+or `TypeScript <https://www.typescriptlang.org/docs/handbook/2/objects.html#readonly-properties>`_),
+and is useful for restricting attribute reassignment at a type checker level,
+as well as defining a broad interface for structural subtyping.
 
 .. _classes:
 
@@ -78,11 +80,11 @@ Today, there are three major ways of achieving read-only attributes, honored by
 
     @dataclass(frozen=True)
     class Foo:
-        number: int
+        number: int  # implicitly read-only
 
 
     class Bar(NamedTuple):
-        number: int
+        number: int  # implicitly read-only
 
   - Overriding ``number`` is possible in the ``@dataclass`` case.
   - Read-only at runtime. [#runtime]_
@@ -97,8 +99,8 @@ Protocols
 ---------
 
 Paraphrasing `this post <https://github.com/python/typing/discussions/1525>`_,
-there is no way of defining an attribute ``name: T`` on a :class:`~typing.Protocol`, such that the only
-requirements to satisfy are:
+there is no way of defining an attribute ``name: T`` on a :class:`~typing.Protocol`,
+such that the only requirements to satisfy are:
 
 1. ``hasattr(obj, "name")``
 2. ``isinstance(obj.name, T)`` [#invalid_typevar]_
@@ -135,7 +137,7 @@ Rationale
 
 These problems can be resolved by an attribute-level :external+typing:term:`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`.
+and the newly proposed changes complement its semantics defined in the :pep:`705`.
 
 A class with a read-only instance attribute can now be defined as::
 
@@ -144,7 +146,7 @@ A class with a read-only instance attribute can now be defined as::
 
     class Member:
         def __init__(self, id: int) -> None:
-            self.id: ReadOnly = id
+            self.id: ReadOnly[int] = id
 
 ...and the protocol described in :ref:`protocols` is now just::
 
@@ -170,51 +172,98 @@ Specification
 
 The :external+py3.13:data:`typing.ReadOnly` :external+typing:term:`type qualifier`
 becomes a valid annotation for :term:`attributes <attribute>` of classes and protocols.
-Type checkers should error on any attempt to reassign or ``del``\ ete an attribute annotated with ``ReadOnly``.
+It can be used at class-level or within ``__init__`` to mark individual attributes read-only::
+
+    class Book:
+        id: ReadOnly[int]
+
+        def __init__(self, id: int, name: str) -> None:
+            self.id = id
+            self.name: ReadOnly[str] = name
+
+Type checkers should error on any attempt to reassign or ``del``\ ete an attribute
+annotated with ``ReadOnly``.
 
 Type checkers should also error on any attempt to delete an attribute annotated as ``Final``.
 (This is not currently specified.)
 
-Akin to ``Final``, read-only attributes do not influence the mutability of
-the assigned object. Immutable ABCs and containers may be used in combination with
-``ReadOnly`` to prevent mutation of such values.
+Akin to ``Final`` [#final_mutability]_, ``ReadOnly`` does not influence how
+type checkers perceive the mutability of the assigned object. Immutable :term:`ABCs <abstract base class>`
+and :mod:`containers <collections.abc>` may be used in combination with ``ReadOnly``
+to forbid mutation of such values:
 
-Syntax
-------
+.. code-block:: python
 
-``ReadOnly`` can be used at class-level or within ``__init__`` to mark individual
-attributes read-only:
+    from collections import abc
+    from dataclasses import dataclass
+    from typing import Protocol, ReadOnly
 
-.. code-block:: python
 
-    class Book:
-        id: ReadOnly[int]
+    @dataclass
+    class Game:
+        name: str
 
-        def __init__(self, id: int, name: str) -> None:
-            self.id = id
-            self.name: ReadOnly = name
 
-The explicit type in ``ReadOnly[<type>]`` can be omitted if the declaration has
-an initializing value. A type checker should apply its usual type inference
-rules to determine the type of ``name``.
+    class HasGames[T: abc.Collection[Game]](Protocol):
+        games: ReadOnly[T]
+
+
+    def add_games(shelf: HasGames[list[Game]]) -> None:
+        shelf.games.append(Game("Half-Life"))  # ok: list is mutable
+        shelf.games[-1].name = "Black Mesa"    # ok: "name" is not read-only
+        shelf.games = []                       # error: "games" is read-only
+        del shelf.games                        # error: "games" is read-only and cannot be deleted
+
+
+    def read_games(shelf: HasGames[abc.Sequence[Game]]) -> None:
+        shelf.games.append(...)             # error: "Sequence" has no attribute "append"
+        shelf.games[0].name = "Blue Shift"  # ok: "name" is not read-only
+        shelf.games = []                    # error: "games" is read-only
+
 
-If an attribute is already implied to be read-only, like in frozen :ref:`classes`,
-explicit declarations should be permitted and seen as equivalent, except that ``Final``
-additionally forbids overriding in subclasses:
+All instance attributes of frozen dataclasses and ``NamedTuple`` should be
+implied to be read-only. Type checkers **should not** flag redundant annotations
+of such attributes with ``ReadOnly``:
 
 .. code-block:: python
 
+    from dataclasses import dataclass
+    from typing import NewType, ReadOnly
+
+
     @dataclass(frozen=True)
     class Point:
-        x: ReadOnly[int]
-        y: Final[int]
+        x: int            # implicit read-only
+        y: ReadOnly[int]  # ok, explicit read-only
+
+
+    uint = NewType("uint", int)
+
+
+    @dataclass(frozen=True)
+    class UnsignedPoint(Point):
+        x: ReadOnly[uint]  # ok, explicit & narrower type
+        y: uint            # ok, narrower type
 
 Initialization
 --------------
 
-Assignment to a ``ReadOnly`` attribute can only occur as a part of the declaration,
-or within ``__init__`` of the same class. There is no restriction to how many
-times the attribute can be assigned to.
+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 can happen only\* in the following contexts:
+
+1. In the body of ``__init__``, on the instance received as the first parameter (likely, ``self``).
+2. In the body of ``__new__``, on instances of the declaring class created via
+   a direct call to a super-class' ``__new__`` method.
+3. In the body of the class.
+
+\*A type checker may choose to allow assignment to read-only attributes on instances
+of the declaring class in ``__new__``, without regard to the origin of the instance.
+(This choice trades soundness, as the instance may already be initialized,
+for the simplicity of implementation.)
+
+Note that child classes cannot assign to read-only attributes of parent classes
+in any of the aforementioned contexts, unless the attributes are redeclared.
 
 .. code-block:: python
 
@@ -240,40 +289,34 @@ times the attribute can be assigned to.
 
 
     band = Band(name="Bôa", songs=["Duvet"])
-    band.name = "Python"  # ok: "name" is not read-only
-    band.songs = []  # error: "songs" is read-only
+    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:
-            # error: cannot assign to a read-only attribute of base class
-            self.songs = []
+            self.songs = []  # error: cannot assign to a read-only attribute of base class
 
-An initializing value at a class level can serve as a `flyweight <https://en.wikipedia.org/wiki/Flyweight_pattern>`_
+When a class-level declaration has an initializing value, it can serve as a `flyweight <https://en.wikipedia.org/wiki/Flyweight_pattern>`_
 default for instances:
 
 .. code-block:: python
 
     class Patient:
-        number: ReadOnly = 0
+        number: ReadOnly[int] = 0
 
         def __init__(self, number: int | None = None) -> None:
             if number is not None:
                 self.number = number
 
-This feature should also be supported by ``Final`` attributes. Specifically,
-``Final`` attributes initialized in a class body **should no longer** imply ``ClassVar``,
-and should remain assignable to within ``__init__``.
-
 .. note::
-    Classes defining :data:`~object.__slots__` cannot make use of this feature.
-    An attribute with a class-level value cannot be included in slots,
-    effectively making it a class variable.
-    Type checkers may warn or suggest explicitly marking the attribute as a ``ClassVar``.
+    This feature conflicts with :data:`~object.__slots__`. An attribute with
+    a class-level value cannot be included in slots, effectively making it a class variable.
 
-Type checkers should warn on read-only attributes which may be left uninitialized
-after ``__init__`` exits, except in :external+typing:term:`stubs <stub>`, protocols or ABCs::
+Type checkers can choose to warn on read-only attributes which may be left uninitialized
+after an instance is created (except in :external+typing:term:`stubs <stub>`,
+protocols or ABCs)::
 
     class Patient:
         id: ReadOnly[int]    # error: "id" is not initialized on all code paths
@@ -322,13 +365,16 @@ Borrowing from :pep:`PEP 705 <705#inheritance>`:
 
 * If a read-only attribute is not redeclared, it remains read-only::
 
-    @dataclass
     class Game(HasTitle):
         year: int
 
+        def __init__(self, title: str, year: int) -> None:
+            self.title = title  # error: cannot assign to a read-only attribute of base class
+            self.year = year
 
-    game = Game(title="DOOM", year=1993)
-    game.title = "DOOM II"  # error: attribute is read-only
+
+    game = Game(title="Robot Wants Kitty", year=2010)
+    game.title = "Robot Wants Puppy"  # error: "title" is read-only
 
 * Subtypes can :external+typing:term:`narrow` the type of read-only attributes::
 
@@ -412,8 +458,8 @@ Interaction with other special types
 This is consistent with the interaction of ``ReadOnly`` and :class:`typing.TypedDict`
 defined in :pep:`705`.
 
-``ClassVar`` excludes read-only attributes from being assignable to within
-initialization methods.
+An attribute annotated as both ``ReadOnly`` and ``ClassVar`` cannot be assigned to
+within ``__new__`` or ``__init__``.
 
 Rules of ``Final`` should take priority when combined with ``ReadOnly``. As such,
 type checkers may warn on the redundancy of combining the two type qualifiers.
@@ -429,7 +475,10 @@ However, caution is advised while using the backported ``typing_extensions.ReadO
 in older versions of Python. Mechanisms inspecting annotations may behave incorrectly
 when encountering ``ReadOnly``; in particular, the ``@dataclass`` decorator
 which `looks for <https://docs.python.org/3/library/dataclasses.html#class-variables>`_
-``ClassVar`` will incorrectly treat ``ReadOnly[ClassVar[...]]`` as an instance attribute.
+``ClassVar`` may incorrectly treat ``ReadOnly[ClassVar[...]]`` as an instance attribute.
+
+In such circumstances, authors should prefer ``ClassVar[ReadOnly[...]]`` over
+``ReadOnly[ClassVar[...]]``.
 
 
 Security Implications
@@ -447,49 +496,6 @@ How to Teach This
 Open Issues
 ===========
 
-Assignment in ``__new__``
--------------------------
-
-Immutable classes like :class:`fractions.Fraction` often do not define ``__init__``;
-instead, they perform initialization in ``__new__`` or classmethods. The proposed
-feature won't be useful to them. 
-
-OTOH, allowing assignment within ``__new__`` (and/or classmethods) could open way
-to non-trivial bugs:
-
-.. code-block:: python
-
-    class Foo:
-        # fully initialized objects
-        object_cache: ReadOnly[ClassVar[dict[int, Self]]] = {}
-
-        foo: ReadOnly[int]
-
-        def __new__(cls, foo: int) -> Self:
-            if foo + 1 in cls.object_cache:
-                # this instance is already initialized
-                self = cls.object_cache[foo + 1]
-
-            else:
-                # this instance is not
-                self = super().__new__(cls)
-
-            # assignment to an object which has been initialized before,
-            # breaking the invariant a read-only attribute can be assigned to
-            # only during its initialization?
-            self.foo = foo
-
-            cls.object_cache[foo] = self
-            return self
-
-To my understanding, properly detecting this problem would require type checkers
-to keep track of the "level of initialization" of an object.
-
-This issue doesn't seem to impact ``__init__``, since it's rather uncommon to
-ever rebind ``self`` within it to any other object, and type checkers could
-flag the action as whole.
-
-
 Extending initialization
 ------------------------
 
@@ -502,7 +508,8 @@ functionality differs between mechanisms (``__post_init__`` vs ``__attrs_post_in
 ``ReadOnly[ClassVar[...]]`` and ``__init_subclass__``
 -----------------------------------------------------
 
-Should this be allowed?
+Should read-only class variables be assignable to within the defining class'
+``__init_subclass__``?
 
 .. code-block:: python
 
@@ -514,12 +521,6 @@ Should this be allowed?
 
     class File(URI, protocol="file"): ...
 
-``Final`` in protocols
-----------------------
-
-It's been `suggested <https://discuss.python.org/t/expanding-readonly-to-normal-classes-protocols/67359/45>`_
-to clarify in this PEP whether ``Final`` should be supported by protocols.
-
 
 Footnotes
 =========
@@ -538,6 +539,9 @@ Footnotes
     The implied type variable is not valid in this context; it has been used for
     the ease of demonstration. See `ClassVar <https://typing.readthedocs.io/en/latest/spec/class-compat.html#classvar>`_.
 
+.. [#final_mutability]
+    As noted above the second-to-last code example of https://typing.readthedocs.io/en/latest/spec/qualifiers.html#semantics-and-examples
+
 
 Copyright
 =========