chore(doc): add some documentation and redispose code

aequitas/__init__.py

@@ -1,30 +1,25 @@
 import logging
-import types
-import typing
-import numpy
 
 
-logging.basicConfig(level=logging.DEBUG)
-logger = logging.getLogger('aequitas')
-
-Scalar = typing.Union[int, float, bool, complex, str, numpy.generic]
-
+# keep this line at the top of this file
+__all__ = ["logger", "isinstance"]
 
-EPSILON: float = 1e-9
 
-
-def is_zero(x: Scalar) -> bool:
-    return abs(x) < EPSILON
+logging.basicConfig(level=logging.DEBUG)
+logger = logging.getLogger('aequitas')
+"""General logger to be used in all `aequitas*` modules"""
 
 
 __py_isinstance = isinstance
 
 
 def isinstance(obj, cls):
+    """A version of `isinstance` that takes type unions into account"""
+
     if hasattr(cls, '__args__') and __py_isinstance(cls.__args__, tuple):
         return any(__py_isinstance(obj, t) for t in cls.__args__)
     return __py_isinstance(obj, cls)
 
 
-# let this be the last line of this file
+# keep this line at the bottom of this file
 logger.debug("Module %s correctly loaded", __name__)

aequitas/core/__init__.py

@@ -1,4 +1,32 @@
 import aequitas
+import typing
+import numpy
 
-# let this be the last line of this file
+
+# keep this line at the top of this file
+__all__ = ['Scalar', 'DEFAULT_EPSILON', 'is_zero']
+
+
+Scalar = typing.Union[int, float, bool, complex, str, numpy.generic]
+"""General type for scalars (numbers, strings, or NumPy scalars)
+
+Also see: https://numpy.org/doc/stable/reference/arrays.scalars.html
+"""
+
+
+DEFAULT_EPSILON: float = 1e-9
+"""Default threshold for floating-point comparisons"""
+
+
+def is_zero(x: Scalar, epsilon: float = DEFAULT_EPSILON) -> bool:
+    """Checks whether `x` is zero, up to a given threshold
+
+    :param x: the scalar to check
+    :param epsilon: the threshold for the comparison (defaults to `DEFAULT_EPSILON`)
+    """
+
+    return abs(x) < epsilon
+
+
+# keep this line at the bottom of this file
 aequitas.logger.debug("Module %s correctly loaded", __name__)

aequitas/core/metrics.py

@@ -1,8 +1,8 @@
 import aequitas
+from aequitas.core import *
 import numpy as np
 import typing
 
-Scalar = aequitas.Scalar
 Probability = float
 Condition = typing.Callable[[np.array], np.array]
 ConditionOrScalar = typing.Union[Condition, Scalar]
@@ -18,7 +18,7 @@ def check_condition(vector: np.array) -> Condition:
 
 
 def __ensure_finite_ratio(x: Scalar, y: Scalar) -> float:
-    if any(aequitas.is_zero(z) for z in (x, y)):
+    if any(is_zero(z) for z in (x, y)):
         return 0.0
     return min(x / y, y / x)
 

requirements.txt

@@ -1,2 +1,2 @@
 scikit-learn==1.3.0
-numpy ==1.25.2
+numpy==1.25.2