Implement most comments by Łukasz; few more to do

python · gvanrossum · Mar 18, 2017 · Mar 5, 2017 · Mar 5, 2017 · Mar 5, 2017
commit 4dfbfb202cabd6058f00e55ecb7dfa01d7b73faf
diff --git a/pep-0544.txt b/pep-0544.txt
@@ -43,7 +43,7 @@ this conforms to PEP 484::
 The same problem appears with user-defined ABCs: they must be explicitly
 subclassed or registered. This is particularly difficult to do with library
 types as the type objects may be hidden deep in the implementation
-of the library. Moreover, extensive use of ABCs might impose additional
+of the library. Also, extensive use of ABCs might impose additional
 runtime costs.
 
 The intention of this PEP is to solve all these problems
@@ -62,6 +62,9 @@ using structural [wiki-structural]_ subtyping::
   def collect(items: Iterable[int]) -> int: ...
   result: int = collect(Bucket())  # Passes type check
 
+Note that ABCs in ``typing`` module already provide structural behavior
+at runtime, ``isinstance(Bucket(), Iterable)`` returns ``True``.
+The main goal of this proposal is to support such behavior statically.
 The same functionality will be provided for user-defined protocols, as
 specified below. The above code with a protocol class matches common Python
 conventions much better. It is also automatically extensible and works
@@ -107,7 +110,7 @@ Existing Approaches to Structural Subtyping
 Before describing the actual specification, we review and comment on existing
 approaches related to structural subtyping in Python and other languages:
 
-* Zope interfaces [zope-interfaces]_ was one of the first widely used
+* ``zope.interface`` [zope-interfaces]_ was one of the first widely used
   approaches to structural subtyping in Python. It is implemented by providing
   special classes to distinguish interface classes from normal classes,
   to mark interface attributes, and to explicitly declare implementation.
@@ -188,10 +191,10 @@ approaches related to structural subtyping in Python and other languages:
     assert isinstance(MyIterable(), Iterable)
 
   Such behavior seems to be a perfect fit for both runtime and static behavior
-  of protocols. The main goal of this proposal is to support such behavior
-  statically. In addition, to allow users achieving such runtime behavior
-  for user defined protocols a special ``@runtime`` decorator will be
-  provided, see detailed `discussion`_ below.
+  of protocols. As discussed in `rationale`_, we propose to add static support
+  for such behavior. In addition, to allow users to achieve such runtime
+  behavior for *user defined* protocols a special ``@runtime`` decorator will
+  be provided, see detailed `discussion`_ below.
 
 * TypeScript [typescript]_ provides support for user defined classes and
   interfaces. Explicit implementation declaration is not required and
@@ -339,8 +342,8 @@ Static methods, class methods, and properties are equally allowed
 in protocols.
 
 To define a protocol variable, one must use PEP 526 variable
-annotations in the class body. Attributes defined in the body of a method
-by assignment via ``self`` are not allowed. The rationale
+annotations in the class body. Additional attributes *only* defined in
+the body of a method by assignment via ``self`` are not allowed. The rationale
 for this is that the protocol class implementation is often not shared by
 subtypes, so the interface should not depend on the default implementation.
 Examples::
@@ -403,7 +406,7 @@ subtyping -- the semantics of inheritance is not changed. Examples::
     represent(nice) # OK
     represent(another) # Also OK
 
-Note that there are no conceptual difference between explicit an implicit
+Note that there is no conceptual difference between explicit and implicit
 subtypes, the main benefit of explicit subclassing is to get some protocol
 methods "for free". In addition, type checkers can statically verify that
 the class actually implements the protocol correctly::
@@ -421,28 +424,26 @@ the class actually implements the protocol correctly::
 
         # Type checker might warn that 'intensity' is not defined
 
-The general philosophy is that protocols are mostly like regular ABCs,
-but a static type checker will handle them specially. Subclassing a protocol
-class would not turn the subclass into a protocol unless it also has
-``typing.Protocol`` as an explicit base class. Without this base, the class
-is "downgraded" to a regular ABC that cannot be used with structural
-subtyping. See section on `extending`_ for details of defining subprotocols.
-
 A class can explicitly inherit from multiple protocols and also form normal
 classes. In this case methods are resolved using normal MRO and a type checker
 verifies that all subtyping are correct. The semantics of ``@abstractmethod``
 is not changed, all of them must be implemented by an explicit subclass
 before it could be instantiated.
 
 
-.. _extending :
-
 Merging and extending protocols
 -------------------------------
 
-Subprotocols are also supported. A subprotocol can be defined
-by having both one or more protocols as immediate base classes and also
-having ``typing.Protocol`` as an immediate base class::
+The general philosophy is that protocols are mostly like regular ABCs,
+but a static type checker will handle them specially. Subclassing a protocol
+class would not turn the subclass into a protocol unless it also has
+``typing.Protocol`` as an explicit base class. Without this base, the class
+is "downgraded" to a regular ABC that cannot be used with structural
+subtyping.
+
+A subprotocol can be defined by having *both* one or more protocols as
+immediate base classes and also having ``typing.Protocol`` as an immediate
+base class::
 
   from typing import Sized, Protocol
 
@@ -499,7 +500,7 @@ protocols will be useful for representing self-referential data structures
 like trees in an abstract fashion::
 
   class Traversable(Protocol):
-      leafs: Iterable['Traversable']
+      leaves: Iterable['Traversable']
 
 
 Using Protocols
@@ -516,13 +517,13 @@ relationships are subject to the following rules:
 * A concrete type or a protocol ``X`` is a subtype of another protocol ``P``
   if and only if ``X`` implements all protocol members of ``P``. In other
   words, subtyping with respect to a protocol is always structural.
-* Edge case: for recursive protocols, structural subtyping is decided
-  positively for situations where such decision depends on itself. Continuing
-  the previous example::
+* Edge case: for recursive protocols, a class is considered a subtype of
+  the protocol in situations where such decision depends on itself.
+  Continuing the previous example::
 
     class Tree(Generic[T]):
         def __init__(self, value: T,
-                           leafs: 'List[Tree[T]]') -> None:
+                           leaves: 'List[Tree[T]]') -> None:
             self.value = value
             self.leafs = leafs
 
@@ -539,8 +540,8 @@ using structural compatibility instead of compatibility defined by
 inheritance relationships.
 
 
-``Union[]`` and ``All[]``
--------------------------
+Unions and intersections of protocols
+-------------------------------------
 
 ``Union`` of protocol classes behaves the same way as for non-protocol
 classes. For example::
@@ -562,28 +563,28 @@ classes. For example::
           return 0
   finish(GoodJob()) # OK
 
-In addition, we propose to add another special type construct
-``All`` that represents intersection types. Although for normal types
-it is not very useful, there are many situations where a variable should
-implement more than one protocol. Annotation by ``All[Proto1, Proto2, ...]``
-means that a given variable or parameter must implement all protocols
-``Proto1``, ``Proto2``, etc. either implicitly or explicitly. Example::
+One can use multiple inheritance to define an intersection of protocols.
+Example::
 
-  from typing import Sequence, Hashable, All
+  from typing import Sequence, Hashable
+
+  class HashableFloats(Sequence[float], Hashable, Protocol):
+      pass
 
-  def cached_func(args: All[Sequence[float], Hashable]) -> float:
+  def cached_func(args: HashableFloats) -> float:
       ...
-  cached_func((1, 2, 3)) # OK, tuple is hashable and sequence
+  cached_func((1, 2, 3)) # OK, tuple is both hashable and sequence
 
-The interaction between union and intersection types is specified by PEP 483,
-and basically reflects the corresponding interactions for sets.
+If the this will prove to be a widely used scenario. A special ``Intersection``
+type may be added in future as specified by PEP 483.
 
 
 ``Type[]`` with protocols
 -------------------------
 
 Variables and parameters annotated with ``Type[Proto]`` accept only concrete
-(non-protocol) subtypes of ``Proto``. For example::
+(non-protocol) subtypes of ``Proto``. The main reason for this is to allow
+instantiation of parameters with such type. For example::
 
   class Proto(Protocol):
       @abstractmethod
@@ -605,9 +606,10 @@ The same rule applies to variables::
   var = Concrete # OK
   var().meth()   # OK
 
-Assigning a protocol class to a variable is allowed if it is not explicitly
-typed, and such assignment creates a type alias. For non-protocol classes,
-the behavior of ``Type[]`` is not changed.
+Assigning an ABC or a protocol class to a variable is allowed if it is
+not explicitly typed, and such assignment creates a type alias.
+For normal (non-abstract) classes, the behavior of ``Type[]`` is
+not changed.
 
 
 ``NewType()`` and type aliases
@@ -688,18 +690,15 @@ Using Protocols in Python 2.7 - 3.5
 Variable annotation syntax was added in Python 3.6, so that the syntax
 for defining protocol variables proposed in `specification`_ section can't
 be used in earlier versions. To define these in earlier versions of Python
-one can use abstract properties::
+one can use properties::
 
   class Foo(Protocol):
-      @abstractproperty
-      def c(self) -> int: ...
+      @property
+      def c(self) -> int:
+          return 42         # Default value can be provided for property...
 
       @abstractproperty
-      def c(self) -> int:   # Default value can be provided for property.
-          return 0
-
-      @property
-      def e(self) -> int:   # Note, this is not a protocol member.
+      def d(self) -> int:   # ... or it can be abstract
           return 0
 
 In Python 2.7 the function type comments should be used as per PEP 484.
@@ -722,7 +721,7 @@ effects on the core interpreter and standard library except in the
   a protocol or not. Add a class attribute ``__protocol__ = True``
   if that is the case. Verify that a protocol class only has protocol
   base classes in the MRO (except for object).
-* Implement ``@runtime`` that adds all attributes to ``__subclsshook__()``.
+* Implement ``@runtime`` that adds all attributes to ``__subclasshook__()``.
 * All structural subtyping checks will be performed by static type checkers,
   such as ``mypy`` [mypy]_. No additional support for protocol validation will
   be provided at runtime.