From: Scott Gasch <scott@gasch.org>
Date: Mon, 4 Jul 2022 18:23:40 +0000 (-0700)
Subject: Update docs.
X-Git-Url: https://wannabe.guru.org/gitweb/?a=commitdiff_plain;h=6c4760b7071dcf64fed19838a57a2071ea5fcc3b;hp=1172b6778a036431b542fdc89bbfdd13e13b5e8d;p=python_utils.git

Update docs.
---

diff --git a/iter_utils.py b/iter_utils.py
index 00c4221..977cf1d 100644
--- a/iter_utils.py
+++ b/iter_utils.py
@@ -6,7 +6,9 @@ from typing import Any, List, Optional
 
 
 class PeekingIterator(Iterator):
-    """An iterator that lets you peek at the next item on deck.
+    """An iterator that lets you peek() at the next item on deck.
+    Returns None when there is no next item (i.e. when __next__()
+    will produce a StopIteration exception).
 
     >>> p = PeekingIterator(iter(range(3)))
     >>> p.__next__()
@@ -57,6 +59,12 @@ class SamplingIterator(Iterator):
     collects a random sample (of size sample_size) of the stream that can
     be queried at any time.
 
+    Note that until sample_size elements have been seen the sample will
+    be less than sample_size elements in length.
+
+    Note that if sample_size is > len(source_iter) then it will produce
+    a copy of source_iter.
+
     >>> import collections
     >>> import random
 
@@ -89,7 +97,7 @@ class SamplingIterator(Iterator):
         return self
 
     def __next__(self) -> Any:
-        item = self.source_iter.__next__()  # or raise
+        item = self.source_iter.__next__()
         self.stream_length_so_far += 1
 
         # Filling the resovoir