z3c.batching 3.0

简单批量处理

此模块实现了一种简单的批量机制，允许您将一个大型序列拆分为更小的批量。让我们先创建一个简单的列表，它将成为我们的完整序列

在空根上批量处理

>>> from z3c.batching.batch import Batch
>>> batch = Batch([], size=3)
>>> len(batch)
0
>>> bool(batch)
False
>>> 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']

现在我们可以为这个序列创建一个批量。让我们将批量大小设为3

>>> batch = Batch(sequence, size=3)

批量的第一个参数始终是完整序列。如果没有指定起始元素，则批量从第一个元素开始

>>> list(batch)
['one', 'two', 'three']

通常在构造函数中指定起始索引

>>> batch = Batch(sequence, start=6, size=3)
>>> list(batch)
['seven', 'eight', 'nine']

请注意，起始索引是一个索引，从0开始。如果起始索引大于序列的最大索引，则会引发索引错误

>>> Batch(sequence, start=15, size=3)
Traceback (most recent call last):
...
IndexError: start index key out of range

批量实现了有限序列接口，因此支持一些标准方法。例如，您可以要求批量返回其长度

>>> len(batch)
3

请注意，长度返回批量的实际大小，而不是我们要求的大小

>>> len(Batch(sequence, start=12, size=3))
1

像任何序列一样，一个非空批量在布尔上下文中为真值

>>> bool(batch)
True

您还可以通过索引获取元素，该索引相对于批次

>>> batch[0]
'seven'
>>> batch[1]
'eight'
>>> batch[2]
'nine'

切片

>>> batch[:1]
['seven']

>>> batch[1:2]
['eight']

>>> batch[1:]
['eight', 'nine']

>>> batch[:]
['seven', 'eight', 'nine']

>>> batch[10:]
[]

如果您请求的索引超出了范围，则会引发索引错误

>>> batch[3]
Traceback (most recent call last):
...
IndexError: batch index out of range

您还可以遍历批次

>>> iterator = iter(batch)
>>> next(iterator)
'seven'
>>> next(iterator)
'eight'
>>> next(iterator)
'nine'

批次还实现了IReadSequence接口的一些功能

>>> '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

除了所有这些常用API方法之外，还有一些设计用来简化您生活的属性。起始位置和大小是已指定的

>>> batch.start
6
>>> batch.size
3

批次结束索引立即计算

>>> batch.end
8

UI通常需要计算批次数量和总批次数量

>>> batch.number
3
>>> batch.total
5

您还可以请求下一批次

>>> batch.next
<Batch start=9, size=3>

如果当前批次是最后一个，则下一批次为None

>>> Batch(sequence, start=12, size=3).next is None
True

上一批次显示上一批次

>>> batch.previous
<Batch start=3, size=3>

如果当前批次是第一个，则上一批次为None

>>> Batch(sequence, start=0, size=3).previous is None
True

最后两个属性用于处理批次内的元素。它们请求批次的第一个和最后一个元素

>>> batch.firstElement
'seven'

>>> batch.lastElement
'nine'

总批次

>>> batch = Batch(sequence[:-1], size=3)
>>> batch.total
4

我们可以访问所有批次

>>> 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>

切片

>>> 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>]

大型批量列表的批量邻域

当完整的批次列表太大，无法在用户界面中显示时，我们只想显示所有批次的一个子集。为此提供了一个辅助函数

首先构建一个大的批次序列（或其他任何内容）

>>> batches = range(100)

然后只提取第一个和最后一个元素，以及第46个元素（索引=45）的邻近区域。我们想要左侧3个邻居，右侧5个邻居

>>> 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”可以用于在用户界面中显示分隔符（请参阅z3c.table）

子集批量处理

>>> from z3c.batching.subset import SubsetBatch

有时（出于性能原因），即使用户需要批处理UI，我们也要限制计算范围到用户实际显示的值子集。

由于我们用数据子集初始化批次，因此我们还需要显式提供完整数据集的长度。

让我们创建一个数据子集

>>> data = range(20, 30)

我们将它用作较大数据集的一部分

>>> batch = SubsetBatch(data, length=50, start=20, size=10)

完整API检查

>>> batch.firstElement
20
>>> batch.lastElement
29
>>> batch.index
2
>>> batch.number
3
>>> batch.total
5
>>> batch[2]
22
>>> len(batch)
10
>>> batch[-1] == batch.lastElement
True
>>> [item for item in batch]
[20, 21, 22, 23, 24, 25, 26, 27, 28, 29]

>>> batch.next
<EmptyBatch start=30, size=10>
>>> batch.previous
<EmptyBatch start=10, size=10>
>>> batch.next.previous == batch
True
>>> 22 in batch
True
>>> 10 in batch
False
>>> batch[5:8]
[25, 26, 27]

您在上面已经看到，连续的批次是EmptyBatch类的实例。由于这些实例不包含数据，我们引发错误以确保没有批次提供者尝试显示项目数据

>>> empty = batch.next
>>> empty
<EmptyBatch start=30, size=10>
>>> empty.firstElement
Traceback (most recent call last):
...
ValueError: EmptyBatch holds no item
>>> empty.lastElement
Traceback (most recent call last):
...
ValueError: EmptyBatch holds no item
>>> empty[0]
Traceback (most recent call last):
...
ValueError: EmptyBatch holds no item
>>> [item for item in empty]
Traceback (most recent call last):
...
ValueError: EmptyBatch holds no item

3.0 (2023-02-24)

• 支持Python 3.10、3.11。

• 不再支持Python 2.7、3.5、3.6。

• 支持Python 3.8和3.9。

• 不再支持Python 3.4。

2.2 (2018-10-20)

• 支持Python 3.6、3.7和PyPy3。

• 不再支持Python 2.6和3.3。

2.1.0 (2016-06-05)

• 支持Python 3.3到3.5。

2.0.1 (2015-11-09)

• 标准化命名空间__init__

2.0.0 (2013-02-25)

• 新功能：子集批次。有时（出于性能原因），即使用户需要批处理UI，我们也要限制计算范围到用户实际显示的值子集。

• 将batch.Batch注册为命名（"z3c.batching.batch"）工厂。

1.1.0 (2008-11-12)

• 添加了一个函数，用于从大型批次列表中构建当前批次的小邻域列表。（从z3c.table提取）

• 真正修复了批次切片的bug

1.0.1 (2008-09-09)

• 修复了批次切片的bug。

1.0.0 (2008-02-18)

• 初始版本。