Support adaptor in prepare_pin_version

Author: nathanjmcdougall

pins/adaptors.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from abc import abstractmethod
+from typing import TYPE_CHECKING, Any, ClassVar, Self, TypeAlias, overload
+
+from ._databackend import AbstractBackend
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+    _PandasDataFrame: TypeAlias = pd.DataFrame
+    _DataFrame: TypeAlias = pd.DataFrame
+
+
+class _AbstractPandasFrame(AbstractBackend):
+    _backends = [("pandas", "DataFrame")]
+
+
+_AbstractDF: TypeAlias = _AbstractPandasFrame
+
+
+class _Adaptor:
+    _d: ClassVar[Any]
+
+    def __init__(self, data: Any) -> None:
+        self._d = data
+
+
+class _DFAdaptor(_Adaptor):
+    _d: ClassVar[_DataFrame]
+
+    def __init__(self, data: _DataFrame) -> None:
+        super().__init__(data)
+
+    @property
+    @abstractmethod
+    def columns(self) -> list[Any]: ...
+
+    @abstractmethod
+    def head(self, n: int) -> Self: ...
+
+    @abstractmethod
+    def write_json(self) -> str:
+        """Write the dataframe to a JSON string.
+
+        In the format: list like [{column -> value}, ... , {column -> value}]
+        """
+
+
+class _PandasAdaptor(_DFAdaptor):
+    def __init__(self, data: _AbstractPandasFrame) -> None:
+        super().__init__(data)
+
+    @property
+    def columns(self) -> list[Any]:
+        return self._d.columns
+
+    def head(self, n: int) -> Self:
+        return _PandasAdaptor(self._d.head(n))
+
+    def write_json(self) -> str:
+        return self._d.to_json(orient="records")
+
+
+@overload
+def _create_df_adaptor(df: _DataFrame) -> _DFAdaptor: ...
+@overload
+def _create_df_adaptor(df: _PandasDataFrame) -> _PandasAdaptor: ...
+def _create_df_adaptor(df):
+    if isinstance(df, _AbstractPandasFrame):
+        return _PandasAdaptor(df)
+
+    msg = f"Could not determine dataframe adaptor for {df}"
+    raise NotImplementedError(msg)

pins/boards.py

@@ -7,10 +7,11 @@
 from datetime import datetime, timedelta
 from io import IOBase
 from pathlib import Path
-from typing import Mapping, Optional, Protocol, Sequence
+from typing import Any, Mapping, Optional, Protocol, Sequence
 
 from importlib_resources import files
 
+from .adaptors import _create_df_adaptor, _DFAdaptor
 from .cache import PinsCache
 from .config import get_allow_rsc_short_name
 from .drivers import default_title, load_data, load_file, save_data
@@ -1121,15 +1122,24 @@ def path_to_deploy_version(self, name: str, version: str):
     def user_name(self):
         return self.fs.api.get_user()["username"]
 
+    # TODO(NAMC) what about the functions that call this one?
     def prepare_pin_version(self, pin_dir_path, x, name: "str | None", *args, **kwargs):
+        try:
+            x = _create_df_adaptor(x)
+        except NotImplementedError:
+            # Not a dataframe.
+            pass
+
         # RSC pin names can have form <user_name>/<name>, but this will try to
         # create the object in a directory named <user_name>. So we grab just
         # the <name> part.
         short_name = name.split("/")[-1]
 
         # TODO(compat): py pins always uses the short name, R pins uses w/e the
         # user passed, but guessing people want the long name?
-        meta = super()._create_meta(pin_dir_path, x, short_name, *args, **kwargs)
+        meta = super()._create_meta(
+            pin_dir_path, x, short_name, *args, **kwargs
+        )  # TODO(NAMC) ensure .create_meta can accept adaptor
         meta.name = name
 
         # copy in files needed by index.html ----------------------------------
@@ -1147,7 +1157,7 @@ def prepare_pin_version(self, pin_dir_path, x, name: "str | None", *args, **kwar
         # render index.html ------------------------------------------------
 
         all_files = [meta.file] if isinstance(meta.file, str) else meta.file
-        pin_files = ", ".join(f"""<a href="{x}">{x}</a>""" for x in all_files)
+        pin_files = ", ".join(f"""<a href="{file}">{file}</a>""" for file in all_files)
 
         context = {
             "date": meta.version.created.replace(microsecond=0),
@@ -1164,15 +1174,13 @@ def prepare_pin_version(self, pin_dir_path, x, name: "str | None", *args, **kwar
 
         import json
 
-        import pandas as pd
-
-        if isinstance(x, pd.DataFrame):
+        if isinstance(x, _DFAdaptor):
             # TODO(compat) is 100 hard-coded?
-            # Note that we go df -> json -> dict, to take advantage of pandas type conversions
-            data = json.loads(x.head(100).to_json(orient="records"))
+            # Note that we go df -> json -> dict, to take advantage of type conversions in the dataframe library
+            data: list[dict[Any, Any]] = json.loads(x.head(100).write_json())
             columns = [
                 {"name": [col], "label": [col], "align": ["left"], "type": [""]}
-                for col in x
+                for col in x.columns
             ]
 
             # this reproduces R pins behavior, by omitting entries that would be null

pins/tests/test_adaptors.py

@@ -0,0 +1,46 @@
+import pandas as pd
+import pytest
+from pandas.testing import assert_frame_equal, assert_index_equal
+
+from pins.adaptors import _AbstractPandasFrame, _create_df_adaptor, _PandasAdaptor
+
+
+class TestCreateDFAdaptor:
+    def test_pandas(self):
+        df = pd.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})
+        adaptor = _create_df_adaptor(df)
+        assert isinstance(adaptor, _PandasAdaptor)
+
+    def test_non_df(self):
+        with pytest.raises(NotImplementedError):
+            _create_df_adaptor(42)
+
+
+class TestPandasAdaptor:
+    def test_columns(self):
+        df = pd.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})
+        adaptor = _create_df_adaptor(df)
+        assert_index_equal(adaptor.columns, pd.Index(["a", "b"]))
+
+    def test_head(self):
+        df = pd.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})
+        adaptor = _create_df_adaptor(df)
+        head1_df = pd.DataFrame({"a": [1], "b": [4]})
+        expected = _create_df_adaptor(head1_df)
+        assert isinstance(adaptor.head(1), _PandasAdaptor)
+        assert_frame_equal(adaptor.head(1)._d, expected._d)
+
+    def test_write_json(self):
+        df = pd.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})
+        adaptor = _create_df_adaptor(df)
+        assert adaptor.write_json() == """[{"a":1,"b":4},{"a":2,"b":5},{"a":3,"b":6}]"""
+
+
+class TestAbstractBackends:
+    class TestAbstractPandasFrame:
+        def test_isinstance(self):
+            df = pd.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})
+            assert isinstance(df, _AbstractPandasFrame)
+
+        def test_not_isinstance(self):
+            assert not isinstance(42, _AbstractPandasFrame)