Remove internal mutation restriction

Author: Enegg

peps/pep-0767.rst

@@ -30,10 +30,11 @@ Motivation
 
 The Python type system lacks a single concise way to mark an attribute read-only.
 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 removing the ability to reassign or ``del``\ ete an attribute
-at a type checker level, as well as defining a broad interface for structural subtyping.
+(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 removing the ability to externally assign to or ``del``\ ete
+an attribute at a type checker level, as well as defining a broad interface
+for structural subtyping.
 
 .. _classes:
 
@@ -167,6 +168,9 @@ A class with a read-only instance attribute can now be defined as::
 Specification
 =============
 
+Usage
+-----
+
 The :external+py3.13:data:`typing.ReadOnly` :external+typing:term:`type qualifier`
 becomes a valid annotation for :term:`attributes <attribute>` of classes and protocols.
 It can be used at class-level and within ``__init__`` to mark individual attributes read-only::
@@ -179,100 +183,13 @@ It can be used at class-level and within ``__init__`` to mark individual attribu
             self.name: ReadOnly[str] = name
 
 Use of bare ``ReadOnly`` (without ``[<type>]``) is not allowed.
-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.)
-
-Use of ``ReadOnly`` in annotations at other sites where it currently has no meaning
-(such as local/global variables or function parameters) is considered out of scope
-for this PEP.
-
-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 at a type checker level:
-
-.. code-block:: python
-
-    from collections import abc
-    from dataclasses import dataclass
-    from typing import Protocol, ReadOnly
-
-
-    @dataclass
-    class Game:
-        name: str
-
-
-    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
-
-
-All instance attributes of frozen dataclasses and ``NamedTuple`` should be
-implied to be read-only. Type checkers may inform that annotating such attributes
-with ``ReadOnly`` is redundant, but it should not be seen as an error:
-
-.. code-block:: python
-
-    from dataclasses import dataclass
-    from typing import NewType, ReadOnly
-
-
-    @dataclass(frozen=True)
-    class Point:
-        x: int            # implicit read-only
-        y: ReadOnly[int]  # ok, redundant
 
+Type checkers should error on any attempt to *externally mutate* an attribute
+annotated with ``ReadOnly``.
 
-    uint = NewType("uint", int)
-
-
-    @dataclass(frozen=True)
-    class UnsignedPoint(Point):
-        x: ReadOnly[uint]  # ok, redundant; narrower type
-        y: Final[uint]     # not redundant, Final imposes extra restrictions; narrower type
-
-.. _init:
-
-Initialization
---------------
-
-Assignment to a read-only attribute can only occur in the class declaring the attribute,
-at sites described below.
-There is no restriction to how many times the attribute can be assigned to.
-
-Instance Attributes
-'''''''''''''''''''
-
-Assignment to a read-only instance attribute must be allowed in the following contexts:
-
-* In ``__init__``, on the instance received as the first parameter (usually, ``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 ``@classmethod``\ s, on instances of the declaring class created via
-  a call to the class' or super-class' ``__new__`` method.
+We define "externally" here as occurring outside the body of the class declaring
+the attribute, or its subclasses.
+"Mutate" means to assign to or ``del``\ ete the attribute.
 
 .. code-block:: python
 
@@ -292,8 +209,7 @@ Additionally, a type checker may choose to allow the assignment:
                 self.songs = list(songs)  # multiple assignments are fine
 
         def clear(self) -> None:
-            # error: assignment to read-only "songs" outside initialization
-            self.songs = []
+            self.songs = []  # ok
 
 
     band = Band(name="Bôa", songs=["Duvet"])
@@ -302,10 +218,6 @@ Additionally, a type checker may choose to allow the assignment:
     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
-
 .. code-block:: python
 
     # a simplified immutable Fraction class
@@ -336,61 +248,76 @@ Additionally, a type checker may choose to allow the assignment:
             self.numerator, self.denominator = f.as_integer_ratio()
             return self
 
-Class Attributes
-''''''''''''''''
 
-Read-only class attributes are attributes annotated as both ``ReadOnly`` and ``ClassVar``.
-Assignment to such attributes must be allowed in the following contexts:
+It should also be error to delete an attribute annotated as ``Final``.
+(This is not currently specified.)
 
-* At declaration in the body of the class.
-* In ``__init_subclass__``, on the class object received as the first parameter (usually, ``cls``).
+Use of ``ReadOnly`` in annotations at other sites where it currently has no meaning
+(such as local/global variables or function parameters) is considered out of scope
+for this PEP.
+
+``ReadOnly`` does not influence the mutability of the attribute's value. Immutable
+protocols and :mod:`collections <collections.abc>` may be used in combination
+with ``ReadOnly`` to forbid mutation of those values at a type checker level:
 
 .. code-block:: python
 
-    class URI:
-        protocol: ReadOnly[ClassVar[str]] = ""
+    from collections import abc
+    from dataclasses import dataclass
+    from typing import Protocol, ReadOnly
 
-        def __init_subclass__(cls, protocol: str = "") -> None:
-            cls.protocol = protocol
 
-    class File(URI, protocol="file"): ...
+    @dataclass
+    class Game:
+        name: str
 
-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:
+
+    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 "append"!
+        shelf.games[0].name = "Blue Shift"  # ok: "name" is not read-only
+        shelf.games = []                    # error: "games" is read-only
+
+
+All instance attributes of frozen dataclasses and ``NamedTuple`` should be
+implied to be read-only. Type checkers may inform that annotating such attributes
+with ``ReadOnly`` is redundant, but it should not be seen as an error:
 
 .. code-block:: python
 
-    class Patient:
-        number: ReadOnly[int] = 0
+    from dataclasses import dataclass
+    from typing import NewType, ReadOnly
 
-        def __init__(self, number: int | None = None) -> None:
-            if number is not None:
-                self.number = number
 
-.. note::
-    This is possible only in classes without :data:`~object.__slots__`.
-    An attribute included in slots cannot have a class-level default.
+    @dataclass(frozen=True)
+    class Point:
+        x: int            # implicit read-only
+        y: ReadOnly[int]  # ok, redundant
 
-Type checkers may choose to warn on read-only attributes which could 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
-        name: ReadOnly[str]  # error: "name" is never initialized
+    uint = NewType("uint", int)
 
-        def __init__(self) -> None:
-            if random.random() > 0.5:
-                self.id = 123
 
+    @dataclass(frozen=True)
+    class UnsignedPoint(Point):
+        x: ReadOnly[uint]  # ok, redundant; narrower type
+        y: Final[uint]     # not redundant, Final imposes extra restrictions; narrower type
 
-    class HasName(Protocol):
-        name: ReadOnly[str]  # ok
 
 Subtyping
 ---------
 
-The inability to reassign read-only attributes makes them covariant.
+The inability to externally mutate read-only attributes makes them covariant.
 This has a few subtyping implications. Borrowing from :pep:`705#inheritance`:
 
 * Read-only attributes can be redeclared as writable attributes, descriptors
@@ -409,7 +336,7 @@ This has a few subtyping implications. Borrowing from :pep:`705#inheritance`:
 
     game = Game(title="DOOM", year=1993)
     game.year = 1994
-    game.title = "DOOM II"  # ok: attribute is not read-only
+    game.title = "DOOM II"  # ok: attribute is no longer read-only
 
 
     class TitleProxy(HasTitle):
@@ -422,17 +349,13 @@ This has a few subtyping implications. Borrowing from :pep:`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:
-            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
+    game.year = 2012  # ok
 
 * Subtypes can :external+typing:term:`narrow` the type of read-only attributes::
 
@@ -526,10 +449,25 @@ Interaction with Other Type Qualifiers
 This is consistent with the interaction of ``ReadOnly`` and :class:`typing.TypedDict`
 defined in :pep:`705`.
 
-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.
+Read-only class attributes can be *internally* assigned to in the same places
+a normal class variable can:
+
+.. code-block:: python
+
+    class URI:
+        protocol: ReadOnly[ClassVar[str]] = ""
+
+        def __init_subclass__(cls, protocol: str = "") -> None:
+            cls.protocol = protocol
+
+    class File(URI, protocol="file"): ...
+
+    URI.protocol = "http"  # error: "protocol" is read-only
+
+``Final`` attributes are implicitly read-only. Annotating an attribute as both
+``Final`` and ``ReadOnly`` is redundant and should be flagged as such by type checkers.
+``Final`` may be used to override both implicit and explicit read-only attributes
+of a base class.
 
 
 Backwards Compatibility
@@ -570,8 +508,8 @@ following the footsteps of :pep:`705#how-to-teach-this`:
   `type qualifiers <https://typing.python.org/en/latest/spec/qualifiers.html>`_ section:
 
     The ``ReadOnly`` type qualifier in class attribute annotations indicates
-    that the attribute of the class may be read, but not reassigned or ``del``\ eted.
-    For usage in ``TypedDict``, see `ReadOnly <https://typing.python.org/en/latest/spec/typeddict.html#typing-readonly-type-qualifier>`_.
+    that outside of the class, the attribute may be read but not assigned to
+    or ``del``\ eted. For usage in ``TypedDict``, see `ReadOnly <https://typing.python.org/en/latest/spec/typeddict.html#typing-readonly-type-qualifier>`_.
 
 
 Rejected Ideas
@@ -588,26 +526,22 @@ 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 Scope
+-----------------------------------------------
 
-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__``.
+An earlier version of this PEP specified that internal mutation of read-only
+attributes could only happen in ``__init__`` and at class-level. This was done
+to follow suit the specification of C#'s `readonly <https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/readonly>`__.
 
-:class:`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 :ref:`init` section.
+Later revision of this PEP loosened the restriction to also include ``__new__``,
+``__init_subclass__`` and ``@classmethod``\ s, as it was revealed that the initial
+version would severely limit the usability of ``ReadOnly`` within immutable classes,
+which typically do not define ``__init__``.
 
+Further revision removed this restriction entirely, as it turned out unnecessary
+to achieve soundness of the effects of ``ReadOnly`` as described in this PEP.
+In turn, this allowed to simplify the PEP, and should reduce the complexity
+of type checker implementations.
 
 Allowing Bare ``ReadOnly`` With Initializing Value
 --------------------------------------------------
@@ -637,9 +571,6 @@ Footnotes
     This PEP focuses solely on the type-checking behavior. Nevertheless, it should
     be desirable the name is read-only at runtime.
 
-.. [#final_mutability]
-    As noted above the second-to-last code example of https://typing.python.org/en/latest/spec/qualifiers.html#semantics-and-examples
-
 
 Copyright
 =========