pydoclint, pyright

Author: soodoku

.github/workflows/ci.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.12", "3.13", "3.14"]
 
     steps:
     - uses: actions/checkout@v4
@@ -34,7 +34,7 @@ jobs:
       run: uv run ruff format --check .
 
     - name: Run type checking
-      run: uv run mypy fairlex/
+      run: uv run pyright
 
     - name: Run tests
       run: uv run pytest -q --color=yes

.github/workflows/python-publish.yml

@@ -40,7 +40,7 @@ jobs:
       run: uv run ruff format --check .
 
     - name: Run type checking
-      run: uv run mypy fairlex/
+      run: uv run pyright
 
     - name: Run tests
       run: uv run pytest -q --color=yes

README.md

@@ -3,7 +3,7 @@ fairlex: leximin calibration
 
 [![PyPI version](https://img.shields.io/pypi/v/fairlex.svg)](https://pypi.org/project/fairlex/)
 [![PyPI Downloads](https://static.pepy.tech/badge/fairlex)](https://pepy.tech/projects/fairlex)
-[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/fairlex)](https://pypi.org/project/fairlex/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 
@@ -37,8 +37,8 @@ principal calibration strategies are:
 Installation
 ------------
 
-``fairlex`` requires Python 3.8+ and depends on ``numpy`` and
-``scipy``. You can install it via pip once uploaded to PyPI:
+``fairlex`` requires Python 3.12+ and depends on ``numpy>=1.26`` and
+``scipy>=1.11``. You can install it via pip once uploaded to PyPI:
 
 ```bash
 pip install fairlex

fairlex/__init__.py

@@ -33,7 +33,4 @@
 from .metrics import evaluate_solution
 
 # Expose the package version at runtime
-try:  # pragma: no cover - metadata may not be present in editable installs
-    __version__ = version("fairlex")
-except Exception:
-    __version__ = "0.0.0"
+__version__ = version("fairlex")

fairlex/calibration.py

@@ -32,21 +32,14 @@
 
 """
 
-from __future__ import annotations
-
 from dataclasses import dataclass
 
 import numpy as np
+from scipy.optimize import linprog  # type: ignore[import-untyped]
 
 # Constants
 EXPECTED_MATRIX_DIMENSIONS = 2
 
-try:
-    # SciPy is used for linear programming; HiGHS is fast and reliable.
-    from scipy.optimize import linprog  # type: ignore
-except Exception:  # pragma: no cover
-    linprog = None
-
 
 @dataclass
 class CalibrationResult:
@@ -66,6 +59,7 @@ class CalibrationResult:
         Status code from the linear programme (0 indicates success).
     message : str
         Solver termination message for diagnostics.
+
     """
 
     w: np.ndarray
@@ -76,7 +70,7 @@ class CalibrationResult:
 
 
 def _validate_inputs(
-    A: np.ndarray, b: np.ndarray, w0: np.ndarray
+    A: np.ndarray, b: np.ndarray, w0: np.ndarray,
 ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
     """Validate and coerce input arrays to ensure they have compatible shapes.
 
@@ -98,17 +92,21 @@ def _validate_inputs(
     ------
     ValueError
         If shapes are incompatible.
+
     """
     A = np.asarray(A, dtype=float)
     b = np.asarray(b, dtype=float)
     w0 = np.asarray(w0, dtype=float)
     if A.ndim != EXPECTED_MATRIX_DIMENSIONS:
-        raise ValueError(f"A must be two-dimensional, got shape {A.shape}")
+        msg = f"A must be two-dimensional, got shape {A.shape}"
+        raise ValueError(msg)
     m, n = A.shape
     if b.shape != (m,):
-        raise ValueError(f"b must be of shape {(m,)}, got {b.shape}")
+        msg = f"b must be of shape {(m,)}, got {b.shape}"
+        raise ValueError(msg)
     if w0.shape != (n,):
-        raise ValueError(f"w0 must be of shape {(n,)}, got {w0.shape}")
+        msg = f"w0 must be of shape {(n,)}, got {w0.shape}"
+        raise ValueError(msg)
     return A, b, w0
 
 
@@ -138,11 +136,8 @@ def _solve_lp(
     -------
     res : OptimizeResult
         Result from the solver.
+
     """
-    if linprog is None:
-        raise ImportError(
-            "SciPy is required to solve the linear programmes. Install scipy>=1.6 to use this function."
-        )
     res = linprog(
         c=c,
         A_ub=A_ub,
@@ -197,6 +192,7 @@ def leximin_residual(
     If the problem is infeasible (e.g., because the bounds preclude any
     solution), the returned status will be nonzero and the weights may not be
     meaningful. Check ``status`` and ``message`` on the result.
+
     """
     A, b, w0 = _validate_inputs(A, b, w0)
     m, n = A.shape
@@ -231,7 +227,7 @@ def leximin_residual(
     w = x[:n]
     epsilon = x[-1]
     return CalibrationResult(
-        w=w, epsilon=epsilon, t=None, status=res.status, message=res.message
+        w=w, epsilon=epsilon, t=None, status=res.status, message=res.message,
     )
 
 
@@ -255,6 +251,7 @@ def _setup_weight_fair_constraints(
         Inequality constraint right hand side.
     bounds : list
         Variable bounds.
+
     """
     m, n = A.shape
 
@@ -350,6 +347,7 @@ def leximin_weight_fair(
         :class:`CalibrationResult` containing the final weights and both the
         residual and weight fairness optima. If ``return_stages`` is
         ``True``, a tuple ``(stage1_result, stage2_result)``.
+
     """
     stage1 = leximin_residual(A, b, w0, min_ratio=min_ratio, max_ratio=max_ratio)
     # If the residual stage failed, propagate the failure
@@ -369,7 +367,7 @@ def leximin_weight_fair(
 
     # Set up constraints using helper function
     A_ub, b_ub, bounds = _setup_weight_fair_constraints(
-        A, b, w0, stage1.epsilon, min_ratio=min_ratio, max_ratio=max_ratio, slack=slack
+        A, b, w0, stage1.epsilon, min_ratio=min_ratio, max_ratio=max_ratio, slack=slack,
     )
 
     res = _solve_lp(c, A_ub, b_ub, bounds)
@@ -389,7 +387,7 @@ def leximin_weight_fair(
     w = x[:n]
     t_opt = x[-1]
     stage2 = CalibrationResult(
-        w=w, epsilon=stage1.epsilon, t=t_opt, status=res.status, message=res.message
+        w=w, epsilon=stage1.epsilon, t=t_opt, status=res.status, message=res.message,
     )
     if return_stages:
         return stage1, stage2

fairlex/metrics.py

@@ -23,8 +23,6 @@
 
 """
 
-from __future__ import annotations
-
 import numpy as np
 
 __all__ = [
@@ -52,6 +50,7 @@ def effective_sample_size(weights: np.ndarray) -> float:
     -------
     float
         Effective sample size. Returns ``np.nan`` if the denominator is zero.
+
     """
     w = np.asarray(weights, dtype=float)
     numer = np.sum(w)
@@ -78,6 +77,7 @@ def design_effect(weights: np.ndarray) -> float:
     float
         Design effect. Returns ``np.nan`` if the effective sample size is
         undefined.
+
     """
     w = np.asarray(weights, dtype=float)
     ess = effective_sample_size(w)
@@ -87,9 +87,13 @@ def design_effect(weights: np.ndarray) -> float:
 
 
 def _compute_residual_metrics(
-    A: np.ndarray, b: np.ndarray, w: np.ndarray
+    A: np.ndarray, b: np.ndarray, w: np.ndarray,
 ) -> dict[str, float]:
-    """Compute residual-based metrics."""
+    """Compute residual-based metrics.
+
+    Returns:
+        Dictionary containing residual metrics.
+    """
     resid = A @ w - b
     abs_resid = np.abs(resid)
     return {
@@ -101,9 +105,13 @@ def _compute_residual_metrics(
 
 
 def _compute_weight_metrics(
-    w: np.ndarray, quantiles: tuple[float, ...]
+    w: np.ndarray, quantiles: tuple[float, ...],
 ) -> dict[str, float]:
-    """Compute weight distribution metrics."""
+    """Compute weight distribution metrics.
+
+    Returns:
+        Dictionary containing weight distribution metrics.
+    """
     # Calculate all quantiles plus min/max
     q_vals = np.quantile(w, (*quantiles, 0.0, 1.0))
     q_map = dict(zip((*quantiles, 0.0, 1.0), q_vals, strict=False))
@@ -116,7 +124,7 @@ def _compute_weight_metrics(
         "weight_min": float(q_map[0.0]),
         "weight_p99": float(q_map.get(0.99, q_map[sorted_q[0]])),
         "weight_p95": float(
-            q_map.get(0.95, q_map[sorted_q[min(1, len(sorted_q) - 1)]])
+            q_map.get(0.95, q_map[sorted_q[min(1, len(sorted_q) - 1)]]),
         ),
         "weight_median": float(q_map.get(0.5, np.median(w))),
         "ESS": float(effective_sample_size(w)),
@@ -125,9 +133,13 @@ def _compute_weight_metrics(
 
 
 def _compute_relative_deviations(
-    w: np.ndarray, base_weights: np.ndarray
+    w: np.ndarray, base_weights: np.ndarray,
 ) -> dict[str, float]:
-    """Compute relative deviation metrics."""
+    """Compute relative deviation metrics.
+
+    Returns:
+        Dictionary containing relative deviation metrics.
+    """
     bw = np.asarray(base_weights, dtype=float)
     rel_dev = np.abs(w - bw) / np.where(bw == 0, 1.0, np.abs(bw))
     return {
@@ -169,6 +181,7 @@ def evaluate_solution(
     dict
         A dictionary containing residual and weight diagnostics. See module
         docstring for the key descriptions.
+
     """
     w = np.asarray(w, dtype=float)
     A = np.asarray(A, dtype=float)

fairlex/py.typed

@@ -4,27 +4,27 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fairlex"
-version = "0.1.0"
+version = "0.3.0"
 description = "Leximin calibration for survey weights"
 authors = [
   { name = "Gaurav Sood", email = "contact@gsood.com" },
 ]
 license = { text = "MIT" }
 readme = "README.md"
-requires-python = ">=3.11"
+requires-python = ">=3.12"
 dependencies = [
-  "numpy>=1.21",
-  "scipy>=1.6",
+  "numpy>=1.26.0",
+  "scipy>=1.11.0",
 ]
 classifiers = [
   "Development Status :: 3 - Alpha",
   "License :: OSI Approved :: MIT License",
   "Programming Language :: Python",
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3 :: Only",
-  "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
   "Intended Audience :: Science/Research",
   "Topic :: Scientific/Engineering :: Mathematics",
   "Topic :: Scientific/Engineering :: Information Analysis",
@@ -35,8 +35,9 @@ dev = [
   "pytest>=7.0",
   "pytest-cov>=4.0",
   "ruff>=0.7.0",
-  "mypy>=1.0",
-  "pre-commit>=3.0"
+  "pre-commit>=3.0",
+  "pydoclint>=0.3.0",
+  "pyright>=1.1.0"
 ]
 test = [
   "pytest>=7.0",
@@ -58,7 +59,7 @@ packages = ["fairlex"]
 
 [tool.ruff]
 line-length = 88
-target-version = "py311"
+target-version = "py312"
 preview = true
 exclude = [
   ".git",
@@ -101,16 +102,48 @@ ignore = [
 [tool.ruff.lint.isort]
 known-first-party = ["fairlex"]
 
-[tool.mypy]
-python_version = "3.11"
-warn_return_any = true
-warn_unused_configs = true
-check_untyped_defs = true
-strict = true
-show_error_codes = true
-pretty = true
-
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 python_files = ["test_*.py"]
 addopts = "--cov=fairlex --cov-report=html --cov-report=term-missing"
+
+[tool.pydoclint]
+style = "google"
+exclude = [
+  "tests/*",
+  "docs/*",
+  "examples/*",
+  "build/*",
+  "dist/*",
+  "__pycache__/*"
+]
+check-return-types = true
+check-yield-types = true
+arg-type-hints-in-docstring = true
+arg-type-hints-in-signature = true
+allow-init-docstring = true
+
+[tool.pyright]
+include = ["fairlex"]
+exclude = [
+  "tests",
+  "docs", 
+  "examples",
+  "build",
+  "dist",
+  "__pycache__",
+  ".venv"
+]
+pythonVersion = "3.12"
+typeCheckingMode = "basic"
+reportMissingImports = true
+reportMissingTypeStubs = false
+reportUnusedImport = true
+reportUnusedClass = true
+reportUnusedFunction = true
+reportDuplicateImport = true
+reportConstantRedefinition = false
+reportUnknownParameterType = false
+reportUnknownVariableType = false
+reportUnknownMemberType = false
+reportUnknownArgumentType = false