frameworthy 0.1.0__tar.gz

frameworthy-0.1.0/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.3
+Name: frameworthy
+Version: 0.1.0
+Summary: Add your description here
+Author: joypauls
+Author-email: joypauls <joypaulsen3@gmail.com>
+Requires-Dist: narwhals>=2.25.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# frameworthy [WIP]
+
+Frameworthy is a lightweight Python testing library for DataFrames and analytical transformations, supporting both pandas and polars. Instead of requiring exact expected outputs, it lets you express the properties a transformation should preserve or change: rows, keys, columns, values, aggregates, and more.
+
+Many DataFrame tests never get written because verifying a transformation means constructing a second expected dataset. The goal of Frameworthy is to make it easy to test the guarantees you actually care about.
+
+
+
+
+

frameworthy-0.1.0/README.md

@@ -0,0 +1,10 @@
+# frameworthy [WIP]
+
+Frameworthy is a lightweight Python testing library for DataFrames and analytical transformations, supporting both pandas and polars. Instead of requiring exact expected outputs, it lets you express the properties a transformation should preserve or change: rows, keys, columns, values, aggregates, and more.
+
+Many DataFrame tests never get written because verifying a transformation means constructing a second expected dataset. The goal of Frameworthy is to make it easy to test the guarantees you actually care about.
+
+
+
+
+

frameworthy-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "frameworthy"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "joypauls", email = "joypaulsen3@gmail.com" }
+]
+requires-python = ">=3.13"
+dependencies = [
+    "narwhals>=2.25.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.3,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pandas>=3.0.5",
+    "polars>=1.44.0",
+    "pyright>=1.1.411",
+    "pytest>=9.1.1",
+    "ruff>=0.16.4",
+]

frameworthy-0.1.0/src/frameworthy/__init__.py

@@ -0,0 +1,7 @@
+from frameworthy._errors import FrameworthyAssertionError
+from frameworthy._expectation import expect
+
+__all__ = [
+    "FrameworthyAssertionError",
+    "expect",
+]

frameworthy-0.1.0/src/frameworthy/_errors.py

@@ -0,0 +1,3 @@
+# needs to subclass AssertionError to work with pytest
+class FrameworthyAssertionError(AssertionError):
+    """Raised when a Frameworthy expectation is not satisfied"""

frameworthy-0.1.0/src/frameworthy/_expectation.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import narwhals.stable.v2 as nw
+from narwhals.stable.v2.typing import IntoDataFrame
+
+from frameworthy._errors import FrameworthyAssertionError
+
+
+class TransformationExpectation:
+    """Assertions about the relationship between two DataFrame states"""
+
+    def __init__(
+        self,
+        after: IntoDataFrame,
+        *,
+        relative_to: IntoDataFrame,
+    ) -> None:
+        self._before = nw.from_native(relative_to, eager_only=True)
+        self._after = nw.from_native(after, eager_only=True)
+
+        # should we store the native frames too?
+        # self._before_native = relative_to
+        # self._after_native = after
+
+    def preserves_rows(self) -> None:
+        """Assert that the transformation preserves row count"""
+        before_rows = self._before.shape[0]
+        after_rows = self._after.shape[0]
+
+        if before_rows == after_rows:
+            return
+
+        difference = after_rows - before_rows
+
+        raise FrameworthyAssertionError(
+            format_row_count_failure(
+                before_rows=before_rows,
+                after_rows=after_rows,
+                difference=difference,
+            )
+        )
+
+
+def expect(
+    after: IntoDataFrame,
+    *,
+    relative_to: IntoDataFrame,
+) -> TransformationExpectation:
+    """Create expectations about a DataFrame relative to an earlier state"""
+    return TransformationExpectation(
+        after,
+        relative_to=relative_to,
+    )
+
+
+def format_row_count_failure(
+    *,
+    before_rows: int,
+    after_rows: int,
+    difference: int,
+) -> str:
+    if before_rows == 0:
+        percentage = None
+    else:
+        percentage = difference / before_rows
+
+    direction = "introduced" if difference > 0 else "removed"
+    absolute_difference = abs(difference)
+
+    if percentage is None:
+        change_display = f"{difference:+,} rows"
+    else:
+        change_display = f"{difference:+,} rows ({percentage:+.2%})"
+
+    return (
+        "Expected transformation to preserve row count.\n"
+        "\n"
+        f"before    {before_rows:,} rows\n"
+        f"after     {after_rows:,} rows\n"
+        f"change    {change_display}\n"
+        "\n"
+        f"The transformation {direction} "
+        f"{absolute_difference:,} "
+        f"{'row' if absolute_difference == 1 else 'rows'}."
+    )