polars-list-math 0.1.1__tar.gz

polars_list_math-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 polars-list-math contributors
+
+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.

polars_list_math-0.1.1/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: polars-list-math
+Version: 0.1.1
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: polars>=1.39.3
+License-File: LICENSE
+Summary: List-oriented math and expression helpers for Polars.
+Keywords: polars,list,dataframe,rust,pyo3
+Home-Page: https://github.com/rufrozen/polars-list-math
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Project-URL: Documentation, https://github.com/rufrozen/polars-list-math/tree/main/docs
+Project-URL: Homepage, https://github.com/rufrozen/polars-list-math
+Project-URL: Issues, https://github.com/rufrozen/polars-list-math/issues
+Project-URL: Repository, https://github.com/rufrozen/polars-list-math
+
+# polars-list-math
+
+`polars-list-math` is a Python/Rust package with list-oriented expression
+helpers for Polars.
+
+Import the package once to register extra methods on `Expr.list`:
+
+```python
+import polars as pl
+import polars_list_math  # noqa: F401
+```
+
+## Install
+
+```bash
+pip install polars-list-math
+# or
+uv add polars-list-math
+```
+
+Requires Python 3.12+ and `polars>=1.39.3`.
+
+## Methods
+
+| Method | Result | Docs |
+| --- | --- | --- |
+| `Expr.list.zip(...)` | Zip lists into `list[struct]` | [Polars proposal](https://github.com/pola-rs/polars/issues/22719) |
+| `Expr.list.combinations(...)` | Pair each item with itself and later items in the same list | [Combinations](https://github.com/rufrozen/polars-list-math/blob/main/docs/combinations.md) |
+| `Expr.list.combinations_to(...)` | Pair each item with each item from another list | [Combinations](https://github.com/rufrozen/polars-list-math/blob/main/docs/combinations.md) |
+| `Expr.list.similarity(...)` | Weighted similarity between two lists | [Similarity](https://github.com/rufrozen/polars-list-math/blob/main/docs/similarity.md) |
+| `Expr.list.mean_similarity(...)` | Mean similarity inside a nested-list row | [Similarity](https://github.com/rufrozen/polars-list-math/blob/main/docs/similarity.md) |
+| `Expr.list.mean_similarity_to(...)` | Mean similarity to reference nested lists | [Similarity](https://github.com/rufrozen/polars-list-math/blob/main/docs/similarity.md) |
+
+The Python helper `py_list_similarity(...)` computes the same weighted
+similarity for plain Python sequences.
+
+If a future Polars release ships native methods with the same names, this
+package leaves the native implementation untouched.
+
+## Quick Examples
+
+```python
+df = pl.DataFrame(
+    {
+        "a": [[1, 2, 3]],
+        "b": [[2, 1, 3]],
+        "groups": [[[1, 2, 3], [1, 2, 3], [4, 5, 6]]],
+    }
+)
+
+df.with_columns(
+    pl.col("a").list.similarity("b").alias("similarity"),
+    pl.col("groups").list.mean_similarity().alias("mean_similarity"),
+    pl.col("a").list.combinations().alias("pairs"),
+    pl.col("a").list.zip("b", fields=["a", "b"]).alias("zipped"),
+)
+```
+
+## Development
+
+```bash
+make install
+make develop
+make test
+```
+
+Build and check the package locally:
+
+```bash
+make check-dist
+```
+
+Release steps are in
+[docs/publishing.md](https://github.com/rufrozen/polars-list-math/blob/main/docs/publishing.md).
+

polars_list_math-0.1.1/README.md

@@ -0,0 +1,74 @@
+# polars-list-math
+
+`polars-list-math` is a Python/Rust package with list-oriented expression
+helpers for Polars.
+
+Import the package once to register extra methods on `Expr.list`:
+
+```python
+import polars as pl
+import polars_list_math  # noqa: F401
+```
+
+## Install
+
+```bash
+pip install polars-list-math
+# or
+uv add polars-list-math
+```
+
+Requires Python 3.12+ and `polars>=1.39.3`.
+
+## Methods
+
+| Method | Result | Docs |
+| --- | --- | --- |
+| `Expr.list.zip(...)` | Zip lists into `list[struct]` | [Polars proposal](https://github.com/pola-rs/polars/issues/22719) |
+| `Expr.list.combinations(...)` | Pair each item with itself and later items in the same list | [Combinations](https://github.com/rufrozen/polars-list-math/blob/main/docs/combinations.md) |
+| `Expr.list.combinations_to(...)` | Pair each item with each item from another list | [Combinations](https://github.com/rufrozen/polars-list-math/blob/main/docs/combinations.md) |
+| `Expr.list.similarity(...)` | Weighted similarity between two lists | [Similarity](https://github.com/rufrozen/polars-list-math/blob/main/docs/similarity.md) |
+| `Expr.list.mean_similarity(...)` | Mean similarity inside a nested-list row | [Similarity](https://github.com/rufrozen/polars-list-math/blob/main/docs/similarity.md) |
+| `Expr.list.mean_similarity_to(...)` | Mean similarity to reference nested lists | [Similarity](https://github.com/rufrozen/polars-list-math/blob/main/docs/similarity.md) |
+
+The Python helper `py_list_similarity(...)` computes the same weighted
+similarity for plain Python sequences.
+
+If a future Polars release ships native methods with the same names, this
+package leaves the native implementation untouched.
+
+## Quick Examples
+
+```python
+df = pl.DataFrame(
+    {
+        "a": [[1, 2, 3]],
+        "b": [[2, 1, 3]],
+        "groups": [[[1, 2, 3], [1, 2, 3], [4, 5, 6]]],
+    }
+)
+
+df.with_columns(
+    pl.col("a").list.similarity("b").alias("similarity"),
+    pl.col("groups").list.mean_similarity().alias("mean_similarity"),
+    pl.col("a").list.combinations().alias("pairs"),
+    pl.col("a").list.zip("b", fields=["a", "b"]).alias("zipped"),
+)
+```
+
+## Development
+
+```bash
+make install
+make develop
+make test
+```
+
+Build and check the package locally:
+
+```bash
+make check-dist
+```
+
+Release steps are in
+[docs/publishing.md](https://github.com/rufrozen/polars-list-math/blob/main/docs/publishing.md).

polars_list_math-0.1.1/polars_list_math/__init__.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from ._list_combinations import install as _install_list_combinations
+from ._list_mean_similarity import install as _install_list_mean_similarity
+from ._list_similarity import (
+    install as _install_list_similarity,
+)
+from ._list_similarity import (
+    py_list_similarity,
+)
+from ._list_zip import install as _install_list_zip
+
+__all__ = [
+    "install",
+    "py_list_similarity",
+]
+
+
+def install(*, overwrite: bool = False) -> None:
+    _install_list_combinations(overwrite=overwrite)
+    _install_list_zip(overwrite=overwrite)
+    _install_list_similarity(overwrite=overwrite)
+    _install_list_mean_similarity(overwrite=overwrite)
+
+
+install()

polars_list_math-0.1.1/polars_list_math/_list_combinations.py

@@ -0,0 +1,300 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import polars as pl
+from polars._utils.wrap import wrap_expr
+from polars.plugins import register_plugin_function
+
+IntoExpr = Any
+
+_INPUT_PREFIX = "__polars_list_math_list_combinations_input_"
+_LIB = Path(__file__).parent
+_NATIVE_EXTENSIONS = {".so", ".pyd", ".dll", ".dylib"}
+_DEFAULT_LEFT_INDEX = "left_index"
+_DEFAULT_RIGHT_INDEX = "right_index"
+
+
+@dataclass(frozen=True)
+class _CombinationFields:
+    include_index: bool
+    left_index: str
+    right_index: str
+    left_value: str
+    right_value: str
+
+
+def list_combinations(
+    expr: IntoExpr,
+    *,
+    left_value: str = "left_value",
+    right_value: str = "right_value",
+    with_index: bool = False,
+    left_index: str | None = None,
+    right_index: str | None = None,
+    skip_null: bool = False,
+) -> pl.Expr:
+    """Build a list expression with all ``i <= j`` pairs from each input list."""
+    fields = _normalize_fields(left_index, right_index, left_value, right_value, with_index)
+    _validate_skip_null(skip_null)
+    if _native_library_available():
+        return register_plugin_function(
+            plugin_path=_LIB,
+            function_name="list_combinations",
+            args=[expr],
+            kwargs=_kwargs(fields, with_index, skip_null),
+            is_elementwise=True,
+            use_abs_path=True,
+        )
+
+    parsed_expr = _parse_into_expr(expr)
+
+    return parsed_expr.map_elements(
+        lambda value: _combinations_row(value, fields, skip_null),
+        return_dtype=None,
+        skip_nulls=False,
+    )
+
+
+def list_combinations_to(
+    expr: IntoExpr,
+    target: IntoExpr,
+    *,
+    left_value: str = "left_value",
+    right_value: str = "right_value",
+    with_index: bool = False,
+    left_index: str | None = None,
+    right_index: str | None = None,
+    skip_null: bool = False,
+) -> pl.Expr:
+    """Build a list expression with all pairs from the input list to a target list."""
+    fields = _normalize_fields(left_index, right_index, left_value, right_value, with_index)
+    _validate_skip_null(skip_null)
+    if _native_library_available():
+        return register_plugin_function(
+            plugin_path=_LIB,
+            function_name="list_combinations_to",
+            args=[expr, target],
+            kwargs=_kwargs(fields, with_index, skip_null),
+            is_elementwise=True,
+            use_abs_path=True,
+        )
+
+    parsed_exprs = [_parse_into_expr(expr), _parse_into_expr(target)]
+    aliases = [f"{_INPUT_PREFIX}{index}" for index in range(2)]
+    row_expr = pl.struct(
+        parsed.alias(alias) for parsed, alias in zip(parsed_exprs, aliases, strict=True)
+    )
+
+    def combinations_to_row(row: Any) -> list[dict[str, Any]] | None:
+        left, right = _row_values(row, aliases)
+        return _combinations_to_row(left, right, fields, skip_null)
+
+    return row_expr.map_elements(
+        combinations_to_row,
+        return_dtype=None,
+        skip_nulls=False,
+    )
+
+
+def install(*, overwrite: bool = False) -> None:
+    """Register the Polars list namespace helpers."""
+    list_namespace = type(pl.col("__polars_list_math_list_combinations_probe__").list)
+
+    if overwrite or not hasattr(list_namespace, "combinations"):
+        list_namespace.combinations = _expr_list_combinations  # type: ignore
+    if overwrite or not hasattr(list_namespace, "combinations_to"):
+        list_namespace.combinations_to = _expr_list_combinations_to  # type: ignore
+
+
+def _expr_list_combinations(
+    self: Any,
+    *,
+    left_value: str = "left_value",
+    right_value: str = "right_value",
+    with_index: bool = False,
+    left_index: str | None = None,
+    right_index: str | None = None,
+    skip_null: bool = False,
+) -> pl.Expr:
+    base_expr = wrap_expr(self._pyexpr)
+    return list_combinations(
+        base_expr,
+        left_value=left_value,
+        right_value=right_value,
+        with_index=with_index,
+        left_index=left_index,
+        right_index=right_index,
+        skip_null=skip_null,
+    )
+
+
+def _expr_list_combinations_to(
+    self: Any,
+    target: IntoExpr,
+    *,
+    left_value: str = "left_value",
+    right_value: str = "right_value",
+    with_index: bool = False,
+    left_index: str | None = None,
+    right_index: str | None = None,
+    skip_null: bool = False,
+) -> pl.Expr:
+    base_expr = wrap_expr(self._pyexpr)
+    return list_combinations_to(
+        base_expr,
+        target,
+        left_value=left_value,
+        right_value=right_value,
+        with_index=with_index,
+        left_index=left_index,
+        right_index=right_index,
+        skip_null=skip_null,
+    )
+
+
+def _combinations_row(
+    value: Any,
+    fields: _CombinationFields,
+    skip_null: bool,
+) -> list[dict[str, Any]] | None:
+    values = _list_or_none(value, "list.combinations")
+    if values is None:
+        return None
+
+    out: list[dict[str, Any]] = []
+    for left_index in range(len(values)):
+        for right_index in range(left_index, len(values)):
+            left_value = values[left_index]
+            right_value = values[right_index]
+            if skip_null and (left_value is None or right_value is None):
+                continue
+            out.append(_pair_record(fields, left_index, right_index, left_value, right_value))
+    return out
+
+
+def _combinations_to_row(
+    left: Any,
+    right: Any,
+    fields: _CombinationFields,
+    skip_null: bool,
+) -> list[dict[str, Any]] | None:
+    left_values = _list_or_none(left, "list.combinations_to")
+    right_values = _list_or_none(right, "list.combinations_to")
+    if left_values is None or right_values is None:
+        return None
+
+    out: list[dict[str, Any]] = []
+    for left_index, left_value in enumerate(left_values):
+        for right_index, right_value in enumerate(right_values):
+            if skip_null and (left_value is None or right_value is None):
+                continue
+            out.append(_pair_record(fields, left_index, right_index, left_value, right_value))
+    return out
+
+
+def _pair_record(
+    fields: _CombinationFields,
+    left_index: int,
+    right_index: int,
+    left_value: Any,
+    right_value: Any,
+) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    if fields.include_index:
+        out[fields.left_index] = left_index
+        out[fields.right_index] = right_index
+    out[fields.left_value] = left_value
+    out[fields.right_value] = right_value
+    return out
+
+
+def _normalize_fields(
+    left_index: str | None,
+    right_index: str | None,
+    left_value: str,
+    right_value: str,
+    with_index: bool,
+) -> _CombinationFields:
+    _validate_with_index(with_index)
+    include_index = with_index or left_index is not None or right_index is not None
+    resolved_left_index = _DEFAULT_LEFT_INDEX if left_index is None else left_index
+    resolved_right_index = _DEFAULT_RIGHT_INDEX if right_index is None else right_index
+
+    index_names = (resolved_left_index, resolved_right_index) if include_index else ()
+    field_names = (*index_names, left_value, right_value)
+    if not all(isinstance(field, str) for field in field_names):
+        msg = "combination field names must be strings"
+        raise TypeError(msg)
+    if not (left_index is None or isinstance(left_index, str)) or not (
+        right_index is None or isinstance(right_index, str)
+    ):
+        msg = "combination index field names must be strings or None"
+        raise TypeError(msg)
+    if len(set(field_names)) != len(field_names):
+        msg = "combination field names must be unique"
+        raise ValueError(msg)
+    return _CombinationFields(
+        include_index=include_index,
+        left_index=resolved_left_index,
+        right_index=resolved_right_index,
+        left_value=left_value,
+        right_value=right_value,
+    )
+
+
+def _validate_with_index(with_index: bool) -> None:
+    if not isinstance(with_index, bool):
+        msg = "with_index must be a bool"
+        raise TypeError(msg)
+
+
+def _validate_skip_null(skip_null: bool) -> None:
+    if not isinstance(skip_null, bool):
+        msg = "skip_null must be a bool"
+        raise TypeError(msg)
+
+
+def _kwargs(fields: _CombinationFields, with_index: bool, skip_null: bool) -> dict[str, Any]:
+    return {
+        "left_index": fields.left_index if fields.include_index else None,
+        "right_index": fields.right_index if fields.include_index else None,
+        "left_value": fields.left_value,
+        "right_value": fields.right_value,
+        "with_index": with_index,
+        "skip_null": skip_null,
+    }
+
+
+def _parse_into_expr(expr: IntoExpr) -> pl.Expr:
+    if isinstance(expr, pl.Expr):
+        return expr
+    if isinstance(expr, str):
+        return pl.col(expr)
+    return pl.lit(expr)
+
+
+def _list_or_none(value: Any, name: str) -> list[Any] | None:
+    if value is None:
+        return None
+    if isinstance(value, pl.Series):
+        return value.to_list()
+    if not isinstance(value, list):
+        msg = f"{name} expects a List expression"
+        raise TypeError(msg)
+    return value
+
+
+def _row_values(row: Any, aliases: list[str]) -> list[Any]:
+    if row is None:
+        return [None] * len(aliases)
+    if isinstance(row, Mapping):
+        return [row[alias] for alias in aliases]
+    return list(row)
+
+
+def _native_library_available() -> bool:
+    return any(path.is_file() and path.suffix in _NATIVE_EXTENSIONS for path in _LIB.iterdir())