Edit doc strings and __repr__ methods for constraints module

Author: peterrrock2

gerrychain/constraints/__init__.py

@@ -34,7 +34,6 @@
 and should return whether or not the instance is valid according to their
 rules. Many top-level functions following this signature in this module are
 examples of this.
-
 """
 
 from .bounds import (LowerBound, SelfConfiguringLowerBound,

gerrychain/constraints/bounds.py

@@ -1,3 +1,7 @@
+from typing import Callable, Tuple
+from ..partition import Partition
+
+
 class Bounds:
     """
     Wrapper for numeric-validators to enforce upper and lower limits.
@@ -8,23 +12,28 @@ class Bounds:
 
     """
 
-    def __init__(self, func, bounds):
+    def __init__(self, func: Callable, bounds: Tuple[float, float]) -> None:
         """
         :param func: Numeric validator function. Should return an iterable of values.
+        :type func: Callable
         :param bounds: Tuple of (lower, upper) numeric bounds.
+        :type bounds: Tuple[float, float]
         """
         self.func = func
         self.bounds = bounds
 
-    def __call__(self, *args, **kwargs):
+    def __call__(self, *args, **kwargs) -> bool:
         lower, upper = self.bounds
         values = self.func(*args, **kwargs)
         return lower <= min(values) and max(values) <= upper
 
     @property
-    def __name__(self):
+    def __name__(self) -> str:
         return "Bounds({},{})".format(self.func.__name__, str(self.bounds))
 
+    def __repr__(self) -> str:
+        return "<{}>".format(self.__name__)
+
 
 class UpperBound:
     """
@@ -33,25 +42,26 @@ class UpperBound:
     This class is meant to be called as a function after instantiation; its
     return is ``True`` if the numeric validator is within a set upper limit,
     and ``False`` otherwise.
-
     """
 
-    def __init__(self, func, bound):
+    def __init__(self, func: Callable, bound: float) -> None:
         """
         :param func: Numeric validator function. Should return a comparable value.
+        :type func: Callable
         :param bounds: Comparable upper bound.
+        :type bounds: float
         """
         self.func = func
         self.bound = bound
 
-    def __call__(self, *args, **kwargs):
+    def __call__(self, *args, **kwargs) -> bool:
         return self.func(*args, **kwargs) <= self.bound
 
     @property
-    def __name__(self):
+    def __name__(self) -> str:
         return "UpperBound({} >= {})".format(self.func.__name__, self.bound)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return "<{}>".format(self.__name__)
 
 
@@ -62,25 +72,26 @@ class LowerBound:
     This class is meant to be called as a function after instantiation; its
     return is ``True`` if the numeric validator is within a set lower limit,
     and ``False`` otherwise.
-
     """
 
-    def __init__(self, func, bound):
+    def __init__(self, func: Callable, bound: float) -> None:
         """
         :param func: Numeric validator function. Should return a comparable value.
+        :type func: Callable
         :param bounds: Comparable lower bound.
+        :type bounds: float
         """
         self.func = func
         self.bound = bound
 
-    def __call__(self, *args, **kwargs):
+    def __call__(self, *args, **kwargs) -> bool:
         return self.func(*args, **kwargs) >= self.bound
 
     @property
-    def __name__(self):
+    def __name__(self) -> str:
         return "LowerBound({} <= {})".format(self.func.__name__, self.bound)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return "<{}>".format(self.__name__)
 
 
@@ -94,21 +105,28 @@ class SelfConfiguringUpperBound:
     This class is meant to be called as a function after instantiation; its
     return is ``True`` if the numeric validator is within a set upper limit,
     and ``False`` otherwise.
-
     """
 
-    def __init__(self, func):
+    def __init__(self, func: Callable) -> None:
         """
         :param func: Numeric validator function.
+        :type func: Callable
         """
         self.func = func
         self.bound = None
 
-    def __call__(self, partition):
+    def __call__(self, partition: Partition) -> bool:
         if not self.bound:
             self.bound = self.func(partition)
         return self.func(partition) <= self.bound
 
+    @property
+    def __name__(self) -> str:
+        return "SelfConfiguringUpperBound({})".format(self.func.__name__)
+
+    def __repr__(self) -> str:
+        return "<{}>".format(self.__name__)
+
 
 class SelfConfiguringLowerBound:
     """
@@ -120,36 +138,73 @@ class SelfConfiguringLowerBound:
     This class is meant to be called as a function after instantiation; its
     return is ``True`` if the numeric validator is within a set lower limit,
     and ``False`` otherwise.
-
     """
 
-    def __init__(self, func, epsilon=0.05):
+    def __init__(self, func: Callable, epsilon: float = 0.05) -> None:
         """
         :param func: Numeric validator function.
-        :param epsilon: Initial "wiggle room" that the validator allows.
+        :type func: Callable
+        :param epsilon: Initial population deviation allowable by the validator.
+        :type epsilon: float
         """
         self.func = func
         self.bound = None
         self.epsilon = epsilon
-        self.__name__ = func.__name__
 
-    def __call__(self, partition):
+    def __call__(self, partition: Partition) -> bool:
         if not self.bound:
             self.bound = self.func(partition) - self.epsilon
         return self.func(partition) >= self.bound
 
+    @property
+    def __name__(self) -> str:
+        return "SelfConfiguringLowerBound({})".format(self.func.__name__)
+
+    def __repr__(self) -> str:
+        return "<{}>".format(self.__name__)
+
 
 class WithinPercentRangeOfBounds:
-    def __init__(self, func, percent):
+    """
+    Wrapper for numeric-validators to enforce upper and lower limits
+    determined by a percentage of the initial value.
+
+    When instantiated, the initial upper and lower bounds are set as the
+    initial value of the numeric-validator times (1 ± percent).
+
+    This class is meant to be called as a function after instantiation; its
+    return is ``True`` if the numeric validator is within the desired
+    percentage range of the initial value, and ``False`` otherwise.
+    """
+
+    def __init__(self, func: Callable, percent: float) -> None:
+        """
+        :param func: Numeric validator function.
+        :type func: Callable
+        :param percent: Percentage of the initial value to use as the bounds.
+        :type percent: float
+
+        :return: None
+
+        .. Warning::
+            The percentage is assumed to be in the range [0.0, 100.0].
+        """
         self.func = func
         self.percent = float(percent) / 100.0
         self.lbound = None
         self.ubound = None
 
-    def __call__(self, partition):
+    def __call__(self, partition: Partition) -> bool:
         if not (self.lbound and self.ubound):
             self.lbound = self.func(partition) * (1.0 - self.percent)
             self.ubound = self.func(partition) * (1.0 + self.percent)
             return True
         else:
             return self.lbound <= self.func(partition) <= self.ubound
+
+    @property
+    def __name__(self) -> str:
+        return "WithinPercentRangeOfBounds({})".format(self.func.__name__)
+
+    def __repr__(self) -> str:
+        return "<{}>".format(self.__name__)

gerrychain/constraints/compactness.py

@@ -1,22 +1,63 @@
-
+from ..partition import Partition
 import math
 
+
 from .bounds import SelfConfiguringLowerBound, SelfConfiguringUpperBound
 
 
-def L1_reciprocal_polsby_popper(partition):
+def L1_reciprocal_polsby_popper(partition: Partition) -> float:
+    """
+    Returns the $L^1$ norm of the reciprocal Polsby-Popper scores
+    for the given partition
+
+    :param partition: Partition representing a districting plan
+    :type partition: Partition
+
+    :return: $L^1$ norm of the reciprocal Polsby-Popper scores
+    :rtype: float
+    """
     return sum(1 / value for value in partition["polsby_popper"].values())
 
 
-def L1_polsby_popper(partition):
+def L1_polsby_popper(partition: Partition) -> float:
+    """
+    Returns the $L^1$ norm of the Polsby-Popper scores
+    for the given partition
+
+    :param partition: Partition representing a districting plan
+    :type partition: Partition
+
+    :return: $L^1$ norm of the reciprocal Polsby-Popper scores
+    :rtype: float
+    """
     return sum(value for value in partition["polsby_popper"].values())
 
 
-def L2_polsby_popper(partition):
+def L2_polsby_popper(partition: Partition) -> float:
+    """
+    Returns the $L^2$ norm of the Polsby-Popper scores
+    for the given partition.
+
+    :param partition: Partition representing a districting plan
+    :type partition: Partition
+
+    :return: $L^2$ norm of the Polsby-Popper scores
+    :rtype: float
+    """
     return math.sqrt(sum(value ** 2 for value in partition["polsby_popper"].values()))
 
 
 def L_minus_1_polsby_popper(partition):
+    """
+    Returns the $L^{-1}$ norm of the Polsby-Popper scores
+    for the given partition.
+
+    :param partition: Partition representing a districting plan
+    :type partition: Partition
+
+    :return: $L^{-1}$ norm of the Polsby-Popper scores
+    :rtype: float
+    """
     return len(partition.parts) / sum(
         1 / value for value in partition["polsby_popper"].values()
     )