Subtyping

Author: Enegg

peps/pep-0763.rst

@@ -101,7 +101,7 @@ 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]_ 
+2. ``isinstance(obj.name, T)`` [#invalid_typevar]_
 
 The above are satisfiable at runtime by all of the following:
 
@@ -231,17 +231,18 @@ times the attribute can be assigned to in those contexts. Example:
                 self.songs = list(songs)
 
         def clear(self) -> None:
-            # Type check error: assignment to read-only "songs" outside initialization
+            # error: assignment to read-only "songs" outside initialization
             self.songs = []
 
 
     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
+    band.name = "Emma"  # 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__>`_
-may give the attribute a default value, overridable at instance level:
+retain the ability to initialize a read-only attribute both at declaration and
+within ``__init__``:
 
 .. code-block:: python
 
@@ -252,19 +253,138 @@ may give the attribute a default value, overridable at instance level:
             if number is not None:
                 self.number = number
 
-Inheritance
------------
+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::
+
+    class Foo:
+        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.
+
+Subtyping
+---------
+
+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::
+
+    @dataclass
+    class HasTitle:
+        title: ReadOnly[str]
+
+
+    @dataclass
+    class Game(HasTitle):
+        title: str
+        year: int
+
+
+    game = Game(title="DOOM", year=1993)
+    game.year = 1994
+    game.title = "DOOM II"  # ok: attribute is not read-only
+
+
+    class TitleProxy(HasTitle):
+        @functools.cached_property
+        def title(self) -> str: ...
+
+
+    class SharedTitle(HasTitle):
+        title: ClassVar[str] = "Still Grey"
+
+* If a read-only attribute is not redeclared, it remains read-only::
+
+    @dataclass
+    class Game(HasTitle):
+        year: int
+
+
+    game = Game(title="DOOM", year=1993)
+    game.title = "DOOM II"  # error: attribute is read-only
+
+* Subtypes can narrow the type of read-only attributes::
+
+    class GameCollection(Protocol):
+        games: ReadOnly[abc.Collection[Game]]
+
+
+    @dataclass
+    class GameSeries(GameCollection):
+        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::
+
+    class MyBase(abc.ABC):
+        foo: ReadOnly[int]
+        bar: ReadOnly[str] = "abc"
+        baz: ReadOnly[float]
+
+        def __init__(self, baz: float) -> None:
+            self.baz = baz
+
+        @abstractmethod
+        def do_something(self) -> None: ...
+
+
+    @final
+    class MySubclass(MyBase):
+        # error: MySubclass does not override "foo"
+
+        def do_something(self) -> None:
+            print(self.foo, self.bar, self.baz)
+
+* 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``::
+
+    class HasName(Protocol):
+        name: ReadOnly[str]
+
+
+    class NamedAttr:
+        name: str
+
+    class NamedProp:
+        @property
+        def name(self) -> str: ...
+
+    class NamedClassVar:
+        name: ClassVar[str]
+
+    class NamedDescriptor:
+        @cached_property
+        def name(self) -> str: ...
+
+    # all of the following are ok
+    has_name: HasName
+    has_name = NamedAttr()
+    has_name = NamedProp()
+    has_name = NamedClassVar
+    has_name = NamedClassVar()
+    has_name = NamedDescriptor()
 
-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.
+    - 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
 ------------------------------------
@@ -328,6 +448,7 @@ or attrs' `initialization hooks <https://www.attrs.org/en/stable/init.html#hooki
 This has been set aside for now, as defining rules regarding inclusion of
 such methods has proven difficult.
 
+
 Footnotes
 =========