docs(other): add doctest examples to fischer_yates_shuffle

other/fischer_yates_shuffle.py

@@ -11,6 +11,19 @@
 
 
 def fisher_yates_shuffle(data: list) -> list[Any]:
+    """
+    In-place random shuffle of a list using the Fisher–Yates algorithm.
+
+    The output is a permutation of the input. Since the operation is random,
+    we assert permutation properties rather than exact order in doctests.
+
+    >>> data = [1, 2, 3, 4]
+    >>> shuffled = fisher_yates_shuffle(data.copy())
+    >>> sorted(shuffled) == [1, 2, 3, 4]
+    True
+    >>> len(shuffled) == len(set(shuffled))
+    True
+    """
     for _ in range(len(data)):
         a = random.randint(0, len(data) - 1)
         b = random.randint(0, len(data) - 1)

other/linear_congruential_generator.py

@@ -1,3 +1,21 @@
+"""
+Linear Congruential Generator (LCG)
+https://en.wikipedia.org/wiki/Linear_congruential_generator
+
+This module implements a simple linear congruential generator.  It is intended
+for educational purposes, not for cryptographic use.
+
+>>> lcg = LinearCongruentialGenerator(2, 3, 9, seed=1)
+>>> [lcg.next_number() for _ in range(5)]
+[5, 4, 2, 7, 8]
+
+The generated values are always in the half-open interval [0, modulo):
+
+>>> lcg = LinearCongruentialGenerator(2, 3, 9, seed=1)
+>>> all(0 <= lcg.next_number() < 9 for _ in range(10))
+True
+"""
+
 __author__ = "Tobias Carryer"
 
 from time import time
@@ -28,9 +46,15 @@ def __init__(self, multiplier, increment, modulo, seed=int(time())):  # noqa: B0
 
     def next_number(self):
         """
+        Generate the next number in the sequence.
+
         The smallest number that can be generated is zero.
-        The largest number that can be generated is modulo-1. modulo is set in the
-        constructor.
+        The largest number that can be generated is ``modulo - 1``. ``modulo`` is
+        set in the constructor.
+
+        >>> lcg = LinearCongruentialGenerator(5, 1, 16, seed=0)
+        >>> [lcg.next_number() for _ in range(4)]
+        [1, 6, 15, 12]
         """
         self.seed = (self.multiplier * self.seed + self.increment) % self.modulo
         return self.seed