Syntax

Author: Enegg

peps/pep-0763.rst

@@ -1,7 +1,7 @@
 PEP: 763
 Title: Classes & protocols: Read-only attributes
 Author: <REQUIRED: list of authors' real names and optionally, email addrs>
-Sponsor: <real name of sponsor>
+Sponsor: Carl Meyer <carl@oddbird.net>
 Discussions-To: <REQUIRED: URL of current canonical discussion thread>
 Status: Draft
 Type: Standards Track
@@ -17,7 +17,9 @@ Abstract
 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.
+attributes, as a single concise way to mark them read-only. Some parity changes
+are also made to :class:`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.
 
@@ -30,6 +32,8 @@ This feature is common in other object-oriented languages (such as `C# <https://
 and is useful for restricting attribute mutation at a type checker level, as well
 as defining a broad interface for structural subtyping.
 
+.. _classes:
+
 Classes
 -------
 
@@ -82,17 +86,19 @@ There are 3 major ways of achieving read-only attributes, honored by type checke
 
   - Overriding ``number`` is possible in the ``@dataclass`` case.
   - Read-only at runtime. [#runtime]_
-  - No per-attribute control - these methods apply to the whole class.
+  - No per-attribute control - these mechanisms apply to the whole class.
   - Frozen dataclasses incur some runtime overhead.
-  - Not all classes qualify to be a ``NamedTuple``.
+  - ``NamedTuple`` is still a ``tuple``. Most classes do not need to inherit
+    indexing, iteration, or concatenation.
 
 .. _protocols:
 
 Protocols
 ---------
 
 Paraphrasing `this post <https://github.com/python/typing/discussions/1525>`_,
-there is no way of defining a :class:`~typing.Protocol`, such that the only requirements to satisfy are:
+there is no way of defining a :class:`~typing.Protocol`, such that the only
+requirements to satisfy are:
 
 1. ``hasattr(obj, name)``
 2. ``isinstance(obj.name, T)`` [#invalid_typevar]_ 
@@ -105,6 +111,9 @@ The above are satisfiable at runtime by all of the following:
 4. an object with a ``@property`` ``def name(self) -> T``,
 5. an object with a custom descriptor, such as :func:`functools.cached_property`.
 
+Note that the attribute being marked ``Final`` or the property defining a setter
+do not impact this.
+
 The most common practice is to define such a protocol with a ``@property``::
 
     class HasName[T](Protocol):
@@ -117,21 +126,22 @@ other than ``property`` are rejected.
 
 Covering the extra possibilities induces a great amount of boilerplate, involving
 creation of an abstract descriptor protocol, possibly also accounting for
-class vs instance level overloads.
+class and instance level overloads.
 Worse yet, all of that is multiplied for each additional read-only attribute.
 
 
 Rationale
 =========
 
-This problem can be resolved by an attribute-level type qualifier. ``ReadOnly``
+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`.
 
 A class with a read-only instance attribute can be now defined as such::
 
     from typing import ReadOnly
 
+
     class Member:
         id: ReadOnly[int]
 
@@ -142,19 +152,19 @@ A class with a read-only instance attribute can be now defined as such::
 
     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.
+* 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
@@ -163,12 +173,46 @@ Specification
 The :external+py3.13:data:`typing.ReadOnly` type qualifier becomes a valid annotation
 for attributes of classes and protocols.
 
-Classes
--------
+It remains invalid in annotations of global and local variables, as in those contexts
+it would have the same meaning as using ``Final``.
+
+Syntax
+------
+
+``ReadOnly`` can be used at class-level or within ``__init__`` to declare
+an attribute read-only:
+
+.. code-block:: python
+
+    class Base:
+        id: ReadOnly[int]
+
+        def __init__(self, id: int, rate: float) -> None:
+            self.id = id
+            self.rate: ReadOnly = rate
+
+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``.
 
-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::
+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``:
+
+.. code-block:: python
+
+    @dataclass(frozen=True)
+    class Point:
+        x: ReadOnly[int]
+        y: ReadOnly[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:
+
+.. code-block:: python
 
     from collections import abc
     from typing import ReadOnly
@@ -187,37 +231,41 @@ initializing methods in the same class::
                 self.songs = list(songs)
 
         def clear(self) -> None:
-            self.songs = []  # Type check error: "songs" is read only
+            # Type check error: assignment to read-only "songs" outside initialization
+            self.songs = []
 
 
-    band = Band("Boa", ["Duvet"])
+    band = Band(name="Boa", songs=["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.
+Classes which do not define `__slots__ <https://docs.python.org/3/reference/datamodel.html#object.__slots__>`_
+may give the attribute a default value, overridable at instance level:
 
-A read-only attribute with an initializer remains assignable to during initialization::
+.. code-block:: python
 
     class Foo:
         number: ReadOnly[int] = 0
 
         def __init__(self, number: int | None = None) -> None:
             if number is not None:
-               self.number = number
+                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
----------
+Inheritance
+-----------
 
 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``.
 
+Changes to ``Final``
+--------------------
+
+.. TODO
+    once changes are done, this probably won'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.
+
 Interaction with other special types
 ------------------------------------
 
@@ -238,11 +286,8 @@ Interaction with other special types
 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.
+``ClassVar`` excludes read-only attributes from being assignable to within
+initialization methods.
 
 
 Backwards Compatibility
@@ -252,10 +297,10 @@ This PEP introduces new contexts where ``ReadOnly`` is valid. Programs inspectin
 those places will have to change to support it. This is expected to mainly affect type checkers.
 
 However, caution is advised while using the backported ``typing_extensions.ReadOnly``
-in older versions of Python, especially in conjunction with other type qualifiers;
-not all nesting orderings might be treated equal. In particular, the ``@dataclass``
-decorator which looks for ``ClassVar`` will incorrectly treat
-``ReadOnly[ClassVar[...]]`` as an instance attribute.
+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.
 
 
 Security Implications
@@ -270,6 +315,19 @@ How to Teach This
 [How to teach users, new and experienced, how to apply the PEP to their work.]
 
 
+Rejected ideas
+==============
+
+Assignment in ``__post_init__``
+-------------------------------
+
+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.
+
 Footnotes
 =========