[Checkins] SVN: zc.intid/trunk/src/zc/intid/ better explain subclassing support

[Fred Drake]

Log message for revision 105911:
  better explain subclassing support

Changed:
  U   zc.intid/trunk/src/zc/intid/__init__.py
  U   zc.intid/trunk/src/zc/intid/tests.py
  U   zc.intid/trunk/src/zc/intid/utility.py

-=-
Modified: zc.intid/trunk/src/zc/intid/__init__.py
===================================================================
--- zc.intid/trunk/src/zc/intid/__init__.py	2009-11-20 15:45:26 UTC (rev 105910)
+++ zc.intid/trunk/src/zc/intid/__init__.py	2009-11-20 16:00:12 UTC (rev 105911)
@@ -14,6 +14,15 @@
 """\
 Interfaces for the unique id utility.
 
+Note that most of these interfaces present identical method signatures
+to those of their zope.intid counterparts.  This includes everything
+that comprises the ``IIntIds`` interface.
+
+Note that the contracts for these APIs differs, primarily in not
+requiring ``IKeyReference`` support.
+
+The IIntIdsSubclassOverride and event interfaces are new.
+
 """
 
 import zope.interface
@@ -83,9 +92,29 @@
     """
 
 
-class IIntIdsSubclassOverride(zope.interface.Interface):
-    """Methods that subclasses can usefully override."""
+class IIntIdsSubclass(zope.interface.Interface):
+    """Additional interface that subclasses can usefully use."""
 
+    family = zope.interface.Attribute(
+        """BTree family used for this id utility.
+
+        This will be either BTree.family32 or BTree.family64.
+
+        This may not be modified, but may be used to create additional
+        structures of the same integer family as the ``refs`` structure.
+
+        """)
+
+    refs = zope.interface.Attribute(
+        """BTree mapping from id to object.
+
+        Subclasses can use this to determine whether an id has already
+        been assigned.
+
+        This should not be directly modified by subclasses.
+
+        """)
+
     def generateId(ob):
         """Return a new iid that isn't already used.
 
@@ -94,6 +123,8 @@
         The default behavior is to generate arbitrary integers without
         reference to the objects they're generated for.
 
+        This method may be overriden.
+
         """
 
 

Modified: zc.intid/trunk/src/zc/intid/tests.py
===================================================================
--- zc.intid/trunk/src/zc/intid/tests.py	2009-11-20 15:45:26 UTC (rev 105910)
+++ zc.intid/trunk/src/zc/intid/tests.py	2009-11-20 16:00:12 UTC (rev 105911)
@@ -41,8 +41,9 @@
         zope.event.subscribers.remove(self.events.append)
 
     def test_interface(self):
-        zope.interface.verify.verifyObject(
-            zc.intid.IIntIds, self.createIntIds())
+        u = self.createIntIds()
+        zope.interface.verify.verifyObject(zc.intid.IIntIds, u)
+        zope.interface.verify.verifyObject(zc.intid.IIntIdsSubclass, u)
 
     def test_non_keyreferences(self):
         #

Modified: zc.intid/trunk/src/zc/intid/utility.py
===================================================================
--- zc.intid/trunk/src/zc/intid/utility.py	2009-11-20 15:45:26 UTC (rev 105910)
+++ zc.intid/trunk/src/zc/intid/utility.py	2009-11-20 16:00:12 UTC (rev 105911)
@@ -43,7 +43,7 @@
 
     zope.interface.implements(
         zc.intid.IIntIds,
-        zc.intid.IIntIdsSubclassOverride,
+        zc.intid.IIntIdsSubclass,
         zope.location.ILocation)
 
     __parent__ = None