refactor(stupidb): reorganize the codebase

BREAKING CHANGE: Modules are named differently

mypy.ini

@@ -1,5 +1,5 @@
 [mypy]
-exclude = (stupidb/tests)|(docs/conf.py)
+exclude = docs/conf\.py
 ignore_missing_imports = true
 # untyped things
 disallow_untyped_calls = true

pre-commit.nix

@@ -50,6 +50,12 @@ in
         entry = "pyupgrade --py37-plus";
         types_or = [ "python" ];
       };
+
+      mypy = {
+        enable = false;
+        entry = "mypy";
+        types_or = [ "python" ];
+      };
     };
   };
 }

stupidb/aggregation.py

@@ -23,13 +23,13 @@
 )
 
 from .aggregator import Aggregate, Aggregator
-from .associative import BinaryAssociativeAggregate, UnaryAssociativeAggregate
-from .navigation import (
+from .functions.associative import BinaryAssociativeAggregate, UnaryAssociativeAggregate
+from .functions.navigation import (
     BinaryNavigationAggregate,
     TernaryNavigationAggregate,
     UnaryNavigationAggregate,
 )
-from .ranking import RankingAggregate
+from .functions.ranking import RankingAggregate
 from .row import AbstractRow
 from .typehints import Following, OrderBy, OrderingKey, PartitionBy, Preceding, T
 

stupidb/aggregator.py

@@ -3,15 +3,15 @@
 from __future__ import annotations
 
 import abc
-from typing import Callable, ClassVar, Generic, Sequence, TypeVar
+from typing import Generic, Sequence, TypeVar
 
 from .row import AbstractRow
 from .typehints import Getter, Output, Result, T
 
-AggregateClass = TypeVar("AggregateClass", covariant=True)
+AggClass = TypeVar("AggClass", covariant=True)
 
 
-class Aggregator(Generic[AggregateClass, Result], abc.ABC):
+class Aggregator(Generic[AggClass, Result], abc.ABC):
     """Interface for aggregators.
 
     Aggregators must implement the :meth:`~stupidb.aggregator.Aggregator.query`
@@ -21,13 +21,13 @@ class Aggregator(Generic[AggregateClass, Result], abc.ABC):
 
     See Also
     --------
-    stupidb.associative.SegmentTree
-    stupidb.navigation.NavigationAggregator
+    stupidb.associative.segmenttree.SegmentTree
+    stupidb.functions.navigation.core.NavigationAggregator
 
     """
 
     @abc.abstractmethod
-    def __init__(self, arguments: Sequence[T], cls: AggregateClass) -> None:
+    def __init__(self, arguments: Sequence[T], cls: AggClass) -> None:
         """Initialize an aggregator from `arguments` and `cls`."""
 
     @abc.abstractmethod
@@ -39,7 +39,6 @@ class Aggregate(Generic[Output], abc.ABC):
     """An aggregate or window function."""
 
     __slots__ = ()
-    aggregator_class: ClassVar[Callable[..., Aggregator]]
 
     @classmethod
     def prepare(
@@ -52,4 +51,11 @@ def prepare(
         arguments = [
             tuple(getter(peer) for getter in getters) for peer in possible_peers
         ]
-        return cls.aggregator_class(arguments, cls)
+        return cls.aggregator_class(arguments)
+
+    @classmethod
+    @abc.abstractmethod
+    def aggregator_class(
+        cls, inputs: Sequence[tuple[T | None, ...]]
+    ) -> Aggregator[Aggregate[Output], Output]:  # pragma: no cover
+        ...

stupidb/api.py

@@ -15,6 +15,7 @@
 from __future__ import annotations
 
 import inspect
+import operator
 from typing import Any, Callable, Iterable, Mapping
 
 import tabulate
@@ -28,20 +29,6 @@
     Nulls,
     WindowAggregateSpecification,
 )
-from .associative import (
-    Count,
-    Max,
-    Mean,
-    Min,
-    PopulationCovariance,
-    PopulationStandardDeviation,
-    PopulationVariance,
-    SampleCovariance,
-    SampleStandardDeviation,
-    SampleVariance,
-    Sum,
-    Total,
-)
 from .core import (
     Aggregation,
     CrossJoin,
@@ -68,13 +55,39 @@
     Union,
     UnionAll,
 )
-from .navigation import First, Lag, Last, Lead, Nth
+from .functions.associative import (
+    Count,
+    Max,
+    Mean,
+    Min,
+    PopulationCovariance,
+    PopulationStandardDeviation,
+    PopulationVariance,
+    SampleCovariance,
+    SampleStandardDeviation,
+    SampleVariance,
+    Sum,
+    Total,
+)
+from .functions.navigation import First, Lag, Last, Lead, Nth
+from .functions.ranking import DenseRank, Rank, RowNumber
 from .protocols import Comparable
-from .ranking import DenseRank, Rank, RowNumber
 from .row import AbstractRow
 from .typehints import R1, R2, OrderBy, R, T
 
 
+@public  # type: ignore[misc]
+def const(x: T | None) -> Callable[[AbstractRow], T | None]:
+    """Return a function that returns `x` regardless of input."""
+    return lambda _: x
+
+
+@public  # type: ignore[misc]
+def get(name: str) -> Callable[[AbstractRow], T | None]:
+    """Return a function that gets the `name` field from a row."""
+    return operator.itemgetter(name)
+
+
 @private  # type: ignore[misc]
 class shiftable(curry):
     """Shiftable curry."""
@@ -705,7 +718,7 @@ def count(x: Callable[[AbstractRow], T | None]) -> AggregateSpecification:
 
 
 @public  # type: ignore[misc]
-def sum(x: Callable[[AbstractRow], R]) -> AggregateSpecification:
+def sum(x: Callable[[AbstractRow], R | None]) -> AggregateSpecification:
     """Compute the sum of `x`, with an empty column summing to NULL.
 
     Parameters
@@ -718,7 +731,7 @@ def sum(x: Callable[[AbstractRow], R]) -> AggregateSpecification:
 
 
 @public  # type: ignore[misc]
-def total(x: Callable[[AbstractRow], R]) -> AggregateSpecification:
+def total(x: Callable[[AbstractRow], R | None]) -> AggregateSpecification:
     """Compute the sum of `x`, with an empty column summing to zero.
 
     Parameters
@@ -795,8 +808,8 @@ def dense_rank() -> AggregateSpecification:
 @public  # type: ignore[misc]
 def lead(
     x: Callable[[AbstractRow], T | None],
-    n: Callable[[AbstractRow], int | None] = (lambda row: 1),
-    default: Callable[[AbstractRow], T | None] = (lambda row: None),
+    n: Callable[[AbstractRow], int | None] = const(1),
+    default: Callable[[AbstractRow], T | None] = const(None),
 ) -> AggregateSpecification:
     """Lead a column `x` by `n` rows, using `default` for NULL values.
 
@@ -820,8 +833,8 @@ def lead(
 @public  # type: ignore[misc]
 def lag(
     x: Callable[[AbstractRow], T | None],
-    n: Callable[[AbstractRow], int | None] = (lambda row: 1),
-    default: Callable[[AbstractRow], T | None] = (lambda row: None),
+    n: Callable[[AbstractRow], int | None] = const(1),
+    default: Callable[[AbstractRow], T | None] = const(None),
 ) -> AggregateSpecification:
     """Lag a column `x` by `n` rows, using `default` for NULL values.
 
@@ -843,7 +856,7 @@ def lag(
 
 
 @public  # type: ignore[misc]
-def mean(x: Callable[[AbstractRow], R]) -> AggregateSpecification:
+def mean(x: Callable[[AbstractRow], R | None]) -> AggregateSpecification:
     """Compute the average of a column.
 
     Parameters
@@ -883,7 +896,7 @@ def max(x: Callable[[AbstractRow], Comparable | None]) -> AggregateSpecification
 
 @public  # type: ignore[misc]
 def cov_samp(
-    x: Callable[[AbstractRow], R1], y: Callable[[AbstractRow], R2]
+    x: Callable[[AbstractRow], R1 | None], y: Callable[[AbstractRow], R2 | None]
 ) -> AggregateSpecification:
     """Compute the sample covariance of two columns.
 
@@ -899,7 +912,7 @@ def cov_samp(
 
 
 @public  # type: ignore[misc]
-def var_samp(x: Callable[[AbstractRow], R]) -> AggregateSpecification:
+def var_samp(x: Callable[[AbstractRow], R | None]) -> AggregateSpecification:
     """Compute the sample variance of a column.
 
     Parameters
@@ -912,7 +925,7 @@ def var_samp(x: Callable[[AbstractRow], R]) -> AggregateSpecification:
 
 
 @public  # type: ignore[misc]
-def stdev_samp(x: Callable[[AbstractRow], R]) -> AggregateSpecification:
+def stdev_samp(x: Callable[[AbstractRow], R | None]) -> AggregateSpecification:
     """Compute the sample standard deviation of a column.
 
     Parameters
@@ -926,7 +939,7 @@ def stdev_samp(x: Callable[[AbstractRow], R]) -> AggregateSpecification:
 
 @public  # type: ignore[misc]
 def cov_pop(
-    x: Callable[[AbstractRow], R1], y: Callable[[AbstractRow], R2]
+    x: Callable[[AbstractRow], R1 | None], y: Callable[[AbstractRow], R2 | None]
 ) -> AggregateSpecification:
     """Compute the population covariance of two columns.
 
@@ -955,7 +968,7 @@ def var_pop(x: Callable[[AbstractRow], R]) -> AggregateSpecification:
 
 
 @public  # type: ignore[misc]
-def stdev_pop(x: Callable[[AbstractRow], R]) -> AggregateSpecification:
+def stdev_pop(x: Callable[[AbstractRow], R | None]) -> AggregateSpecification:
     """Compute the population standard deviation of a column.
 
     Parameters