Add mypy typing

This was mostly straightforward except for a few places where there were
conflicting types documented (usually int instead of float or vice
versa)

There are a few type ignores too since some of the current class
hierarchies cannot be typed. For example, with Store the merge method
accepts a store of the same type which when typed in both the parent and
child classes results in a violation of the Liskov substitution
principle

Author: Kyle-Verhoog

.github/workflows/test.yml

@@ -16,6 +16,8 @@ jobs:
           fetch-depth: 0
       - run: pip install riot==0.8
       - run: riot -v run check_fmt
+      - run: riot -v run -s mypy
+
   test:
     strategy:
       matrix:

README.md

@@ -94,5 +94,12 @@ Format code with
     riot run fmt
 
 
+### Type-checking
+
+Type checking is done with [mypy](http://mypy-lang.org/):
+
+    riot run mypy
+
+
 ## References
 [1] Charles Masson and Jee E Rim and Homin K. Lee. DDSketch: A fast and fully-mergeable quantile sketch with relative-error guarantees. PVLDB, 12(12): 2195-2205, 2019. (The code referenced in the paper, including our implementation of the the Greenwald-Khanna (GK) algorithm, can be found at: https://github.com/DataDog/sketches-py/releases/tag/v0.1 )

ddsketch/ddsketch.py

@@ -34,6 +34,7 @@
 <a href="https://github.com/DataDog/sketches-py/">Python</a>
 <a href="https://github.com/DataDog/sketches-js/">JavaScript</a>
 """
+import typing
 
 from .exception import IllegalArgumentException
 from .exception import UnequalSketchParametersException
@@ -43,6 +44,13 @@
 from .store import DenseStore
 
 
+if typing.TYPE_CHECKING:
+    from typing import Optional
+
+    from .mapping import KeyMapping
+    from .store import Store
+
+
 DEFAULT_REL_ACC = 0.01  # "alpha" in the paper
 DEFAULT_BIN_LIMIT = 2048
 
@@ -73,6 +81,7 @@ def __init__(
         negative_store,
         zero_count,
     ):
+        # type: (KeyMapping, Store, Store, float) -> None
         self.mapping = mapping
         self.store = store
         self.negative_store = negative_store
@@ -85,6 +94,7 @@ def __init__(
         self._sum = 0.0
 
     def __repr__(self):
+        # type: () -> str
         return (
             f"store: {self.store}, negative_store: {self.negative_store}, "
             f"zero_count: {self.zero_count}, count: {self.count}, "
@@ -93,25 +103,30 @@ def __repr__(self):
 
     @property
     def name(self):
+        # type: () -> str
         """str: name of the sketch"""
         return "DDSketch"
 
     @property
     def num_values(self):
+        # type: () -> float
         """float: number of values in the sketch"""
         return self.count
 
     @property
     def avg(self):
+        # type: () -> float
         """float: exact avg of the values added to the sketch"""
         return self.sum / self.count
 
     @property
     def sum(self):
+        # type: () -> float
         """float: exact sum of the values added to the sketch"""
         return self._sum
 
     def add(self, val, weight=1.0):
+        # type: (float, float) -> None
         """Add a value to the sketch."""
         if weight <= 0.0:
             raise IllegalArgumentException("weight must be a positive float")
@@ -132,6 +147,7 @@ def add(self, val, weight=1.0):
             self.max = val
 
     def get_quantile_value(self, quantile):
+        # type: (float) -> Optional[float]
         """the approximate value at the specified quantile
 
         Args:
@@ -158,6 +174,7 @@ def get_quantile_value(self, quantile):
         return quantile_value
 
     def merge(self, sketch):
+        # type: (BaseDDSketch) -> None
         """Merges the other sketch into this one. After this operation, this sketch
         encodes the values that were added to both this and the input sketch.
         """
@@ -187,10 +204,12 @@ def merge(self, sketch):
             self.max = sketch.max
 
     def mergeable(self, other):
+        # type: (BaseDDSketch) -> bool
         """Two sketches can be merged only if their gammas are equal."""
         return self.mapping.gamma == other.mapping.gamma
 
     def copy(self, sketch):
+        # type: (BaseDDSketch) -> None
         """copy the input sketch into this one"""
         self.store.copy(sketch.store)
         self.negative_store.copy(sketch.negative_store)
@@ -210,7 +229,7 @@ class DDSketch(BaseDDSketch):
     """
 
     def __init__(self, relative_accuracy=None):
-
+        # type: (Optional[float]) -> None
         # Make sure the parameters are valid
         if relative_accuracy is None:
             relative_accuracy = DEFAULT_REL_ACC
@@ -234,7 +253,7 @@ class LogCollapsingLowestDenseDDSketch(BaseDDSketch):
     """
 
     def __init__(self, relative_accuracy=None, bin_limit=None):
-
+        # type: (Optional[float], Optional[int]) -> None
         # Make sure the parameters are valid
         if relative_accuracy is None:
             relative_accuracy = DEFAULT_REL_ACC
@@ -264,7 +283,7 @@ class LogCollapsingHighestDenseDDSketch(BaseDDSketch):
     """
 
     def __init__(self, relative_accuracy=None, bin_limit=None):
-
+        # type: (Optional[float], Optional[int]) -> None
         # Make sure the parameters are valid
         if relative_accuracy is None:
             relative_accuracy = DEFAULT_REL_ACC

ddsketch/mapping.py

@@ -40,6 +40,7 @@ class KeyMapping(ABC):
     """
 
     def __init__(self, relative_accuracy, offset=0.0):
+        # type: (float, float) -> None
         if relative_accuracy <= 0 or relative_accuracy >= 1:
             raise IllegalArgumentException("Relative accuracy must be between 0 and 1.")
         self.relative_accuracy = relative_accuracy
@@ -53,19 +54,23 @@ def __init__(self, relative_accuracy, offset=0.0):
 
     @classmethod
     def from_gamma_offset(cls, gamma, offset):
+        # type: (float, float) -> KeyMapping
         """Constructor used by pb.proto"""
         relative_accuracy = (gamma - 1.0) / (gamma + 1.0)
         return cls(relative_accuracy, offset=offset)
 
     @abstractmethod
     def _log_gamma(self, value):
+        # type: (float) -> float
         """Return (an approximation of) the logarithm of the value base gamma"""
 
     @abstractmethod
     def _pow_gamma(self, value):
+        # type: (float) -> float
         """Return (an approximation of) gamma to the power value"""
 
     def key(self, value):
+        # type: (float) -> int
         """
         Args:
             value (float)
@@ -75,6 +80,7 @@ def key(self, value):
         return int(math.ceil(self._log_gamma(value)) + self._offset)
 
     def value(self, key):
+        # type: (int) -> float
         """
         Args:
             key (int)
@@ -91,13 +97,16 @@ class LogarithmicMapping(KeyMapping):
     """
 
     def __init__(self, relative_accuracy, offset=0.0):
+        # type: (float, float) -> None
         super().__init__(relative_accuracy, offset=offset)
         self._multiplier *= math.log(2)
 
     def _log_gamma(self, value):
+        # type: (float) -> float
         return math.log2(value) * self._multiplier
 
     def _pow_gamma(self, value):
+        # type: (float) -> float
         return 2 ** (value / self._multiplier)
 
 
@@ -116,6 +125,7 @@ class LinearlyInterpolatedMapping(KeyMapping):
     linearly interpolating the logarithm in-between."""
 
     def _log2_approx(self, value):
+        # type: (float) -> float
         """approximates log2 by s + f
         where v = (s+1) * 2 ** f  for s in [0, 1)
 
@@ -128,15 +138,18 @@ def _log2_approx(self, value):
         return significand + (exponent - 1)
 
     def _exp2_approx(self, value):
+        # type: (float) -> float
         """inverse of _log2_approx"""
         exponent = math.floor(value) + 1
         mantissa = (value - exponent + 2) / 2.0
         return math.ldexp(mantissa, exponent)
 
     def _log_gamma(self, value):
+        # type: (float) -> float
         return self._log2_approx(value) * self._multiplier
 
     def _pow_gamma(self, value):
+        # type: (float) -> float
         return self._exp2_approx(value / self._multiplier)
 
 
@@ -155,10 +168,12 @@ class CubicallyInterpolatedMapping(KeyMapping):
     C = 10 / 7
 
     def __init__(self, relative_accuracy, offset=0.0):
+        # type: (float, float) -> None
         super().__init__(relative_accuracy, offset=offset)
         self._multiplier /= self.C
 
     def _cubic_log2_approx(self, value):
+        # type: (float) -> float
         """approximates log2 using a cubic polynomial"""
         mantissa, exponent = math.frexp(value)
         significand = 2 * mantissa - 1
@@ -167,6 +182,7 @@ def _cubic_log2_approx(self, value):
         ) * significand + (exponent - 1)
 
     def _cubic_exp2_approx(self, value):
+        # type: (float) -> float
         """Derived from Cardano's formula"""
 
         exponent = math.floor(value)
@@ -187,7 +203,9 @@ def _cubic_exp2_approx(self, value):
         return math.ldexp(mantissa, exponent + 1)
 
     def _log_gamma(self, value):
+        # type: (float) -> float
         return self._cubic_log2_approx(value) * self._multiplier
 
     def _pow_gamma(self, value):
+        # type: (float) -> float
         return self._cubic_exp2_approx(value / self._multiplier)