Pep795 comments 1 (#16)

* Added subclass info; clarified explicit objects

* Bug fixes in the RST

Author: TobiasWrigstad

peps/pep-0795.rst

@@ -404,7 +404,7 @@ whereas ``freeze(o, o.__class__)`` freezes both ``o`` and its class
 explicitly, and at the same time).
 
 .. code-block:: python
-   :caption: **Listing 2.a:** By default, types must be frozen explicitly.
+   :caption: **Listing 2.a:** By default, types must be frozen explicitly or freezing fails.
 
     class Foo:
         pass
@@ -434,7 +434,7 @@ a module called ``immutable``. The listing below revisits the listing
 above and uses the ``@frozen`` decorator on ``Foo``.
 
 .. code-block:: python
-   :caption: **Listing 2.b:** By default, types must be frozen explicitly.
+   :caption: **Listing 2.b:** By default, types must be frozen explicitly or else fail.
 
     from immutable import freeze, is_frozen, frozen
 
@@ -475,7 +475,9 @@ An attempt at mutating ``C`` through ``y`` will result in
 Freeze propagation is similar to how static annotations such
 as ``const`` from C or C++ propagate through a code base, except
 at run-time instead of compile-time. This PEP limits or manages freeze
-propagation by making user-defined types explicitly freezable,
+propagation by only permitting user-defined types to be frozen if they
+are frozen *explicitly* (meaning the user passes a direct reference
+to the type as an argument to ``freeze()`` or uses a decorator on it)
 providing a way to hook into the freeze mechanism, and by
 allowing opting out of freezing altogether or for some limited
 duration.
@@ -661,7 +663,7 @@ supported since the value is immutable.
 
    # freeze(d) -- will fail unless Die is @frozen or @freezable
 
-   freeze(Die)
+   freeze(Die) # After this d can be frozen
    is_frozen(Die) # True
    is_frozen(Die.roll) # True
 
@@ -707,16 +709,16 @@ Note that freezing is *in-place*; ``freeze(obj)`` freezes ``obj``, not a copy.
 
 .. _freezable:
 
-Freezability - Unfreezable and explicitly freezable objects
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Freezability - Unfreezable objects and objects which must be explicitly frozen
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The immutable module provides the function ``set_freezable(obj, status=Yes)``
 which controls if and how an object is freezable. Most
 objects are freezable by default, meaning that freezing can propagate
-to them. However, functions and types are explicitly freezable by
-default (``set_freezable(obj, Explicit)``) meaning that freezing
-will never propagate to them and they can only be frozen when they
-are explicitly passed in to ``freeze()``. Objects can also be marked as
+to them. However, types cannot be frozen through propagation by
+default -- they can only be frozen when they
+are explicitly passed in to ``freeze()`` (``set_freezable(obj, Explicit)``).
+Objects can also be marked as
 unfreezable (``set_freezable(obj, No)``) which will result in an error
 when someone attempts to freeze the object. The values for ``Yes``,
 ``No`` and ``Explicit`` are defined in the immutable module.
@@ -899,6 +901,34 @@ itself during initialisation.
    current_module = sys.modules[__name__]
    set_freezable(current_module, immutable.Proxy)
 
+
+Accessing subclass information and subclassing immutable classes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When a class object becomes immutable, its base classes
+replace their interpreter-local registry of mutable
+subclasses with an internal, shared list of weak references
+to immutable subclasses. All mutable subclasses remain
+recorded in interpreter-local registries (also using
+weak references). Any subsequent subclassing of the base
+in a given interpreter adds the new subclass to that
+interpreter's local registry.
+
+Let ``A`` be an immutable class and ``B`` an immutable subclass of
+``A``. When ``B`` is made immutable, its weak reference is moved
+from the interpreter-local registry into ``A``'s shared list of
+immutable subclasses.
+
+Calls to ``type.__subclasses__()`` in any interpreter return
+a fresh list containing all live immutable subclasses plus
+the interpreter's own mutable subclasses. Publication of
+immutable subclasses across interpreters is eventually
+consistent.
+
+Note that once a class is immutable, reassignment of
+``__bases__`` is prohibited.
+
+
 .. _summary-2:
 
 Summary
@@ -1164,14 +1194,15 @@ wants to limit immutability to something that happens only
 at creation. This is not compatible with Python patterns like
 monkey patching and cyclic structures. (Or how types are defined.)
 
-By making classes *explicitly freezable* we avoid freezing one
+By making classes require an explicit call to freeze we avoid freezing one
 object propagating to all objects of the same type at the same
 time as we stop careless freezing of objects. To make a class
-freezable, code must explicitly make it so, through an
-``@frozen`` (at definition-time), ``@freezable`` opting in to
-being frozen as a side-effect of freezing an instance, or through
-an explicit call to ``freeze()`` on the type object itself. This
-serves as documentation similar to the ``const`` propagation
+immutable, code must explicitly make it so, through a ``@frozen``
+decorator at definition-time, or through an explicit call to ``freeze()``
+on the type object itself. By using ``@freezable`` a declaration opts
+in to being frozen as a side-effect of freezing an instance.
+(A call to ``set_freezable(cls, Yes)`` has the same effect).
+This serves as documentation similar to the ``const`` propagation
 above, even though -- as Python is a dynamically checked language --
 this ``const``-like propagation will be driven by run-time errors
 rather than compile-time.
@@ -1242,8 +1273,8 @@ and a proxy mode for modules.
 
 **Freezing rules:**
 
-- Objects which are explicitly freezable (this includes all type
-  objects) must be frozen explicitly -- not indirectly
+- Objects which are explicit-only freezable (this includes all type
+  objects) must be frozen by an explicit call to ``freeze`` -- not indirectly
   via freeze propagation. (Other attempts fail.)
 - Freezing an object graph fails if it contains objects that cannot be frozen.
 - An individual object can be made impossible to freeze by setting
@@ -1397,7 +1428,7 @@ freeze.
 Dealing with cyclic dependencies
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Objects that are explicitly freezable can be in a cyclic
+Objects that require explicit freezing can be in a cyclic
 dependency.
 
 .. code-block:: python
@@ -1412,10 +1443,10 @@ dependency.
            self.value = A()
 
 Notably, freezing ``A`` freezes ``A.foo`` which captures ``B``.
-However, since ``B`` is explicitly freezable, freezing ``A.foo``
+However, since ``B`` requires explicit freezing, freezing ``A.foo``
 will fail. Trying to first freeze ``B`` does not solve the
 problem, as ``B.bar`` fails to freeze ``A`` which is also
-explicitly freezable. The solution to this problem is to let
+requires explicit freezing. The solution to this problem is to let
 ``freeze`` take multiple arguments which can be used to resolve
 these kinds of situations: ``freeze(A, B)`` will permit ``A.foo``
 to capture ``B`` because it sees that ``B`` is in the list of