superleaf 0.2.0__py3-none-any.whl

superleaf/collections/__init__.py

@@ -0,0 +1,2 @@
+from superleaf.collections.ordered_set import OrderedSet
+from superleaf.collections.summable_dict import SummableDict

superleaf/collections/ordered_set.py

@@ -0,0 +1,79 @@
+import itertools
+from typing import Generic, Iterable, Iterator, Self, TypeVar
+
+T = TypeVar('T')
+
+
+class OrderedSet(Generic[T]):
+    """Similar interface to the native set class, but with item order maintained, and expanded functionality, including
+    addition and summation. Implemented by storing the set items as keys in an internal dict."""
+
+    def __init__(self, items: Iterable[T] = None):
+        self._dict: dict[T, None] = dict(zip(items, itertools.repeat(None))) if items is not None else {}
+
+    @property
+    def _items(self) -> list[T]:
+        return list(self._dict.keys())
+
+    def __iter__(self) -> Iterator[T]:
+        return iter(self._items)
+
+    def copy(self) -> Self:
+        return self.__class__(self._items)
+
+    def union(self, other: Iterable[T]) -> Self:
+        return self.__class__(itertools.chain(self, other))
+
+    def add(self, item: T) -> Self:
+        self._dict[item] = None
+
+    def intersection(self, other: Iterable[T]) -> Self:
+        return self.__class__(filter(lambda x: x in other, self))
+
+    def __add__(self, other: Iterable[T]) -> Self:
+        return self.__class__(self.union(other))
+
+    def __radd__(self, other: Iterable[T]) -> Self:
+        if other == 0:
+            return self
+        else:
+            if not isinstance(other, type(self)):
+                other = type(self)(other)
+            return other + self
+
+    def __iadd__(self, other: Iterable[T]) -> Self:
+        if not isinstance(other, self.__class__):
+            other = self.__class__(other)
+        self._dict.update(other._dict)
+        return self
+
+    def __sub__(self, other: Iterable[T]) -> Self:
+        return self.__class__(filter(lambda x: x not in other, self))
+
+    def __isub__(self, other: Iterable[T]) -> Self:
+        if not isinstance(other, self.__class__):
+            other = self.__class__(other)
+        for item in other:
+            if item in self:
+                self._dict.pop(item)
+        return self
+
+    def __contains__(self, item: T) -> bool:
+        return item in self._dict
+
+    def __eq__(self, other: Self | set[T]) -> Self:
+        if isinstance(other, set):
+            return set(self._items) == other
+        elif isinstance(other, OrderedSet):
+            return self._dict == other._dict
+        else:
+            return False
+
+    def __repr__(self) -> str:
+        return "{" + ", ".join([item.__repr__() for item in self._items]) + "}"
+
+    def __len__(self) -> int:
+        return len(self._dict)
+
+    def __getitem__(self, item: int) -> T:
+        return self._items[item]

superleaf/collections/summable_dict.py

@@ -0,0 +1,71 @@
+from typing import Self
+
+
+class SummableDict(dict):
+    """A dictionary-like object that supports addition and subtraction of values."""
+
+    def __add__(self, other) -> Self:
+        summed = self.copy()
+        if isinstance(other, dict):
+            for k, v in other.items():
+                if k in summed:
+                    summed[k] = summed[k] + v
+                else:
+                    summed[k] = v
+        else:
+            for k, v in self.items():
+                summed[k] = summed[k] + other
+        return summed
+
+    def __iadd__(self, other) -> Self:
+        if isinstance(other, dict):
+            for k, v in other.items():
+                if k in self:
+                    self[k] = self[k] + v
+                else:
+                    self[k] = v
+        else:
+            for k, v in self.items():
+                self[k] = self[k] + other
+        return self
+
+    def __radd__(self, other) -> Self:
+        if other == 0:
+            return self.copy()
+        elif isinstance(other, dict):
+            return SummableDict(other) + self
+        else:
+            summed = self.copy()
+            for k, v in self.items():
+                summed[k] = other + v
+            return summed
+
+    def __neg__(self) -> Self:
+        return SummableDict({k: -v for k, v in self.items()})
+
+    def __sub__(self, other) -> Self:
+        if isinstance(other, dict):
+            return self + -SummableDict(other)
+        else:
+            return self + -other
+
+    def __isub__(self, other) -> Self:
+        if isinstance(other, dict):
+            for k, v in other.items():
+                if k in self:
+                    self[k] = self[k] - v
+                else:
+                    self[k] = -v
+        else:
+            for k, v in self.items():
+                self[k] = self[k] - other
+        return self
+
+    def __rsub__(self, other):
+        if other == 0:
+            return self.copy()
+        else:
+            return other + -self
+
+    def copy(self):
+        return SummableDict(super().copy())

superleaf/dataframe/__init__.py

@@ -0,0 +1,4 @@
+from superleaf.dataframe.column_ops import Col, Values
+from superleaf.dataframe.selection import dfilter, partition, reorder_columns
+from superleaf.dataframe.standardize import standardize_columns
+from superleaf.dataframe.transform import expand_dict_to_cols

superleaf/dataframe/column_ops.py

@@ -0,0 +1,364 @@
+from abc import ABCMeta, abstractmethod
+from typing import Any, Callable, Iterable, Optional, Union
+
+import pandas as pd
+
+
+class ColOp(metaclass=ABCMeta):
+    """Abstract base class for column operations on pandas DataFrames.
+
+    Subclasses implement transformations or evaluations that produce pandas Series or scalar
+    results when applied to DataFrames. Supports chaining and combining using logical and
+    arithmetic operators.
+
+    Operators defined on this class:
+    ``|`` (bitwise or), ``&`` (bitwise and), ``~`` (bitwise not), ``==`` (equal to), ``!=`` (not equal to),
+    ``<`` (less than), ``<=`` (less than or equal to), ``>`` (greater than), ``>=`` (greater than or equal to),
+    ``+`` (addition), ``-`` (subtraction), ``*`` (multiplication), ``/`` (division), ``^`` (power)
+    """
+
+    @abstractmethod
+    def __call__(self, df: pd.DataFrame) -> Union[pd.Series, Any]:
+        """Evaluate the operation on the DataFrame.
+
+        Parameters
+        ----------
+        df : pd.DataFrame
+            Input DataFrame on which to apply the operation.
+
+        Returns
+        -------
+        Union[pd.Series, Any]
+            The resulting pandas Series or scalar value produced by this operation.
+        """
+        pass
+
+    def __or__(self, right: "ColOp") -> "ColOp":
+        return _OrOp(self, right)
+
+    def __and__(self, right: "ColOp") -> "ColOp":
+        return _AndOp(self, right)
+
+    def __invert__(self) -> "ColOp":
+        return _NotOp(self)
+
+    def __eq__(self, value: Any) -> "ColOp":
+        return _EqOp(self, value)
+
+    def __ne__(self, value: Any) -> "ColOp":
+        return _NotOp(self == value)
+
+    def __lt__(self, value: Any) -> "ColOp":
+        return _LtOp(self, value)
+
+    def __le__(self, value: Any) -> "ColOp":
+        return _LeOp(self, value)
+
+    def __gt__(self, value: Any) -> "ColOp":
+        return _GtOp(self, value)
+
+    def __ge__(self, value: Any) -> "ColOp":
+        return _GeOp(self, value)
+
+    def __add__(self, right: "ColOp") -> "ColOp":
+        return _AddOp(self, right)
+
+    def __sub__(self, right: "ColOp") -> "ColOp":
+        return _SubtractOp(self, right)
+
+    def __mul__(self, right: "ColOp") -> "ColOp":
+        return _MultiplyOp(self, right)
+
+    def __truediv__(self, right: "ColOp") -> "ColOp":
+        return _DivideOp(self, right)
+
+    def __pow__(self, right: "ColOp") -> "ColOp":
+        return _PowOp(self, right)
+
+    def apply(self, f: Callable[[pd.Series], pd.Series]) -> "ColOp":
+        """Apply a transformation function to the result of this operation.
+
+        Parameters
+        ----------
+        f : callable
+            A function that takes a pandas Series and returns a transformed Series.
+
+        Returns
+        -------
+        ColOp
+            A new ColOp representing the application of ``f`` to this operation’s output.
+        """
+        return _ColApplyOp(self, f)
+
+    def map(self, f: Callable[[Any], Any]) -> "ColOp":
+        """Map a function over each element of the Series produced by this operation.
+
+        Parameters
+        ----------
+        f : callable
+            A function applied element-wise to each value in the Series.
+
+        Returns
+        -------
+        ColOp
+            A new ColOp representing the mapped operation.
+        """
+        return _ColMapOp(self, f)
+
+    def isin(self, values: Iterable[Any]) -> "ColOp":
+        """Test whether each element of the Series is in the given values.
+
+        Parameters
+        ----------
+        values : iterable
+            A collection of values to test membership against.
+
+        Returns
+        -------
+        ColOp
+            A new ColOp that yields a boolean Series.
+        """
+        if isinstance(values, ColOp):
+            combined_vals = self.to_list() + values.to_list()
+            return combined_vals.map(lambda x: x[0] in x[1])
+        else:
+            return self.apply(lambda s: s.isin(values))
+
+    def contains(self, value: Any) -> "ColOp":
+        """Test whether each element of the Series contains the specified value.
+
+        Parameters
+        ----------
+        value : Any
+            Value to search for within each element.
+
+        Returns
+        -------
+        ColOp
+            A new ColOp that yields a boolean Series.
+        """
+        return self.map(lambda x: value in x)
+
+    def notna(self) -> "ColOp":
+        """Test for non-missing values in the Series.
+
+        Returns
+        -------
+        ColOp
+            A new ColOp yielding a boolean Series where True indicates non-null values.
+        """
+        return self.apply(lambda s: s.notna())
+
+    def isna(self) -> "ColOp":
+        """Test for missing values in the Series.
+
+        Returns
+        -------
+        ColOp
+            A new ColOp yielding a boolean Series where True indicates null values.
+        """
+        return self.apply(lambda s: s.isna())
+
+    def astype(self, type_) -> "ColOp":
+        """Cast the Series to a specified dtype.
+
+        Parameters
+        ----------
+        type_ : type or str
+            The target data type for the Series.
+
+        Returns
+        -------
+        ColOp
+            A new ColOp representing the cast operation.
+        """
+        return self.apply(lambda s: s.astype(type_))
+
+    def to_list(self) -> "ColOp":
+        """Wrap each element in the Series into a single-element list.
+
+        Returns
+        -------
+        ColOp
+            A new ColOp that converts each scalar to a list containing that value.
+        """
+        return self.map(lambda x: [x])
+
+
+class Index(ColOp):
+    """Represent the index of a pandas DataFrame.
+
+    Parameters
+    ----------
+    None
+
+    Examples
+    --------
+    >>> idx = Index()
+    >>> idx(df)
+    DatetimeIndex([...])
+    """
+    def __call__(self, df: pd.DataFrame) -> pd.Index:
+        return df.index
+
+
+class Col(ColOp):
+    """Represent a named column in a DataFrame.
+
+    Parameters
+    ----------
+    name : str, optional
+        Column name to select. If None, selects the entire DataFrame.
+
+    Examples
+    --------
+    >>> col = Col('column_name')
+    >>> col(df)
+    0    ...
+    Name: column_name, dtype: dtype
+    """
+    def __init__(self, name: Optional[str]):
+        self._name = name
+
+    def __call__(self, df: pd.DataFrame) -> pd.Series:
+        if self._name is None:
+            return df.iloc[:]
+        else:
+            return df[self._name]
+
+
+class Values(Col):
+    """Represent the values of a pandas Series.
+
+    Notes
+    -----
+    This raises a TypeError if called on a DataFrame instead of a Series.
+
+    Examples
+    --------
+    >>> values = Values()
+    >>> values(series)
+    array([...])
+    """
+    def __init__(self):
+        super().__init__(None)
+
+    def __call__(self, s: pd.Series) -> pd.Series:
+        if isinstance(s, pd.DataFrame):
+            raise TypeError("Values can only be called on a Series")
+        return s.iloc[:]
+
+
+class _LiteralOp(ColOp):
+    def __init__(self, value: Any) -> None:
+        self._value = value
+
+    def __call__(self, df: pd.DataFrame) -> Any:
+        return self._value
+
+
+class _ComparisonOp(ColOp):
+    def __init__(self, col: ColOp, value: Union[ColOp, Any]) -> None:
+        self._col = col
+        if isinstance(value, ColOp):
+            self._value = value
+        else:
+            self._value = _LiteralOp(value)
+
+
+class _EqOp(_ComparisonOp):
+    def __call__(self, df: pd.DataFrame) -> pd.Series:
+        return self._col(df) == self._value(df)
+
+
+class _LtOp(_ComparisonOp):
+    def __call__(self, df: pd.DataFrame) -> pd.Series:
+        return self._col(df) < self._value(df)
+
+
+class _LeOp(_ComparisonOp):
+    def __call__(self, df: pd.DataFrame) -> pd.Series:
+        return self._col(df) <= self._value(df)
+
+
+class _GtOp(_ComparisonOp):
+    def __call__(self, df: pd.DataFrame) -> pd.Series:
+        return self._col(df) > self._value(df)
+
+
+class _GeOp(_ComparisonOp):
+    def __call__(self, df: pd.DataFrame) -> pd.Series:
+        return self._col(df) >= self._value(df)
+
+
+class _BinaryOp(ColOp):
+    def __init__(self, left: Union[ColOp, Any], right: Union[ColOp, Any]) -> None:
+        if isinstance(left, ColOp):
+            self._left = left
+        else:
+            self._left = _LiteralOp(left)
+        if isinstance(right, ColOp):
+            self._right = right
+        else:
+            self._right = _LiteralOp(right)
+
+
+class _OrOp(_BinaryOp):
+    def __call__(self, df: pd.DataFrame) -> pd.Series:
+        return self._left(df) | self._right(df)
+
+
+class _AndOp(_BinaryOp):
+    def __call__(self, df: pd.DataFrame) -> pd.Series:
+        return self._left(df) & self._right(df)
+
+
+class _AddOp(_BinaryOp):
+    def __call__(self, df: pd.DataFrame) -> pd.Series:
+        return self._left(df) + self._right(df)
+
+
+class _SubtractOp(_BinaryOp):
+    def __call__(self, df: pd.DataFrame) -> pd.Series:
+        return self._left(df) - self._right(df)
+
+
+class _MultiplyOp(_BinaryOp):
+    def __call__(self, df: pd.DataFrame) -> pd.Series:
+        return self._left(df) * self._right(df)
+
+
+class _DivideOp(_BinaryOp):
+    def __call__(self, df: pd.DataFrame) -> pd.Series:
+        return self._left(df) / self._right(df)
+
+
+class _PowOp(_BinaryOp):
+    def __call__(self, df: pd.DataFrame) -> pd.Series:
+        return self._left(df) ** self._right(df)
+
+
+class _NotOp(ColOp):
+    def __init__(self, col: ColOp) -> None:
+        self._col = col
+
+    def __call__(self, df: pd.DataFrame) -> pd.Series:
+        return ~self._col(df)
+
+
+class _ColApplyOp(ColOp):
+    def __init__(self, col: ColOp, f: Callable[[pd.Series], pd.Series]) -> None:
+        self._col = col
+        self._fun = f
+
+    def __call__(self, df: pd.DataFrame) -> pd.Series:
+        return self._fun(self._col(df))
+
+
+class _ColMapOp(ColOp):
+    def __init__(self, col: ColOp, f: Callable[[Any], Any]) -> None:
+        self._col = col
+        self._fun = f
+
+    def __call__(self, df: pd.DataFrame) -> pd.Series:
+        return self._col(df).map(self._fun)

superleaf/dataframe/display.py

@@ -0,0 +1,80 @@
+import pandas as pd
+from IPython.display import display
+
+
+def set_max_columns(max_columns=None):
+    """Set pandas’ display.max_columns option.
+
+    Temporarily controls how many columns pandas will print when formatting DataFrames.
+
+    Parameters
+    ----------
+    max_columns : int or None
+        Maximum number of columns to show. If None, pandas will use its own default (usually 20).
+    """
+    pd.set_option('display.max_columns', max_columns)
+
+
+def set_max_rows(max_rows=None):
+    """Set pandas’ display.max_rows option.
+
+    Temporarily controls how many rows pandas will print when formatting DataFrames.
+
+    Parameters
+    ----------
+    max_rows : int or None
+        Maximum number of rows to show. If None, pandas will use its own default (usually 60).
+    """
+    pd.set_option('display.max_rows', max_rows)
+
+
+class _PandasDisplayCM:
+    def __init__(self, all_columns=False, all_rows=False):
+        self._value_store = {}
+        self.all_columns = all_columns
+        self.all_rows = all_rows
+
+    def __enter__(self):
+        if self.all_columns:
+            self._value_store['max_columns'] = pd.get_option('display.max_columns')
+            set_max_columns()
+        if self.all_rows:
+            self._value_store['max_rows'] = pd.get_option('display.max_rows')
+            set_max_rows()
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if self.all_columns:
+            pd.set_option('display.max_columns', self._value_store['max_columns'])
+        if self.all_rows:
+            pd.set_option('display.max_rows', self._value_store['max_rows'])
+        return False
+
+
+def show_all(df, mode=None, columns=True, rows=True):
+    """Display a DataFrame with all rows and/or columns visible.
+
+    Uses a context manager to temporarily override pandas’ display.max_columns
+    and display.max_rows options, then calls IPython.display.display.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        The DataFrame to render in the notebook.
+    mode : str, optional
+        One of:
+        - 'columns': expand only columns
+        - 'rows': expand only rows
+        - None (default): use the ``columns`` and ``rows`` flags below
+    columns : bool, optional
+        When mode is None, if True (default) all columns are shown.
+    rows : bool, optional
+        When mode is None, if True (default) all rows are shown.
+    """
+    if mode == 'columns':
+        cm = _PandasDisplayCM(all_columns=True)
+    elif mode == 'rows':
+        cm = _PandasDisplayCM(all_rows=True)
+    else:
+        cm = _PandasDisplayCM(all_columns=columns, all_rows=rows)
+    with cm:
+        display(df)