References, changes to Final, open issues

Author: Enegg

peps/pep-0763.rst

@@ -6,7 +6,7 @@ Discussions-To: <REQUIRED: URL of current canonical discussion thread>
 Status: Draft
 Type: Standards Track
 Topic: Typing
-Created: 11-Oct-2024
+Created: ?-Nov-2024
 Python-Version: 3.?
 
 
@@ -18,7 +18,7 @@ to allow defining read-only :class:`typing.TypedDict` items.
 
 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 :class:`typing.Final`.
+are also made to :data:`typing.Final`.
 
 Akin to :pep:`705`, it makes no Python grammar changes. Correct usage of
 read-only attributes is intended to be enforced only by static type checkers.
@@ -27,7 +27,7 @@ read-only attributes is intended to be enforced only by static type checkers.
 Motivation
 ==========
 
-Python type system lacks a single concise way to mark an attribute read-only.
+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.
@@ -52,7 +52,7 @@ There are 3 major ways of achieving read-only attributes, honored by type checke
         def __init__(self, number: int) -> None:
             self.number: Final = number
 
-  - Supported by :mod:`dataclasses` (since `typing#1669 <https://github.com/python/typing/pull/1669>`_).
+  - Supported by :mod:`dataclasses` (and type checkers 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.
 
@@ -116,7 +116,7 @@ do not impact this.
 
 The most common practice is to define such a protocol with a ``@property``::
 
-    class HasName[T](Protocol):
+    class HasName(Protocol):
         @property
         def name(self) -> T: ...
 
@@ -133,22 +133,20 @@ Worse yet, all of that is multiplied for each additional read-only attribute.
 Rationale
 =========
 
-These problems 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`.
+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 the :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
+            self.id: ReadOnly = id
 
-...and a protocol as described in :ref:`protocols` is now just::
+...and a protocol described in :ref:`protocols` is now just::
 
     from typing import Protocol, ReadOnly
 
@@ -160,8 +158,8 @@ A class with a read-only instance attribute can be now defined as such::
     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.
+* A subclass of ``Member`` can redefine ``.id`` as a writable attribute or a
+  :term:`descriptor`. It can also :external+typing:term:`narrow` the type.
 * 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.
@@ -170,47 +168,53 @@ A class with a read-only instance attribute can be now defined as such::
 Specification
 =============
 
-The :external+py3.13:data:`typing.ReadOnly` type qualifier becomes a valid annotation
-for attributes of classes and protocols.
+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 is used to indicate that an attribute should not be reassigned or ``del``\ eted.
+
+The deletability rule should be extended to ``Final`` as well, as it is currently
+not specified.
 
-It remains invalid in annotations of global and local variables, as in those contexts
-it would have the same meaning as using ``Final``.
+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.
 
 Syntax
 ------
 
-``ReadOnly`` can be used at class-level or within ``__init__`` to declare
-an attribute read-only:
+``ReadOnly`` can be used at class-level or within ``__init__`` to mark individual
+attributes read-only:
 
 .. code-block:: python
 
-    class Base:
+    class Book:
         id: ReadOnly[int]
 
-        def __init__(self, id: int, rate: float) -> None:
+        def __init__(self, id: int, name: str) -> None:
             self.id = id
-            self.rate: ReadOnly = rate
+            self.name: ReadOnly = name
 
-The explicit type in ``ReadOnly[<type>]`` can be omitted if an initializing value
-is assigned to the attribute. A type checker should apply its usual type inference
-rules to determine the type of ``rate``.
+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``.
 
-In contexts where an attribute is already implied to be read-only, like in the
-frozen :ref:`classes`, it should be valid to explicitly declare it ``ReadOnly``:
+If an attribute is already implied to be read-only, like in the frozen :ref:`classes`,
+explicit declarations should be permitted and seen as equivalent, except ``Final``
+additionally forbids overriding in subclasses:
 
 .. code-block:: python
 
     @dataclass(frozen=True)
     class Point:
         x: ReadOnly[int]
-        y: ReadOnly[int]
+        y: Final[int]
 
 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 in those contexts. Example:
+times the attribute can be assigned to.
 
 .. code-block:: python
 
@@ -235,38 +239,53 @@ times the attribute can be assigned to in those contexts. Example:
             self.songs = []
 
 
-    band = Band(name="Boa", songs=["Duvet"])
-    band.name = "Emma"  # ok: "name" is not read-only
+    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
 
-Classes which do not define `__slots__ <https://docs.python.org/3/reference/datamodel.html#object.__slots__>`_
-retain the ability to initialize a read-only attribute both at declaration and
-within ``__init__``:
+
+    class SubBand(Band):
+        def __init__(self) -> None:
+            # error: cannot assign to a read-only attribute of base class
+            self.songs = []
+
+An initializing value at a class level can serve as a `flyweight <https://en.wikipedia.org/wiki/Flyweight_pattern>`_
+default for instances:
 
 .. code-block:: python
 
-    class Foo:
-        number: ReadOnly[int] = 0
+    class Patient:
+        number: ReadOnly = 0
 
         def __init__(self, number: int | None = None) -> None:
             if number is not None:
                 self.number = number
 
-Type checkers should warn on attributes declared ``ReadOnly`` which may be left
-uninitialized after ``__init__`` exits, unless the class is a protocol or an ABC::
+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__``.
 
-    class Foo:
+.. 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``.
+
+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::
+
+    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
 
-This rule stems from the fact the body of the class declaring the attribute is
-the only place able to initialize it, in contrast to non-read-only attributes,
-which could be initialized outside of the class body.
+
+    class HasName(Protocol):
+        name: ReadOnly[str]  # ok
 
 Subtyping
 ---------
@@ -275,7 +294,7 @@ Read-only attributes are covariant. This has a few subtyping implications.
 Borrowing from :pep:`PEP 705 <705#inheritance>`:
 
 * Read-only attributes can be redeclared as writable attributes, descriptors
-  and class variables::
+  or class variables::
 
     @dataclass
     class HasTitle:
@@ -311,7 +330,7 @@ Borrowing from :pep:`PEP 705 <705#inheritance>`:
     game = Game(title="DOOM", year=1993)
     game.title = "DOOM II"  # error: attribute is read-only
 
-* Subtypes can narrow the type of read-only attributes::
+* Subtypes can :external+typing:term:`narrow` the type of read-only attributes::
 
     class GameCollection(Protocol):
         games: ReadOnly[abc.Collection[Game]]
@@ -322,8 +341,8 @@ Borrowing from :pep:`PEP 705 <705#inheritance>`:
         name: str
         games: ReadOnly[list[Game]]  # ok: list[Game] is assignable to Collection[Game]
 
-* In nominal subclasses of protocols and ABCs, a read-only attribute should be
-  considered abstract, unless it is initialized::
+* 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]
@@ -334,14 +353,14 @@ Borrowing from :pep:`PEP 705 <705#inheritance>`:
             self.baz = baz
 
         @abstractmethod
-        def do_something(self) -> None: ...
+        def pprint(self) -> None: ...
 
 
     @final
     class MySubclass(MyBase):
         # error: MySubclass does not override "foo"
 
-        def do_something(self) -> None:
+        def pprint(self) -> None:
             print(self.foo, self.bar, self.baz)
 
 * In a protocol attribute declaration, ``name: ReadOnly[T]`` indicates that a structural
@@ -373,19 +392,6 @@ Borrowing from :pep:`PEP 705 <705#inheritance>`:
     has_name = NamedClassVar()
     has_name = NamedDescriptor()
 
-
-Changes to ``Final``
---------------------
-
-.. TODO
-    - deletability
-    - final in protocols?
-    - interaction of Final and ReadOnly - once parity changes are done, the
-      following shouldn't be true:
-      ``ReadOnly`` cannot be combined with ``Final``, as the two qualifiers differ in
-      initialization rules, leading to ambiguity and/or significance of ordering.
-    - section on "Type consistency"?
-
 Interaction with other special types
 ------------------------------------
 
@@ -409,6 +415,9 @@ defined in :pep:`705`.
 ``ClassVar`` excludes read-only attributes from being assignable to within
 initialization methods.
 
+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.
+
 
 Backwards Compatibility
 =======================
@@ -435,18 +444,81 @@ How to Teach This
 [How to teach users, new and experienced, how to apply the PEP to their work.]
 
 
-Rejected ideas
-==============
+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
+------------------------
+
+Mechanisms such as :func:`dataclasses.__post_init__` or attrs' `initialization hooks <https://www.attrs.org/en/stable/init.html#hooking-yourself-into-initialization>`_
+augment initialization by providing a set of dunder hooks which will be called
+once during instance creation. The current rules would disallow assignment in those
+hooks. Specifying any single method in the pep isn't enough, as the naming and
+functionality differs between mechanisms (``__post_init__`` vs ``__attrs_post_init__``).
+
+``ReadOnly[ClassVar[...]]`` and ``__init_subclass__``
+-----------------------------------------------------
+
+Should this be allowed?
+
+.. code-block:: python
+
+    class URI:
+        protocol: ReadOnly[ClassVar[str]] = ""
+
+        def __init_subclass__(cls, protocol: str = "") -> None:
+            cls.foo = protocol
+
+    class File(URI, protocol="file"): ...
 
-Assignment in ``__post_init__``
--------------------------------
+``Final`` in protocols
+----------------------
 
-An earlier version of this PEP specified that assignment to read-only attributes
-may also be permitted within methods augmenting initialization, such as
-dataclasses' `__post_init__ <https://docs.python.org/3/library/dataclasses.html#dataclasses.__post_init__>`_
-or attrs' `initialization hooks <https://www.attrs.org/en/stable/init.html#hooking-yourself-into-initialization>`_.
-This has been set aside for now, as defining rules regarding inclusion of
-such methods has proven difficult.
+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
@@ -463,8 +535,8 @@ Footnotes
     be desirable the name is read-only at runtime.
 
 .. [#invalid_typevar]
-    The implied type variable is not valid in this context. It has been used here
-    for ease of demonstration.
+    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>`_.
 
 
 Copyright