z3c.batching Batching This package provides simple sequence batching. ====================== Detailed Documentation ====================== .. contents:: 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: Batch on empty root: >>> from z3c.batching.batch import Batch >>> batch = Batch([], size=3) >>> len(batch) 0 >>> batch.firstElement Traceback (most recent call last): ... IndexError: ... >>> batch.lastElement Traceback (most recent call last): ... IndexError: ... >>> batch[0] Traceback (most recent call last): ... IndexError: ... >>> batch.next is None True >>> batch.previous is None True >>> 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: >>> batch = 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 = 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: >>> 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(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' Slicing: >>> batch[:1] ['seven'] >>> batch[1:2] ['eight'] >>> batch[1:] ['eight', 'nine'] >>> batch[:] ['seven', 'eight', 'nine'] >>> batch[10:] [] If you ask for index 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' Batch also implement some of IReadSequence interface: >>> 'eight' in batch True >>> 'ten' in batch False >>> batch == Batch(sequence, start=6, size=3) True >>> batch != Batch(sequence, start=6, size=3) False >>> batch != Batch(sequence, start=3, size=3) True 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 batch 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: >>> 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: >>> 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' Total batches: >>> batch = Batch(sequence[:-1], size=3) >>> batch.total 4 We can have access to all batches: >>> len(batch.batches) 4 >>> batch.batches[0] <Batch start=0, size=3> >>> batch.batches[3] <Batch start=9, size=3> >>> batch.batches[4] Traceback (most recent call last): ... IndexError: ... >>> batch.batches[-1] <Batch start=9, size=3> >>> batch.batches[-2] <Batch start=6, size=3> Slicing: >>> batch.batches[:1] [<Batch start=0, size=3>] >>> batch.batches[:] [<Batch start=0, size=3>, <Batch start=3, size=3>, <Batch start=6, size=3>, <Batch start=9, size=3>] >>> batch.batches[1:2] [<Batch start=3, size=3>] >>> batch.batches[1:] [<Batch start=3, size=3>, <Batch start=6, size=3>, <Batch start=9, size=3>] >>> batch.batches[10:] [] >>> batch.batches[2:50] [<Batch start=6, size=3>, <Batch start=9, size=3>] Batch neighbourhood of a large batch list ----------------------------------------- When the full list of batches is too large to be displayed in a user interface, we want to display only a subset of all the batches. A helper function is provided for that purpose: First build a large sequence of batches (or anything else): >>> batches = range(100) Then extract only the first and last items, as well as the neighbourhood of the 46th item (index = 45). We want 3 neighbours at the left, 5 at the right: >>> from z3c.batching.batch import first_neighbours_last >>> first_neighbours_last(batches, 45, 3, 5) [0, None, 42, 43, 44, 45, 46, 47, 48, 49, 50, None, 99] 'None' can be used to display a separator in a user interface (see z3c.table) ======= CHANGES ======= 1.1.0 (2008-11-12) ------------------ - Added a function to build a small neighbourhood list of the current batch, from a large batch list. (extracted from z3c.table) - Really fixed the bug with batches slicing 1.0.1 (2008-09-09) ------------------ - Fixed bug with batches slicing. 1.0.0 (2008-02-18) ------------------ - Initial release. Zope Corporation and Contributors 2a5d53de05a9e41953ed1826447b07e9a7fa1525 1.1.0