iter_utils.py

   1 #!/usr/bin/env python3
   2
   3 import random
   4 from collections.abc import Iterator
   5 from typing import Any, List, Optional
   6
   7
   8 class PeekingIterator(Iterator):
   9     """An iterator that lets you peek at the next item on deck.
  10
  11     >>> p = PeekingIterator(iter(range(3)))
  12     >>> p.__next__()
  13     0
  14     >>> p.peek()
  15     1
  16     >>> p.peek()
  17     1
  18     >>> p.__next__()
  19     1
  20     >>> p.__next__()
  21     2
  22     >>> p.peek() == None
  23     True
  24     >>> p.__next__()
  25     Traceback (most recent call last):
  26       ...
  27     StopIteration
  28     """
  29
  30     def __init__(self, source_iter: Iterator):
  31         self.source_iter = source_iter
  32         self.on_deck: List[Any] = []
  33
  34     def __iter__(self) -> Iterator:
  35         return self
  36
  37     def __next__(self) -> Any:
  38         if len(self.on_deck) > 0:
  39             return self.on_deck.pop()
  40         else:
  41             item = self.source_iter.__next__()
  42             return item
  43
  44     def peek(self) -> Optional[Any]:
  45         if len(self.on_deck) > 0:
  46             return self.on_deck[0]
  47         try:
  48             item = self.source_iter.__next__()
  49             self.on_deck.append(item)
  50             return self.peek()
  51         except StopIteration:
  52             return None
  53
  54
  55 class SamplingIterator(Iterator):
  56     """An iterator that simply echoes what source_iter produces but also
  57     collects a random sample (of size sample_size) of the stream that can
  58     be queried via get_random_sample() at any time.
  59
  60     >>> import collections
  61     >>> import random
  62
  63     >>> random.seed(22)
  64     >>> s = SamplingIterator(iter(range(100)), 10)
  65     >>> s.__next__()
  66     0
  67
  68     >>> s.__next__()
  69     1
  70
  71     >>> s.resovoir
  72     [0, 1]
  73
  74     >>> collections.deque(s)
  75     deque([2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99])
  76
  77     >>> s()
  78     [78, 18, 47, 83, 93, 26, 25, 73, 94, 38]
  79
  80     """
  81
  82     def __init__(self, source_iter: Iterator, sample_size: int):
  83         self.source_iter = source_iter
  84         self.sample_size = sample_size
  85         self.resovoir: List[Any] = []
  86         self.stream_length_so_far = 0
  87
  88     def __iter__(self) -> Iterator:
  89         return self
  90
  91     def __next__(self) -> Any:
  92         item = self.source_iter.__next__()  # or raise
  93         self.stream_length_so_far += 1
  94
  95         # Filling the resovoir
  96         pop = len(self.resovoir)
  97         if pop < self.sample_size:
  98             self.resovoir.append(item)
  99             if self.sample_size == (pop + 1):  # just finished filling...
 100                 random.shuffle(self.resovoir)
 101
 102         # Swap this item for one in the resovoir with probabilty
 103         # sample_size / stream_length_so_far.  See:
 104         #
 105         # https://en.wikipedia.org/wiki/Reservoir_sampling
 106         else:
 107             r = random.randint(0, self.stream_length_so_far)
 108             if r < self.sample_size:
 109                 self.resovoir[r] = item
 110         return item
 111
 112     def __call__(self) -> List[Any]:
 113         return self.resovoir
 114
 115
 116 if __name__ == '__main__':
 117     import doctest
 118
 119     doctest.testmod()