Some more reshuffling and formatting

python · gvanrossum · Mar 18, 2017 · Mar 5, 2017 · Mar 5, 2017 · Mar 5, 2017
commit 1ffed9b9a3318fc6942b5431b02007460bec5d3e
diff --git a/pep-05xx.txt b/pep-05xx.txt
@@ -94,66 +94,67 @@ Existing approaches to structural subtyping
 Before describing the actual specification, we review existing approaches to
 structural subtyping in Python and other languges:
 
-* Zope interfaces::
+* Zope interfaces was probably historically first widely used approach to
+  structural subtyping. For example::
 
-  from zope.interface import Interface
-  from zope.interface import Attribute
-  from zope.interface import implements
+    from zope.interface import Interface
+    from zope.interface import Attribute
+    from zope.interface import implements
 
-  class IHost(Interface):
-      """A host object"""
+    class IHost(Interface):
+        """A host object"""
 
-      name = Attribute("Name of host")
+        name = Attribute("Name of host")
 
-      def goodmorning(guest):
-          """Say good morning to guest"""
+        def goodmorning(guest):
+            """Say good morning to guest"""
 
-  class Host(object):
+    class Host(object):
 
-      implements(IHost)
+        implements(IHost)
 
-      name = u''
+        name = u''
 
-      def goodmorning(self, guest):
-          return "Good morning, %s!" % guest
+        def goodmorning(self, guest):
+            return "Good morning, %s!" % guest
 
-plus interface contracts/constraints::
+  plus interface contracts/constraints::
 
-  from zope.interface import invariant
+    from zope.interface import invariant
 
-  def contacts_invariant(obj):
-      if not (obj.email or obj.phone):
-          raise Exception("At least one contact info is required")
+    def contacts_invariant(obj):
+        if not (obj.email or obj.phone):
+            raise Exception("At least one contact info is required")
 
-  class IPerson(Interface):
+    class IPerson(Interface):
 
-      name = Attribute("Name")
-      email = Attribute("Email Address")
-      phone = Attribute("Phone Number")
+        name = Attribute("Name")
+        email = Attribute("Email Address")
+        phone = Attribute("Phone Number")
 
-      invariant(contacts_invariant)
+        invariant(contacts_invariant)
 
-Even more is possible. However, this all requires runtime validation.
+  Even more is possible. However, this all requires runtime validation.
 
-* TypeScript::
+* TypeScript also provides support for user defined interfaces.
+  For example::
 
-  interface LabelledValue {
-      label: string;
-  }
+    interface LabelledValue {
+        label: string;
+    }
 
-  function printLabel(labelledObj: LabelledValue) {
-      console.log(labelledObj.label);
-  }
+    function printLabel(labelledObj: LabelledValue) {
+        console.log(labelledObj.label);
+    }
 
-  let myObj = {size: 10, label: "Size 10 Object"};
-  printLabel(myObj);
+    let myObj = {size: 10, label: "Size 10 Object"};
+    printLabel(myObj);
 
-In addition optional members, always errors on reduntant members.
+  In addition optional members, always errors on reduntant members.
 
 * Go - everything is an interface
 * Python abstract base classes
-
-require explicit subclassing or registration.
+  require explicit subclassing or registration.
 
 * Abstract classes in ``collections.abc`` (with ``__subclasshook__``)
 
@@ -164,8 +165,8 @@ Specification
 Terminology
 -----------
 
-We propose to use the term *protocols* types supoorting structural subtyping.
-The reason is that the term iterator protocol,
+We propose to use the term *protocols* for types supoorting structural
+subtyping. The reason is that the term iterator protocol,
 for example, is widely understood in the community, and coming up with
 a new term for this concept in a statically typed context would just create
 confusion.
@@ -237,7 +238,7 @@ the implementation of the library. Besides, this would be uglier than how
 you'd actually write the code in straight, idiomatic dynamically typed Python.
 The code with a protocol class matches common Python conventions much better.
 It's also automatically extensible and works with additional,
-unrelated classes that happen to implement the required interface.
+unrelated classes that happen to implement the required protocol.
 
 
 Protocol members
@@ -473,11 +474,25 @@ Union[Proto.open() -> int, Proto.open() -> str],
 although it is not a subclass of any of two.
 
 
+``Type[...]`` with protocols
+----------------------------
+
+``Type[...]`` accepts only non-abstract (non-protocol?) classes
+
+copy all stuff from my PR
+
+
+``@runtime`` decorator
+---------------------------
+
+(like in ``collections.abc``), typechecker ensures no empty bodies
+
+
 ``isinstance()`` and narrowing types
 ------------------------------------
 
 ``isinstance(x, Proto)`` and ``issublclass(C, Proto)``
-narrow type if defined with ``@auto_runtime``; ``isinstance(x, Proto[int])``
+narrow type if defined with ``@runtime``; ``isinstance(x, Proto[int])``
 always fails.
 
 We shouldn't implement any magic ``isinstance()`` machinery, as performing
@@ -499,26 +514,11 @@ but this should be specific to these particular classes.
 We need this fallback option anyway for backward compatibility.
 
 
-``Type[...]`` with protocols
-----------------------------
-
-``Type[...]`` accepts only non-abstract (non-protocol?) classes
-
-copy all stuff from my PR
-
-
 Runtime behavior of protocol classes
 ====================================
 
 At runtime normal ABCs, cannot be instantiated.
 
-
-``@auto_runtime`` decorator
----------------------------
-
-(like in ``collections.abc``), typechecker ensures no empty bodies
-
-
 Changes in typing module
 ------------------------
 
@@ -572,22 +572,49 @@ Implementation details
 We'd need to implement at least the following things:
 
 * Define class ``Protocol`` (this could be simple, and would be similar
-to ``Generic``).
+  to ``Generic``).
 * Implement metaclass functionality to detect whether a class is
-a protocol or not. Maybe add a class attribute such as ``__protocol__ = True``
-if that's the case. Verify that a protocol class only has protocol
-base classes in the MRO (except for object).
+  a protocol or not. Maybe add a class attribute such as ``__protocol__ = True``
+  if that's the case. Verify that a protocol class only has protocol
+  base classes in the MRO (except for object).
 * Optionally, override ``isinstance``.
 * Optionally, translate ``...`` class attribute values to
-something else (properties?).
+  something else (properties?).
 
 
 Postponed ideas
 ===============
 
-Should we support optional attributes?
+Make every class a protocol by default
 --------------------------------------
 
+Some languages such as Go make structural subtyping the only or the primary
+form of subtyping. We could achieve a similar result by making all classes
+protocols by default (or even always). However we believe that this would be
+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.
+
+* 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.
+
+* Experience suggests that many classes are not practical as protocols anyway,
+  mainly because their interfaces are too large, complex or
+  implementation-oriented (for example, they may include de facto
+  private attributes and methods without a ``__`` prefix).
+  Most actually useful protocols in existing Python code seem to be implicit.
+  The ABCs in typing and ``collections.abc`` are a kind-of exception, but
+  even they are pretty recent additions to Python and most programmers
+  do not use them yet.
+
+
+Support optional protocol members
+---------------------------------
+
 We can come up with examples where it would be handy to be able to say
 that a method or data attribute does not need to be present in a class
 implementing a protocol, but if it's present, it must conform to a specific
@@ -602,42 +629,15 @@ they are pretty commonly used. If I remember correctly, at least TypeScript
 and Objective-C support a similar concept.
 
 
-Should these be interoperable with other similar implementations?
------------------------------------------------------------------
+Should protocols be interoperable with similar implementations?
+---------------------------------------------------------------
 
 The protocols as described here are basically a small extension to
 the existing concept of ABCs. I argue that this is the way they should
 be understood, instead of as something that replaces Zope interfaces,
 for example.
 
 
-Make every class a protocol by default
---------------------------------------
-
-Some languages such as Go make structural subtyping the only or the primary
-form of subtyping. We could achieve a similar result by making all classes
-protocols by default (or even always). I argue that this would be a bad idea
-and classes should need to be explicitly marked as protocols,
-as shown in my proposal above.
-
-* 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.
-
-* 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.
-
-* Experience suggests that most classes aren't practical as protocols anyway,
-mainly because their interfaces are too large, complex or
-implementation-oriented (for example, they may include de facto
-private attributes and methods without a ``__`` prefix).
-Most actually useful protocols in existing Python code seem to be implicit.
-The ABCs in typing and ``collections.abc`` are a kind-of exception, but
-even they are pretty recent additions to Python and most programmers
-do not use them yet.
-
-
 Use assignments to check explicitly that a class implements a protocol
 ----------------------------------------------------------------------