betterframe 0.1.0__tar.gz

betterframe-0.1.0/.github/workflows/ci.yaml

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          uv sync --dev
+
+      - name: Lint with ruff
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+
+      - name: Test with pytest
+        run: |
+          uv run pytest
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.9
+
+      - name: Build package
+        run: uv build
+
+      - name: Check package
+        run: |
+          uv tool install twine
+          uv tool run twine check dist/*

betterframe-0.1.0/.github/workflows/release.yaml

@@ -0,0 +1,42 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write # For trusted publishing to PyPI
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.9
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Check linting
+        run: |
+          uv run ruff check .
+          uv run ruff format --check .
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          print-hash: true

betterframe-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Local Python version pin (pyenv/uv/asdf)
+.python-version
+
+# uv
+uv.lock.bak

betterframe-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,16 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.5
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      - id: pytest
+        name: pytest
+        entry: uv run pytest
+        language: system
+        pass_filenames: false
+        always_run: true

betterframe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Izzet Yildirim
+
+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.

betterframe-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: betterframe
+Version: 0.1.0
+Summary: Write a dataframe pipeline once, run it on Dask or pandas
+Project-URL: Homepage, https://github.com/izzet/betterframe
+Project-URL: Repository, https://github.com/izzet/betterframe
+Project-URL: Documentation, https://github.com/izzet/betterframe#readme
+Project-URL: Bug Tracker, https://github.com/izzet/betterframe/issues
+Author-email: Izzet Yildirim <izzetcyildirim@gmail.com>
+Maintainer-email: Izzet Yildirim <izzetcyildirim@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: dask,dataframe,meta,pandas,partitions,python
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: pandas>=1.5
+Provides-Extra: dask
+Requires-Dist: dask[dataframe]>=2023.1.0; extra == 'dask'
+Description-Content-Type: text/markdown
+
+# BetterFrame
+
+Write a dataframe pipeline once, run it on Dask or pandas.
+
+Not a DataFrame implementation. BetterFrame adapts the *execution semantics*
+that differ between the two engines — per-partition application, meta schemas,
+aggregation keywords, persistence — so a pipeline that has to work on both does
+not fill up with `if is_dask:` branches.
+
+## Why
+
+Dask is the right tool when data outgrows memory, and a needless tax when it
+does not. A pipeline that wants both ends up either duplicated or littered with
+engine checks. The differences are few but awkward:
+
+| | Dask | pandas |
+|---|---|---|
+| apply a function per partition | `df.map_partitions(fn, meta=…)` | `fn(df)` |
+| index level names | `df.index._meta.names` | `df.index.names` |
+| `groupby().agg()` extras | `split_out=…` | — |
+| make the result concrete | `df.persist()` | already is |
+| column assignment | builds a graph | mutates in place |
+
+## Install
+
+```bash
+pip install betterframe          # pandas only
+pip install "betterframe[dask]"  # to drive Dask frames as well
+```
+
+## Use
+
+```python
+from betterframe import BetterFrame
+
+
+def compute(records):
+    frame = BetterFrame(records).mutable()  # records may be Dask or pandas
+    frame = frame.apply(normalise, meta=lambda: build_meta(frame.meta_source()))
+    result = frame.pipe(
+        lambda df, kw=frame.agg_kwargs(): df.groupby("key").agg({"scaled": "sum"}, **kw)
+    )
+    return result.finalize()
+```
+
+`BetterFrame` binds a frame to the operations its engine needs, so the frame
+stops being an argument to every call. Methods that produce a frame return a
+`BetterFrame`, so a pipeline chains; `finalize()` ends the chain and hands back
+a native frame, and `native` reaches the underlying one at any point.
+
+It is deliberately thin — it does **not** proxy the dataframe API. Real work
+still happens on the frame itself, through `pipe()` or `native`. Wrapping exists
+to answer engine questions, not to replace pandas.
+
+The same function now runs on either engine, and there is exactly one place —
+this package — that knows the difference.
+
+## The part worth knowing about
+
+Most of the surface is mechanical. The subtle part is Dask's `meta` handling,
+because getting it wrong produces frames that differ **only in dtype, only for
+empty inputs, and only sometimes**:
+
+* Dask coerces *every* partition to a meta schema. A helper that short-circuits
+  on an empty frame and returns it unchanged still comes out with the populated
+  schema, because Dask repairs it afterwards.
+* Where no explicit meta is given, Dask *infers* one by running the function
+  against a synthetic non-empty frame. So even without a meta, an empty
+  partition ends up with the schema the function would have produced had there
+  been rows.
+
+pandas does neither. `PandasOps.apply` reproduces both, so an empty frame is
+not silently a different dtype depending on which engine produced it. This is
+the failure mode BetterFrame exists to prevent: it is invisible in every test
+whose fixtures happen to be fully populated.
+
+## Extending
+
+Subclass `DaskOps` / `PandasOps` for engine-specific behaviour of your own —
+custom aggregations, say — and hand the subclasses to `BetterFrame`:
+
+```python
+from betterframe import BetterFrame, DaskOps, PandasOps
+
+
+class MyDaskOps(DaskOps):
+    def set_union(self):
+        return some_dask_aggregation()
+
+
+class MyPandasOps(PandasOps):
+    def set_union(self):
+        return some_pandas_callable
+
+
+frame = BetterFrame(records, dask_ops=MyDaskOps, pandas_ops=MyPandasOps)
+frame.ops.set_union()  # `ops` reaches engine questions that take no frame
+```
+
+Domain-specific aggregations are deliberately left out of the core so the
+package stays about engine semantics.
+
+## Development
+
+```bash
+uv sync --dev
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+```
+
+## License
+
+MIT

betterframe-0.1.0/README.md

@@ -0,0 +1,114 @@
+# BetterFrame
+
+Write a dataframe pipeline once, run it on Dask or pandas.
+
+Not a DataFrame implementation. BetterFrame adapts the *execution semantics*
+that differ between the two engines — per-partition application, meta schemas,
+aggregation keywords, persistence — so a pipeline that has to work on both does
+not fill up with `if is_dask:` branches.
+
+## Why
+
+Dask is the right tool when data outgrows memory, and a needless tax when it
+does not. A pipeline that wants both ends up either duplicated or littered with
+engine checks. The differences are few but awkward:
+
+| | Dask | pandas |
+|---|---|---|
+| apply a function per partition | `df.map_partitions(fn, meta=…)` | `fn(df)` |
+| index level names | `df.index._meta.names` | `df.index.names` |
+| `groupby().agg()` extras | `split_out=…` | — |
+| make the result concrete | `df.persist()` | already is |
+| column assignment | builds a graph | mutates in place |
+
+## Install
+
+```bash
+pip install betterframe          # pandas only
+pip install "betterframe[dask]"  # to drive Dask frames as well
+```
+
+## Use
+
+```python
+from betterframe import BetterFrame
+
+
+def compute(records):
+    frame = BetterFrame(records).mutable()  # records may be Dask or pandas
+    frame = frame.apply(normalise, meta=lambda: build_meta(frame.meta_source()))
+    result = frame.pipe(
+        lambda df, kw=frame.agg_kwargs(): df.groupby("key").agg({"scaled": "sum"}, **kw)
+    )
+    return result.finalize()
+```
+
+`BetterFrame` binds a frame to the operations its engine needs, so the frame
+stops being an argument to every call. Methods that produce a frame return a
+`BetterFrame`, so a pipeline chains; `finalize()` ends the chain and hands back
+a native frame, and `native` reaches the underlying one at any point.
+
+It is deliberately thin — it does **not** proxy the dataframe API. Real work
+still happens on the frame itself, through `pipe()` or `native`. Wrapping exists
+to answer engine questions, not to replace pandas.
+
+The same function now runs on either engine, and there is exactly one place —
+this package — that knows the difference.
+
+## The part worth knowing about
+
+Most of the surface is mechanical. The subtle part is Dask's `meta` handling,
+because getting it wrong produces frames that differ **only in dtype, only for
+empty inputs, and only sometimes**:
+
+* Dask coerces *every* partition to a meta schema. A helper that short-circuits
+  on an empty frame and returns it unchanged still comes out with the populated
+  schema, because Dask repairs it afterwards.
+* Where no explicit meta is given, Dask *infers* one by running the function
+  against a synthetic non-empty frame. So even without a meta, an empty
+  partition ends up with the schema the function would have produced had there
+  been rows.
+
+pandas does neither. `PandasOps.apply` reproduces both, so an empty frame is
+not silently a different dtype depending on which engine produced it. This is
+the failure mode BetterFrame exists to prevent: it is invisible in every test
+whose fixtures happen to be fully populated.
+
+## Extending
+
+Subclass `DaskOps` / `PandasOps` for engine-specific behaviour of your own —
+custom aggregations, say — and hand the subclasses to `BetterFrame`:
+
+```python
+from betterframe import BetterFrame, DaskOps, PandasOps
+
+
+class MyDaskOps(DaskOps):
+    def set_union(self):
+        return some_dask_aggregation()
+
+
+class MyPandasOps(PandasOps):
+    def set_union(self):
+        return some_pandas_callable
+
+
+frame = BetterFrame(records, dask_ops=MyDaskOps, pandas_ops=MyPandasOps)
+frame.ops.set_union()  # `ops` reaches engine questions that take no frame
+```
+
+Domain-specific aggregations are deliberately left out of the core so the
+package stays about engine semantics.
+
+## Development
+
+```bash
+uv sync --dev
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+```
+
+## License
+
+MIT

betterframe-0.1.0/betterframe/__init__.py

@@ -0,0 +1,38 @@
+"""BetterFrame: write a dataframe pipeline once, run it on Dask or pandas.
+
+Not a DataFrame implementation. It adapts the *execution semantics* that differ
+between engines -- per-partition application, meta schemas, aggregation
+keywords, persistence -- so a pipeline that must work on both does not fill up
+with ``if is_dask:`` branches.
+
+Public API:
+- :class:`BetterFrame` -- a frame bound to the operations its engine needs
+- :class:`DaskOps` / :class:`PandasOps` -- subclass to add engine-specific
+  behaviour of your own, and pass to :class:`BetterFrame`
+- :func:`is_dask_frame` -- engine test that does not import Dask needlessly
+
+Example::
+
+    from betterframe import BetterFrame
+
+    frame = BetterFrame(records).mutable()
+    frame = frame.apply(normalise, meta=lambda: build_meta(frame.meta_source()))
+    result = frame.pipe(lambda df: df.groupby("key").agg(aggs, **frame.agg_kwargs()))
+    return result.finalize()
+"""
+
+from __future__ import annotations
+
+from .frame import BetterFrame
+from .ops import DaskOps, DataFrameOps, MetaSource, PandasOps, is_dask_frame
+
+__all__ = [
+    "BetterFrame",
+    "DaskOps",
+    "DataFrameOps",
+    "MetaSource",
+    "PandasOps",
+    "is_dask_frame",
+]
+
+__version__ = "0.1.0"

betterframe-0.1.0/betterframe/frame.py

@@ -0,0 +1,113 @@
+"""``BetterFrame`` -- a frame bound to the operations its engine needs.
+
+Every operation that differs between Dask and pandas takes the frame as its
+first argument, so binding the frame removes that argument from every call and
+lets a pipeline chain instead of repeating itself.
+
+The wrapper is deliberately thin. It does not proxy the dataframe API: real
+work still happens on the frame itself, reached through :attr:`native` or
+:meth:`pipe`. Wrapping exists to answer engine questions, not to replace pandas.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from .ops import DaskOps, DataFrameOps, PandasOps, is_dask_frame
+
+__all__ = ["BetterFrame"]
+
+
+class BetterFrame:
+    """A dataframe together with the operations its engine requires.
+
+    Args:
+        frame: A Dask or pandas DataFrame.
+        dask_ops: Operations class to use for Dask frames. Subclass
+            :class:`~betterframe.DaskOps` to add behaviour of your own.
+        pandas_ops: Operations class to use for pandas frames.
+
+    Methods that produce a frame return a new ``BetterFrame``, so a pipeline
+    chains. :meth:`finalize` ends the chain and hands back a native frame.
+    """
+
+    __slots__ = ("_frame", "_ops")
+
+    def __init__(
+        self,
+        frame: Any,
+        *,
+        dask_ops: type[DataFrameOps] = DaskOps,
+        pandas_ops: type[DataFrameOps] = PandasOps,
+    ) -> None:
+        self._frame = frame
+        self._ops = dask_ops() if is_dask_frame(frame) else pandas_ops()
+
+    # --- access ---------------------------------------------------------
+
+    @property
+    def native(self) -> Any:
+        """The underlying dataframe, for operations that need no adaptation."""
+        return self._frame
+
+    @property
+    def ops(self) -> DataFrameOps:
+        """The operations object, for engine questions that take no frame."""
+        return self._ops
+
+    @property
+    def is_dask(self) -> bool:
+        return self._ops.is_dask
+
+    def _wrap(self, frame: Any) -> BetterFrame:
+        new = object.__new__(BetterFrame)
+        new._frame = frame
+        new._ops = self._ops
+        return new
+
+    # --- operations -----------------------------------------------------
+
+    def apply(
+        self, fn: Callable, *args: Any, meta: Callable | None = None, **kwargs: Any
+    ) -> BetterFrame:
+        """Apply a per-partition function.
+
+        ``meta`` is a thunk rather than a value so Dask-only meta builders are
+        never invoked on a pandas frame.
+        """
+        return self._wrap(self._ops.apply(self._frame, fn, *args, meta=meta, **kwargs))
+
+    def pipe(self, fn: Callable, *args: Any, **kwargs: Any) -> BetterFrame:
+        """Run a function against the whole native frame and stay wrapped.
+
+        For operations that need no adaptation -- ``groupby``, ``rename`` and
+        the like -- where dropping to :attr:`native` and re-wrapping would only
+        add noise.
+        """
+        return self._wrap(fn(self._frame, *args, **kwargs))
+
+    def mutable(self) -> BetterFrame:
+        """A frame whose columns may be assigned without affecting the caller."""
+        return self._wrap(self._ops.mutable(self._frame))
+
+    def index_names(self) -> Any:
+        """Names of the frame's index levels."""
+        return self._ops.index_names(self._frame)
+
+    def agg_kwargs(self) -> dict[str, Any]:
+        """Extra keyword arguments for ``groupby().agg()`` on this engine."""
+        return self._ops.agg_kwargs(self._frame)
+
+    def meta_source(self) -> Any:
+        """Something a Dask meta builder can read ``.columns`` and ``._meta`` from."""
+        return self._ops.meta_source(self._frame)
+
+    def finalize(self) -> Any:
+        """Make the result concrete and return the native frame."""
+        return self._ops.finalize(self._frame)
+
+    # --- niceties -------------------------------------------------------
+
+    def __repr__(self) -> str:
+        engine = "dask" if self.is_dask else "pandas"
+        return f"BetterFrame({engine}, {type(self._frame).__name__})"