More polishing

gvanrossum · Mar 18, 2017 · Mar 5, 2017 · Mar 5, 2017 · Mar 5, 2017 · Mar 6, 2017
commit 5d9fb7cfe0a4b6a74d1d390616142775d484c669
diff --git a/pep-05xx.txt b/pep-05xx.txt
@@ -354,7 +354,7 @@ non-protocol member. Examples::
 
   class Template(Protocol):
       name: str        # This is a protocol member
-      value: int = 0   # This one too
+      value: int = 0   # This one too (with default)
       __private: bool  # This is NOT a protocol member
 
       def method(self) -> None:
@@ -373,57 +373,82 @@ Explicitly declaring implementation
 To explicitly declare that a certain class implements a given protocols, they
 can be used as regular base classes. In this case:
 
-* A protocol class could define default implementations for some methods
+* A class could use implementations of some methods in protocols, both
+  protocol members with default implementations and non-protocol members
   (``typing.Sequence`` is an example with useful default methods).
-  In particular, a protocol could provide a default implementation
-  of ``__init__`` that could be used in explicit subclasses.
+  In particular, a protocol could provide a default implementation of
+  ``__init__`` that could be used in explicit subclasses.
   The default implementations will not be used if the subtype relationship
   is implicit and only via structural subtyping -- the semantics of
-  inheritance is not changed.
+  inheritance is not changed. Examples::
+
+    from typing import Protocol
+
+    class PColor(Protocol):
+        def description(self) -> str:
+            ...
+        def simple_description(self) -> str:  # this is a non-protocol member
+            rerun 'nice color'
+        @abstractmethod
+        def add_int(self, x: int) -> int:     # protocol member with default
+            return 42
+
+    class SimpleColor(PColor):
+        def description(self) -> str:
+            return super().simple_description()
+        def add_int(self, x: int) -> int:
+            return super().add_int(x) + x
+
+    class BadColor:
+        def description(self) -> str:
+            return 'not so nice'
+
+    simple: SimpleColor
+    def represent(c: PColor) -> None:
+        ...
+    represent(simple) # OK
+    represent(BadColor()) # Error, 'to_int' is not implemented implicitly
 
 * Second, type checker will statically enforce that a class
   actually implements a protocol correctly. In particular, type checker will
-  always require members without default implementation, to be defined in
-  a subclass that explicitly subclasses the protocol.
+  always require members without default implementation to be defined in
+  a subclass that explicitly subclasses the protocol::
 
-The general philosophy is that protocols are mostly like regular ABCs,
-but a static type checker will handle them specially.
-In particular, a class can explicitly inherit from multiple protocols.
-In this case every method is resolved using normal MRO procedure and type
-checker verifies that all subtyping is correct. Note that a concrete method
-with appropriate type signature can override abstract but not vice versa.
-Examples::
+    from typing import Protocol, Tuple
 
-  from typing import Protocol, Tuple
+    class RGB(Protocol):
+        rgb: Tuple[int, int, int]
+        def intensity(self) -> int:
+            ...
+        @abstractmethod
+        def to_bytes(self) -> bytes:
+            return b''
 
-  class PColor(Protocol):
-      rgb: Tuple[int, int, int]
-      def description(self) -> str:
-          ...
-      def simple_description(self) -> str: # This is non-protocol member
-          rerun 'nice color'
-      @abstractmethod
-      def to_bytes(self) -> bytes:
-          return b''
+    class Point(RGB):
+        def __init__(self, red: int, green: int, blue: str) -> None:
+            self.rgb = red, green, blue  # Error, 'blue' must be 'int'
+        # Error, 'intensity' is not defined!
 
-  class SimpleColor(PColor):
-      def __init__(se;f, red: int, green: int, blue: str) -> None:
-          self.rgb = red, green, blue # Error, last element is 'str' not 'int'
-      def description(self) -> str:
-          return super().simple_description()
-      # Error, 'to_bytes' is not implemented.
-      # Default implementation is not implicitly used.
+        # Note that 'to_bytes' is not required, this is safe
+        # since the default implementation is actually in the MRO.
+
+The general philosophy is that protocols are mostly like regular ABCs,
+but a static type checker will handle them specially.
+In particular, a class can explicitly inherit from multiple protocols.
+In this case methods are resolved using normal MRO and type checker verifies
+that all subtyping are correct. Note that a concrete method with appropriate
+type signature can override protocol method but not vice versa. Examples::
 
   class A(Protocol):
       def m(self) -> None: ...
       def foo(self) -> int: ...
-      def bar(self) -> str: ...
   class B(Protocol):
-      def m(self) -> None: print('hi')
+      def m(self) -> None: print('Hi')
+      def bar(self) -> str: ...
 
-  class C(A, B): # Error, abstract 'A.m' can't override non-abstract 'B.m'
+  class C(A, B): # Fails typecheck, protocol member 'A.m' can't override 'B.m'
       ...
-  class C(B, A): # OK
+  class D(B, A): # OK
       def bar(self) -> str:
           return 'bar'
       # Error, 'foo' is still not implemented.
@@ -435,9 +460,9 @@ a protocol unless it also has ``Protocol`` as an explicit base class.
 Merging and extending protocols
 -------------------------------
 
-I think that we should support subprotocols. A subprotocol can be defined
+Subprotocols are also supported. A subprotocol can be defined
 by having both one or more protocols as the explicit base classes and also
-having typing.Protocol as an immediate base class::
+having ``typing.Protocol`` as an immediate base class::
 
   from typing import Sized, Protocol
 
@@ -446,9 +471,9 @@ having typing.Protocol as an immediate base class::
           ...
 
 Now the protocol ``SizedAndCloseable`` is a protocol with two methods,
-``__len__`` and ``close``. Alternatively, we could have implemented it
-like this, assuming the existence of ``SupportsClose``
-from an earlier example::
+``__len__`` and ``close``. Alternatively, one can implement it
+like this, assuming the existence of ``SupportsClose`` from
+the previous example::
 
   from typing import Sized
 
@@ -457,12 +482,12 @@ from an earlier example::
   class SizedAndCloseable(Protocol, Sized, SupportsClose):
       pass
 
-The two definitions of ``SizedAndClosable`` would be equivalent.
-Subclass relationships between protocols aren't meaningful when
-considering subtyping, as we only use structural compatibility
-as the criterion, not the MRO.
+The two definitions of ``SizedAndClosable`` are equivalent.
+Subclass relationships between protocols are not meaningful when
+considering subtyping, since the structural compatibility is
+the criterion, not the MRO.
 
-If we omit ``Protocol`` in the base class list, this would be regular
+If one omits ``Protocol`` in the base class list, this would be regular
 (non-protocol) class that must implement ``Sized``. If ``Protocol``
 is included in the base class list, all the other base classes
 must be protocols. A protocol can't extend a regular class.
@@ -599,11 +624,24 @@ the behavior of ``Type[]`` is not changed.
 ------------------------------
 
 Protocols are essentially anonymous. To emphasize this point, static type
-checkers might refuse the protocol classes inside ``NewType(...)`` to avoid an
-illusion that a distinct type is provided.
+checkers might refuse the protocol classes inside ``NewType()`` to avoid an
+illusion that a distinct type is provided::
+
+  form typing import NewType , Protocol, Iterator
+
+  class Id(Protocol):
+      code: int
+      secrets: Iterator[bytes]
+
+  UserId = NewType('UserId', Id)  # Error, can't provide distinct type
 
 On the contrary, type aliases are fully supported, including generic type
-aliases.
+aliases::
+
+  from typing import TypeVar, Reversible, Iterable, Sized
+
+  T = TypeVar('T')
+  CompatReversible = Union[Reversible[T], All[Iterable[T], Sized]]
 
 
 ``@runtime`` decorator and narrowing types by ``isinstance()``
@@ -798,8 +836,8 @@ a bad idea and classes should need to be explicitly marked as protocols,
 as shown in this proposal:
 
 * Protocols don't have some properties of regular classes. In particular,
-  ``isinstance`` is not well-defined for protocols, whereas it's well-defined
-  (and pretty commonly used) for regular classes.
+  ``isinstance`` is not always well-defined for protocols, whereas it's
+  well-defined (and pretty commonly used) for regular classes.
 * Protocol classes should generally not have (many) method implementations,
   as they describe an interface, not an implementation.
   Most classes have many implementations, making them bad protocol classes.