[Checkins] SVN: zc.catalogqueue/trunk/src/zc/catalogqueue/ add helper function to use from evolution code

[Fred L. Drake, Jr.]

Log message for revision 86580:
  add helper function to use from evolution code

Changed:
  U   zc.catalogqueue/trunk/src/zc/catalogqueue/CHANGES.txt
  U   zc.catalogqueue/trunk/src/zc/catalogqueue/queue.py
  U   zc.catalogqueue/trunk/src/zc/catalogqueue/queue.txt

-=-
Modified: zc.catalogqueue/trunk/src/zc/catalogqueue/CHANGES.txt
===================================================================
--- zc.catalogqueue/trunk/src/zc/catalogqueue/CHANGES.txt	2008-05-09 18:13:13 UTC (rev 86579)
+++ zc.catalogqueue/trunk/src/zc/catalogqueue/CHANGES.txt	2008-05-09 18:40:48 UTC (rev 86580)
@@ -15,7 +15,11 @@
 ``ICatalogQueue.totalProcessed``
   Total number of cataloging events processed.
 
+A new function, ``zc.catalogqueue.queue.addLengthSupport()``, has been added
+to help evolve instances created with ``zc.catalogqueue`` version 0.1.  Old
+instances must be evolved to be used with the new version.
 
+
 0.1 (2008-04-16)
 ================
 

Modified: zc.catalogqueue/trunk/src/zc/catalogqueue/queue.py
===================================================================
--- zc.catalogqueue/trunk/src/zc/catalogqueue/queue.py	2008-05-09 18:13:13 UTC (rev 86579)
+++ zc.catalogqueue/trunk/src/zc/catalogqueue/queue.py	2008-05-09 18:40:48 UTC (rev 86580)
@@ -82,3 +82,17 @@
         self.totalProcessed += done
 
         return done
+
+
+def addLengthSupport(queue):
+    """Update an older CatalogQueue to include the length support.
+
+    This should be called by generations that need to update catalog queues.
+
+    """
+    try:
+        queue._length
+    except AttributeError:
+        queue._length = BTrees.Length.Length()
+        for subqueue in queue._queues:
+            queue._length.change(len(subqueue))

Modified: zc.catalogqueue/trunk/src/zc/catalogqueue/queue.txt
===================================================================
--- zc.catalogqueue/trunk/src/zc/catalogqueue/queue.txt	2008-05-09 18:13:13 UTC (rev 86579)
+++ zc.catalogqueue/trunk/src/zc/catalogqueue/queue.txt	2008-05-09 18:40:48 UTC (rev 86580)
@@ -190,3 +190,51 @@
       Couldn't find object for 0
 
     >>> handler.uninstall()
+
+
+Helper function
+---------------
+
+``CatalogQueue`` instances created using release 0.1 will need to be updated
+before they can be used with release 0.2; this is best done as part of a
+generation.
+
+There's a helper function that can be called for catalog queues that will make
+the required changes.  Let's artificially create an instance that matches what
+we'll see when a persistent catalog queue created using release 0.1 is loaded:
+
+    >>> queue = zc.catalogqueue.queue.CatalogQueue()
+    >>> del queue._length
+
+At this point, the ``__len__()`` method will fail:
+
+    >>> len(queue)
+    Traceback (most recent call last):
+    AttributeError: 'CatalogQueue' object has no attribute '_length'
+
+If we use the ``addLengthSupport()`` function, it works just fine:
+
+    >>> zc.catalogqueue.queue.addLengthSupport(queue)
+    >>> len(queue)
+    0
+
+If the queue wasn't empty at the time of the conversion, the length will be
+properly reported after.  We'll construct a legacy instance in much the same
+way:
+
+    >>> queue = zc.catalogqueue.queue.CatalogQueue()
+    >>> queue.add(0)
+    >>> queue.add(1)
+    >>> queue.add(2)
+    >>> queue.update(0)
+    >>> queue.update(1)
+    >>> queue.remove(0)
+    >>> del queue._length
+
+    >>> len(queue)
+    Traceback (most recent call last):
+    AttributeError: 'CatalogQueue' object has no attribute '_length'
+
+    >>> zc.catalogqueue.queue.addLengthSupport(queue)
+    >>> len(queue)
+    3