Add links + minor changes

python · gvanrossum · Mar 18, 2017 · Mar 5, 2017 · Mar 5, 2017 · Mar 5, 2017
commit 7ea5d41b74fb89f7443fa7312ccd534313bf55b4
diff --git a/pep-05xx.txt b/pep-05xx.txt
@@ -55,6 +55,8 @@ still be implicitly considered a subtype of both ``Sized`` and
 Nominal vs structural subtyping
 -------------------------------
 
+Although structural subtyping is natural for Python programmers
+(explain once more what it is)...
 As discussed in PEP 483, both nominal and structural subtyping have their
 strengths and weaknesses. Therefore, in this PEP do we not propose to propose
 to replace the nominal subtyping described by PEP 484 and currently supported
@@ -74,7 +76,7 @@ stated they are **completely optional**.
 Existing approaches to structural subtyping
 ===========================================
 
-* ``zope.interace``::
+* Zope interfaces::
 
   from zope.interface import Interface
   from zope.interface import Attribute
@@ -97,7 +99,7 @@ Existing approaches to structural subtyping
       def goodmorning(self, guest):
           return "Good morning, %s!" % guest
 
-plus much more detailed runtime constraints::
+plus interface contracts/constraints::
 
   from zope.interface import invariant
 
@@ -113,7 +115,7 @@ plus much more detailed runtime constraints::
 
       invariant(contacts_invariant)
 
-However, this all requires runtime validation.
+Even more is possible. However, this all requires runtime validation.
 
 * TypeScript::
 
@@ -128,12 +130,14 @@ However, this all requires runtime validation.
   let myObj = {size: 10, label: "Size 10 Object"};
   printLabel(myObj);
 
+In addition optional members, always errors on reduntant members.
+
 * Go - everything is an interface
-* ABCs
+* Python abstract base classes
 
 require explicit subclassing or registration.
 
-* ``collections.abc`` (with ``__subclasshook__``)
+* Abstract classes in ``collections.abc`` (with ``__subclasshook__``)
 
 
 Specification
@@ -142,28 +146,30 @@ Specification
 Terminology
 -----------
 
-Let's call them protocols. The reason is that the term iterator protocol,
+We propose to use the term *protocols* 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.
 
-This has the drawback that the term 'protocol' becomes overloaded with
+This has the drawback that the term *protocol* becomes overloaded with
 two subtly different meanings: the first is the traditional, well-known but
-slightly fuzzy concept of protocols such as iterable; the second is the more
-explicitly defined concept of protocols in statically typed code
-(or more generally in code that just uses the typing module).
-I argue that the distinction isn't important most of the time, and in other
-cases people can just add a qualifier such as "protocol classes"
-(for the new-style protocols) or "traditional/non-class/implicit protocols".
-
-Some terminology could be useful here for clarity. If a class includes a
-protocol in its MRO, the class is an (explicit) subclass of the protocol.
-If a class ia a structural subtype of a protocol, it is said to implement
-the protocol and to be compatible with a protocol.
+slightly fuzzy concept of protocols such as iterator; the second is the more
+explicitly defined concept of protocols in statically typed code.
+The distinction is not important most of the time, and in other
+cases we propose to just add a qualifier such as *protocol classes*
+when refering to the static type concept.
+
+If a class includes a protocol in its MRO, the class is an called an *explicit*
+subclass of the protocol. If a class ia a structural subtype of a protocol,
+it is said to implement the protocol and to be compatible with a protocol.
 If a class is compatible with a protocol but the protocol is not included
-in the MRO, the class is an implicit subclass of the protocol.
+in the MRO, the class is an *implicit* subclass of the protocol.
 
-Protocol members.
+The attributes (variables and methods) of a protocol that are mandatory
+for other class in order to be considered a subtype are called
+protocol members. Other members defined in a protocol class are called
+non-protocol members.
 
 
 Defining a Protocol
@@ -617,7 +623,8 @@ do not use them yet.
 Use assignments to check explicitly that a class implements a protocol
 ----------------------------------------------------------------------
 
-I've seen a similar pattern in some Go code that I've reviewed. Example::
+I've seen a similar pattern in some Go code that I've reviewed [golang].
+Example::
 
   class A:
       def __len__(self) -> float:
@@ -642,8 +649,8 @@ References
 .. [mypy]
    http://mypy-lang.org
 
-.. [wiki-structural-subtypin]
-   http://en.wikipedia.org/wiki/...
+.. [wiki-structural-subtyping]
+   https://en.wikipedia.org/wiki/Structural_type_system
 
 .. [typeshed]
    https://github.com/python/typeshed/
@@ -652,31 +659,31 @@ References
    https://github.com/python/typing/issues
 
 .. [pep482]
-   https://hg.python.org/peps/file/tip/pep-0482.txt
+   https://www.python.org/dev/peps/pep-0482/
 
 .. [pep483]
-   https://hg.python.org/peps/file/tip/pep-0483.txt
+   https://www.python.org/dev/peps/pep-0483/
 
 .. [pep484]
-   https://hg.python.org/peps/file/tip/pep-0484.txt
+   https://www.python.org/dev/peps/pep-0484/
 
 .. [pep526]
-   https://hg.python.org/peps/file/tip/pep-0526.txt
+   https://www.python.org/dev/peps/pep-0526/
 
 .. [typescript]
-   https://...
+   https://www.typescriptlang.org/docs/handbook/interfaces.html
 
 .. [golang]
-   https://...
+   https://golang.org/doc/effective_go.html#interfaces_and_types
 
-.. [zope-interface]
-   https://...
+.. [zope-interfaces]
+   https://zopeinterface.readthedocs.io/en/latest/
 
 .. [abstract-base-classes]
-   https://...
+   https://docs.python.org/3/library/abc.html
 
 .. [collections-abc]
-   https://...
+   https://docs.python.org/3/library/collections.abc.html
 
 
 Copyright