[Checkins] SVN: z3c.batching/trunk/src/z3c/batching/ This is a
simple batching implementation that helps with the management
Stephan Richter
srichter at cosmos.phy.tufts.edu
Tue Jan 30 18:49:32 EST 2007
Log message for revision 72270:
This is a simple batching implementation that helps with the management
of batching. The original code for this is in the bugtracker
application. I adjusted it to a modern API and changed the fields to be
more useful.
Changed:
A z3c.batching/trunk/src/z3c/batching/
A z3c.batching/trunk/src/z3c/batching/README.txt
A z3c.batching/trunk/src/z3c/batching/__init__.py
A z3c.batching/trunk/src/z3c/batching/batch.py
A z3c.batching/trunk/src/z3c/batching/interfaces.py
A z3c.batching/trunk/src/z3c/batching/tests.py
-=-
Added: z3c.batching/trunk/src/z3c/batching/README.txt
===================================================================
--- z3c.batching/trunk/src/z3c/batching/README.txt 2007-01-30 23:47:46 UTC (rev 72269)
+++ z3c.batching/trunk/src/z3c/batching/README.txt 2007-01-30 23:49:31 UTC (rev 72270)
@@ -0,0 +1,123 @@
+===============
+Simple Batching
+===============
+
+This module implements a simple batching mechanism that allows you to split a
+large sequence into smaller batches. Let's start by creating a simple list,
+which will be our full sequence:
+
+ >>> sequence = ['one', 'two', 'three', 'four', 'five', 'six', 'seven',
+ ... 'eight', 'nine', 'ten', 'eleven', 'twelve', 'thirteen']
+
+We can now create a batch for this sequence. Let's make our batch size 3:
+
+ >>> from z3c import batching
+ >>> batch = batching.Batch(sequence, size=3)
+
+The first argument to the batch is always the full sequence. If no start
+element is specified, the batch starts at the first element:
+
+ >>> list(batch)
+ ['one', 'two', 'three']
+
+The start index is commonly specified in the constructor though:
+
+ >>> batch = batching.Batch(sequence, start=6, size=3)
+ >>> list(batch)
+ ['seven', 'eight', 'nine']
+
+Note that the start is an index and starts at zero. If the start index is
+greater than the largest index of the sequence, an index error is raised:
+
+ >>> batching.Batch(sequence, start=15, size=3)
+ Traceback (most recent call last):
+ ...
+ IndexError: start index key out of range
+
+A batch implements the finite sequence interface and thus supports some
+standard methods. For example, you can ask the batch for its length:
+
+ >>> len(batch)
+ 3
+
+Note that the length returns the true size of the batch, not the size we asked
+for:
+
+ >>> len(batching.Batch(sequence, start=12, size=3))
+ 1
+
+You can also get an element by index, which is relative to the batch:
+
+ >>> batch[0]
+ 'seven'
+ >>> batch[1]
+ 'eight'
+ >>> batch[2]
+ 'nine'
+
+If you ask for inex that is out of range, an index error is raised:
+
+ >>> batch[3]
+ Traceback (most recent call last):
+ ...
+ IndexError: batch index out of range
+
+You can also iterate through the batch:
+
+ >>> iterator = iter(batch)
+ >>> iterator.next()
+ 'seven'
+ >>> iterator.next()
+ 'eight'
+ >>> iterator.next()
+ 'nine'
+
+Besides all of those common API methods, there are several properties that were
+designed to make your life simpler. The start and size are specified:
+
+ >>> batch.start
+ 6
+ >>> batch.size
+ 3
+
+The end index of the batch is immediately computed:
+
+ >>> batch.end
+ 8
+
+The UI often requires that the number of the btach and the total number of
+batches is computed:
+
+ >>> batch.number
+ 3
+ >>> batch.total
+ 5
+
+You can also ask for the next batch:
+
+ >>> batch.next
+ <Batch start=9, size=3>
+
+If the current batch is the last one, the next batch is None:
+
+ >>> batching.Batch(sequence, start=12, size=3).next is None
+ True
+
+The previous batch shows the previous batch:
+
+ >>> batch.previous
+ <Batch start=3, size=3>
+
+If the current batch is the first one, the previous batch is None:
+
+ >>> batching.Batch(sequence, start=0, size=3).previous is None
+ True
+
+The final two properties deal with the elements within the batch. They ask for
+the first and last element of the batch:
+
+ >>> batch.firstElement
+ 'seven'
+
+ >>> batch.lastElement
+ 'nine'
Property changes on: z3c.batching/trunk/src/z3c/batching/README.txt
___________________________________________________________________
Name: svn:eol-style
+ native
Added: z3c.batching/trunk/src/z3c/batching/__init__.py
===================================================================
--- z3c.batching/trunk/src/z3c/batching/__init__.py 2007-01-30 23:47:46 UTC (rev 72269)
+++ z3c.batching/trunk/src/z3c/batching/__init__.py 2007-01-30 23:49:31 UTC (rev 72270)
@@ -0,0 +1,3 @@
+# Make a package
+
+from z3c.batching.batch import Batch
Property changes on: z3c.batching/trunk/src/z3c/batching/__init__.py
___________________________________________________________________
Name: svn:keywords
+ Id
Added: z3c.batching/trunk/src/z3c/batching/batch.py
===================================================================
--- z3c.batching/trunk/src/z3c/batching/batch.py 2007-01-30 23:47:46 UTC (rev 72269)
+++ z3c.batching/trunk/src/z3c/batching/batch.py 2007-01-30 23:49:31 UTC (rev 72270)
@@ -0,0 +1,100 @@
+##############################################################################
+#
+# Copyright (c) 2003-2007 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.0 (ZPL). A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""Batching Implementation
+
+$Id$
+"""
+__docformat__ = 'restructuredtext'
+import zope.interface
+from zope.schema.fieldproperty import FieldProperty
+
+from z3c.batching import interfaces
+
+
+class Batch(object):
+ zope.interface.implements(interfaces.IBatch)
+
+ start = FieldProperty(interfaces.IBatch['start'])
+ size = FieldProperty(interfaces.IBatch['size'])
+ end = FieldProperty(interfaces.IBatch['end'])
+
+ def __init__(self, list, start=0, size=20):
+ self._list = list
+ # See interfaces.IBatch
+ self.start = start
+ if len(list) == 0:
+ self.start = -1
+ elif start >= len(list):
+ raise IndexError('start index key out of range')
+ # See interfaces.IBatch
+ self.size = size
+ self._trueSize = size
+ if start + size >= len(list):
+ self._trueSize = len(list) - start
+ # See interfaces.IBatch
+ self.end = start + self._trueSize - 1
+
+ @property
+ def number(self):
+ """See interfaces.IBatch"""
+ return self.start / self.size + 1
+
+ @property
+ def total(self):
+ """See interfaces.IBatch"""
+ return len(self._list) / self.size + 1
+
+ @property
+ def next(self):
+ """See interfaces.IBatch"""
+ start = self.start + self.size
+ if start >= len(self._list):
+ return None
+ return Batch(self._list, start, self.size)
+
+ @property
+ def previous(self):
+ """See interfaces.IBatch"""
+ start = self.start - self.size
+ if start < 0:
+ return None
+ return Batch(self._list, start, self.size)
+
+ @property
+ def firstElement(self):
+ """See interfaces.IBatch"""
+ return self._list[self.start]
+
+ @property
+ def lastElement(self):
+ """See interfaces.IBatch"""
+ return self._list[self.end]
+
+ def __getitem__(self, key):
+ """See zope.interface.common.sequence.IMinimalSequence"""
+ if key >= self._trueSize:
+ raise IndexError('batch index out of range')
+ return self._list[self.start+key]
+
+ def __iter__(self):
+ """See zope.interface.common.sequence.IMinimalSequence"""
+ return iter(self._list[self.start:self.end+1])
+
+ def __len__(self):
+ """See zope.interface.common.sequence.IFiniteSequence"""
+ return self._trueSize
+
+ def __repr__(self):
+ return '<%s start=%i, size=%i>' % (
+ self.__class__.__name__, self.start, self.size)
Property changes on: z3c.batching/trunk/src/z3c/batching/batch.py
___________________________________________________________________
Name: svn:keywords
+ Id
Added: z3c.batching/trunk/src/z3c/batching/interfaces.py
===================================================================
--- z3c.batching/trunk/src/z3c/batching/interfaces.py 2007-01-30 23:47:46 UTC (rev 72269)
+++ z3c.batching/trunk/src/z3c/batching/interfaces.py 2007-01-30 23:49:31 UTC (rev 72270)
@@ -0,0 +1,93 @@
+##############################################################################
+#
+# Copyright (c) 2003 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.0 (ZPL). A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""Batching Support
+
+$Id$
+"""
+__docformat__ = 'restructuredtext'
+from zope.interface.common import sequence
+import zope.schema
+
+class IBatch(sequence.IFiniteSequence):
+ """A Batch represents a sub-list of the full sequence.
+
+ The Batch constructor takes a list (or any list-like object) of elements,
+ a starting index and the size of the batch. From this information all
+ other values are calculated.
+ """
+
+ start = zope.schema.Int(
+ title=u'Start Index',
+ description=(u'The index of the sequence at which the batch starts. '
+ u'If the full sequence is empty, the value is -1.'),
+ min=-1,
+ default=0,
+ required=True)
+
+ size = zope.schema.Int(
+ title=u'Batch Size',
+ description=u'The maximum size of the batch.',
+ min=1,
+ default=20,
+ required=True)
+
+ end = zope.schema.Int(
+ title=u'End Index',
+ description=u'The index of the sequence at which the batch ends.',
+ min=0,
+ default=0,
+ readonly=True,
+ required=True)
+
+ number = zope.schema.Int(
+ title=u'Current Batch Number',
+ description=u'The number of the batch in relation to all batches.',
+ min=1,
+ readonly=True,
+ required=True)
+
+ total = zope.schema.Int(
+ title=u'Total Number of Batches',
+ description=u'The total number of batches available.',
+ min=1,
+ readonly=True,
+ required=True)
+
+ next = zope.schema.Field(
+ title=u'Next Batch',
+ description=u'The next batch of the sequence; ``None`` if last.',
+ readonly=True,
+ required=True)
+
+ previous = zope.schema.Field(
+ title=u'Previous Batch',
+ description=u'The previous batch of the sequence; ``None`` if first.',
+ readonly=True,
+ required=True)
+
+ firstElement = zope.schema.Field(
+ title=u'First Element',
+ description=u'The first element of the batch.',
+ readonly=True,
+ required=True)
+
+ totalElements = zope.schema.Int(
+ title=u'Total Number of Elements',
+ description=u'Return the length of the full sequence.',
+ min=1,
+ readonly=True,
+ required=True)
+
+ def __iter__():
+ """Creates an iterator for the contents of the batch."""
Property changes on: z3c.batching/trunk/src/z3c/batching/interfaces.py
___________________________________________________________________
Name: svn:keywords
+ Id
Added: z3c.batching/trunk/src/z3c/batching/tests.py
===================================================================
--- z3c.batching/trunk/src/z3c/batching/tests.py 2007-01-30 23:47:46 UTC (rev 72269)
+++ z3c.batching/trunk/src/z3c/batching/tests.py 2007-01-30 23:49:31 UTC (rev 72270)
@@ -0,0 +1,32 @@
+##############################################################################
+#
+# Copyright (c) 2006 Lovely Systems and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution.
+# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
+# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
+# FOR A PARTICULAR PURPOSE.
+#
+##############################################################################
+"""Tag test setup
+
+$Id$
+"""
+__docformat__ = "reStructuredText"
+
+import doctest
+import unittest
+from zope.testing.doctestunit import DocFileSuite
+
+def test_suite():
+ return unittest.TestSuite((
+ DocFileSuite(
+ 'README.txt',
+ optionflags=doctest.NORMALIZE_WHITESPACE|doctest.ELLIPSIS),
+ ))
+
+if __name__ == '__main__':
+ unittest.main(defaultTest='test_suite')
Property changes on: z3c.batching/trunk/src/z3c/batching/tests.py
___________________________________________________________________
Name: svn:keywords
+ Id
More information about the Checkins
mailing list