superleaf 0.2.0__tar.gz

superleaf-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Erik Schomburg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

superleaf-0.2.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: superleaf
+Version: 0.2.0
+Summary: A library for intuitive and readable data manipulation, using functional and pipeable syntax.
+Author-email: Erik Schomburg <eschomburg@gmail.com>
+Project-URL: Homepage, https://github.com/eschombu/superleaf
+Project-URL: Issues, https://github.com/eschombu/superleaf/issues
+Requires-Python: >=3.8
+License-File: LICENSE
+Requires-Dist: matplotlib
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: pendulum>=3.0.0
+Requires-Dist: scipy
+Provides-Extra: dev
+Requires-Dist: flake8; extra == "dev"
+Requires-Dist: pydata-sphinx-theme; extra == "dev"
+Requires-Dist: pydoclint; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Provides-Extra: notebook
+Requires-Dist: jupyter; extra == "notebook"
+Provides-Extra: parallel
+Requires-Dist: multiprocess; extra == "parallel"
+Requires-Dist: pyarrow; extra == "parallel"
+Requires-Dist: tqdm; extra == "parallel"
+Dynamic: license-file

superleaf-0.2.0/README.md

@@ -0,0 +1,81 @@
+# `superleaf`
+
+<h3> <em>NOTE:</em> This package is still under development, it needs more documentation, and some components not related
+to its intended core uses may be removed.</h3>
+
+## A library for intuitive and readable data filtering and manipulation, using functional and pipeable syntax.
+
+When trying to select and filter `pandas` dataframes in somewhat complicated ways, the syntax can quickly get
+cumbersome. This library provides utilities for quickly and intuitively specifying ways to select and filter based on
+column and row conditions. It also includes utilities for piping and composing value accessor and manipulation operators
+on more general datatypes.
+
+## Operators
+
+Some of the operators in this library have analogues in the Python standard library `operator` module, but the ones here
+can be more flexibly composed and piped.
+
+For example, let's say you want to take the logarithm of all of the values inside one of the fields of a sequence of data
+containers. You can achieve this with the following code:
+
+```
+import numpy as np
+from superleaf.operators import operator
+from superlead.getters import attr_getter
+
+exp_field_op = attr_getter("field_a") >> operator(np.log)  # "right shift" operator used for piping
+results_iter = map(exp_field_op, data_containers)
+```
+
+This produces an iterator with the same results as the following list comprehension:
+```
+results_list = [np.log(datum.field_a) for datum in data_containers]
+```
+
+## DataFrame column operators and selection/filtering
+
+Row filtering, especially for complicated combinations of conditions, of pandas dataframes can have cumbersome and
+seemingly repetitive syntax. The `dfilter` and `Col` utilities can be used to more succinctly achieve complicated
+filtering and selection of portions of dataframes.
+
+For example, consider the following dataframe:
+```
+import pandas as pd
+
+df = pd.DataFrame({
+    "col1": [          0,         1,          0,       1,      1,         1,      0],
+    "col2": [       -5.1,       2.2,        0.2,     1.7,   -1.1,    np.nan,    0.9],
+    "col3": [ "elephant", "giraffe", "Elephant", "Zebra",  "Emu",    "lion", "lion"],
+})
+```
+
+Let's say we want to select the rows where col1 == 1, col2 is NaN or negative, and col3 begins with the letter 'e':
+```
+sub_df = df[(df["col1"] == 1) & (df["col2"].isna() | (df["col2"] < 0)) & df["col3"].map(lambda s: s.lower().startswith('e'))]
+```
+
+Using `superleaf`, we could do this with the following:
+```
+from superleaf.dataframe.selection import dfilter
+from superleaf.operator import ComparisonFunctions as F, str_op
+
+sub_df = dfilter(df, col1=1, col2=(F.isna | F.lt(0)), col3=(str_op("lower") >> F.startswith("e")))
+```
+
+This would fail if the values in col3 might not be strings. In this case, a fallback value can be set:
+```
+from superleaf.operator import with_fallback
+
+sub_df = dfilter(df, col1=1, col2=(F.isna | F.lt(0)), col3=with_fallback(str_op("lower") >> F.startswith("e"), False))
+```
+
+## Utilities
+
+### Parallelization
+
+
+### Hash strings
+
+
+## Data structures and collections
+

superleaf-0.2.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "superleaf"
+version = "0.2.0"
+authors = [
+    {name = "Erik Schomburg", email = "eschomburg@gmail.com"},
+]
+description = "A library for intuitive and readable data manipulation, using functional and pipeable syntax."
+requires-python = ">=3.8"
+dependencies = [
+    "matplotlib",
+    "numpy",
+    "pandas",
+    "pendulum>=3.0.0",
+    "scipy",
+]
+
+[project.optional-dependencies]
+dev = ["flake8", "pydata-sphinx-theme", "pydoclint", "pytest", "pytest-mock"]
+notebook = ["jupyter"]
+parallel = ["multiprocess", "pyarrow", "tqdm"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[project.urls]
+Homepage = "https://github.com/eschombu/superleaf"
+Issues = "https://github.com/eschombu/superleaf/issues"

superleaf-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

superleaf-0.2.0/src/superleaf/collections/__init__.py

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

superleaf-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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)