Improve docstrings for sphinx.

[python_utils.git] / histogram.py

diff --git a/histogram.py b/histogram.py
index 52a0d1fad558a493c6e303abdd07a6933053a045..86d0493dc57e32056c4eb04ec4499992d365e542 100644 (file)
--- a/histogram.py
+++ b/histogram.py
@@ -19,11 +19,22 @@ class BucketDetails:
     """A collection of details about the internal histogram buckets."""
 
     num_populated_buckets: int = 0
+    """Count of populated buckets"""
+
     max_population: Optional[int] = None
+    """The max population in a bucket currently"""
+
     last_bucket_start: Optional[int] = None
+    """The last bucket starting point"""
+
     lowest_start: Optional[int] = None
+    """The lowest populated bucket's starting point"""
+
     highest_end: Optional[int] = None
+    """The highest populated bucket's ending point"""
+
     max_label_width: Optional[int] = None
+    """The maximum label width (for display purposes)"""
 
 
 class SimpleHistogram(Generic[T]):
@@ -34,6 +45,14 @@ class SimpleHistogram(Generic[T]):
     NEGATIVE_INFINITY = -math.inf
 
     def __init__(self, buckets: List[Tuple[Bound, Bound]]):
+        """C'tor.
+
+        Args:
+            buckets: a list of [start..end] tuples that define the
+                buckets we are counting population in.  See also
+                :meth:`n_evenly_spaced_buckets` to generate these
+                buckets more easily.
+        """
         from math_utils import NumericPopulation
 
         self.buckets: Dict[Tuple[Bound, Bound], Count] = {}
@@ -53,6 +72,17 @@ class SimpleHistogram(Generic[T]):
         max_bound: T,
         n: int,
     ) -> List[Tuple[int, int]]:
+        """A helper method for generating the buckets argument to
+        our c'tor provided that you want N evenly spaced buckets.
+
+        Args:
+            min_bound: the minimum possible value
+            max_bound: the maximum possible value
+            n: how many buckets to create
+
+        Returns:
+            A list of bounds that define N evenly spaced buckets
+        """
         ret: List[Tuple[int, int]] = []
         stride = int((max_bound - min_bound) / n)
         if stride <= 0:
@@ -64,12 +94,23 @@ class SimpleHistogram(Generic[T]):
         return ret
 
     def _get_bucket(self, item: T) -> Optional[Tuple[int, int]]:
+        """Given an item, what bucket is it in?"""
         for start_end in self.buckets:
             if start_end[0] <= item < start_end[1]:
                 return start_end
         return None
 
     def add_item(self, item: T) -> bool:
+        """Adds a single item to the histogram (reculting in us incrementing
+        the population in the correct bucket.
+
+        Args:
+            item: the item to be added
+
+        Returns:
+            True if the item was successfully added or False if the item
+            is not within the bounds established during class construction.
+        """
         bucket = self._get_bucket(item)
         if bucket is None:
             return False
@@ -84,12 +125,24 @@ class SimpleHistogram(Generic[T]):
         return True
 
     def add_items(self, lst: Iterable[T]) -> bool:
+        """Adds a collection of items to the histogram and increments
+        the correct bucket's population for each item.
+
+        Args:
+            lst: An iterable of items to be added
+
+        Returns:
+            True if all items were added successfully or False if any
+            item was not able to be added because it was not within the
+            bounds established at object construction.
+        """
         all_true = True
         for item in lst:
             all_true = all_true and self.add_item(item)
         return all_true
 
-    def get_bucket_details(self, label_formatter: str) -> BucketDetails:
+    def _get_bucket_details(self, label_formatter: str) -> BucketDetails:
+        """Get the details about one bucket."""
         details = BucketDetails()
         for (start, end), pop in sorted(self.buckets.items(), key=lambda x: x[0]):
             if pop > 0:
@@ -108,9 +161,13 @@ class SimpleHistogram(Generic[T]):
         return details
 
     def __repr__(self, *, width: int = 80, label_formatter: str = '%d') -> str:
+        """Returns a pretty (text) representation of the histogram and
+        some vital stats about the population in it (min, max, mean,
+        median, mode, stdev, etc...)
+        """
         from text_utils import bar_graph
 
-        details = self.get_bucket_details(label_formatter)
+        details = self._get_bucket_details(label_formatter)
         txt = ""
         if details.num_populated_buckets == 0:
             return txt