Add native Polars DataFrame support

.gitignore

@@ -24,6 +24,13 @@ __pycache__/
 
 # virtual environments
 /venv/
+/.venv/
+
+# uv lock file (this is a library; lock files are for applications)
+/uv.lock
+
+# Claude Code
+/.claude
 
 # PyCharm project files
 /.idea

README.md

@@ -20,7 +20,22 @@ simply `spotfire`) to include the required Python packages to support optional f
 | `spotfire[plot-matplotlib]` | Plotting support using just `matplotlib`     |
 | `spotfire[plot-pil]`        | Plotting support using just `Pillow`         |
 | `spotfire[plot-seaborn]`    | Plotting support using just `seaborn`        |
+| `spotfire[polars]`          | Polars DataFrame support                     |
 | `spotfire[dev,lint]`        | Internal development                         |
 
+Once installed, `export_data()` accepts `polars.DataFrame` and `polars.Series` directly, and
+`import_data()` can return a `polars.DataFrame`:
+
+```python
+import spotfire.sbdf as sbdf
+
+df = sbdf.import_data("data.sbdf", output_format=sbdf.OutputFormat.POLARS)
+```
+
+> **Note for Spotfire data functions:** Spotfire's bundled Python interpreter does not include
+> Polars. To use Polars inside a data function, configure Spotfire to use a custom Python
+> environment that has `polars` installed. Polars is a large binary package (~44 MB), so
+> Spotfire Packages (SPKs) that bundle it will be significantly larger than typical packages.
+
 ### License
 BSD-type 3-Clause License.  See the file ```LICENSE``` included in the package.

pyproject.toml

@@ -54,9 +54,13 @@ plot-seaborn = [
     "seaborn >= 0.13.2",
 ]
 plot = [ "spotfire[plot-matplotlib,plot-pil,plot-seaborn]" ]
+# Polars support
+polars = [
+    "polars >= 0.20.0",
+]
 # Development requirements
 dev = [
-    "spotfire[geo,plot]",
+    "spotfire[geo,plot,polars]",
     "Cython >= 3.0.4",
     "html-testRunner",
 ]
@@ -283,5 +287,6 @@ plugins = ["numpy.typing.mypy_plugin"]
 module = [
     "geopandas",
     "HtmlTestRunner",
+    "polars",
 ]
 ignore_missing_imports = true

spotfire/__init__.py

@@ -5,3 +5,4 @@
 """User visible utility functions."""
 
 from spotfire.public import copy_metadata, get_spotfire_types, set_spotfire_types, set_geocoding_table
+from spotfire.sbdf import OutputFormat

spotfire/data_function.py

@@ -165,19 +165,19 @@ def read(self, globals_dict: _Globals, debug_fn: _LogFunction) -> None:
 
         # Argument type
         if self._type == "column":
-            dataframe = dataframe[dataframe.columns[0]]
+            dataframe = dataframe[dataframe.columns[0]]  # type: ignore[assignment]
         if self._type == "value":
             value = dataframe.at[0, dataframe.columns[0]]
             if type(value).__module__ == "numpy":
-                dataframe = value.tolist()
+                dataframe = value.tolist()  # type: ignore[assignment, union-attr]
             elif type(value).__module__ == "pandas._libs.tslibs.timedeltas":
-                dataframe = value.to_pytimedelta()
+                dataframe = value.to_pytimedelta()  # type: ignore[assignment, union-attr]
             elif type(value).__module__ == "pandas._libs.tslibs.timestamps":
-                dataframe = value.to_pydatetime()
+                dataframe = value.to_pydatetime()  # type: ignore[assignment, union-attr]
             elif type(value).__module__ == "pandas._libs.tslibs.nattype":
-                dataframe = None
+                dataframe = None  # type: ignore[assignment]
             else:
-                dataframe = value
+                dataframe = value  # type: ignore[assignment]
 
         # Store to global dict
         globals_dict[self._name] = dataframe

spotfire/public.py

@@ -18,6 +18,16 @@
 
 _ColumnTypes = dict[str, str]
 
+_POLARS_METADATA_ERROR = (
+    "Polars DataFrames do not support Spotfire metadata; "
+    "see https://github.com/pola-rs/polars/issues/5117"
+)
+
+
+def _is_polars_type(obj) -> bool:
+    """Return True if obj is a Polars DataFrame or Series."""
+    return type(obj).__module__.startswith("polars")
+
 
 # Table and column metadata functions
 
@@ -28,6 +38,8 @@ def copy_metadata(source, destination) -> None:
     :param destination: the DataFrame or Series to copy metadata to
     :raise TypeError: if the types of source and destination do not match
     """
+    if _is_polars_type(source) or _is_polars_type(destination):
+        raise TypeError(_POLARS_METADATA_ERROR)
     # Verify that types of source and destination match
     if isinstance(source, pd.DataFrame) and not isinstance(destination, pd.DataFrame):
         raise TypeError("both source and destination must be DataFrames")
@@ -65,6 +77,8 @@ def get_spotfire_types(dataframe: pd.DataFrame) -> pd.Series:
     :param dataframe: the DataFrame to get the Spotfire types of
     :returns: a Series containing the Spotfire types of each column of dataframe
     """
+    if _is_polars_type(dataframe):
+        raise TypeError(_POLARS_METADATA_ERROR)
     if not isinstance(dataframe, pd.DataFrame):
         raise TypeError("dataframe is not a DataFrame")
     spotfire_types = {}
@@ -83,6 +97,8 @@ def set_spotfire_types(dataframe: pd.DataFrame, column_types: _ColumnTypes) -> N
     :param dataframe: the DataFrame to set the Spotfire types of
     :param column_types: dictionary that maps column names to column types
     """
+    if _is_polars_type(dataframe):
+        raise TypeError(_POLARS_METADATA_ERROR)
     if not isinstance(dataframe, pd.DataFrame):
         raise TypeError("dataframe is not a DataFrame")
     for col, spotfire_type in column_types.items():

spotfire/sbdf.pyi

@@ -2,17 +2,29 @@
 # This file is subject to the license terms contained
 # in the license file that is distributed with this file.
 
+import enum
 import typing
 
 import pandas as pd
 
+if typing.TYPE_CHECKING:
+    import polars as pl
+
 
 _FilenameLike = typing.Union[str, bytes, int]
 
 class SBDFError(Exception): ...
 class SBDFWarning(Warning): ...
 
+class OutputFormat(enum.Enum):
+    """Supported output formats for :func:`import_data`."""
+    PANDAS: str
+    POLARS: str
+
 def spotfire_typename_to_valuetype_id(typename: str) -> typing.Optional[int]: ...
-def import_data(sbdf_file: _FilenameLike): ...
+@typing.overload
+def import_data(sbdf_file: _FilenameLike, output_format: typing.Literal[OutputFormat.PANDAS] = ...) -> pd.DataFrame: ...
+@typing.overload
+def import_data(sbdf_file: _FilenameLike, output_format: typing.Literal[OutputFormat.POLARS]) -> "pl.DataFrame": ...
 def export_data(obj: typing.Any, sbdf_file: _FilenameLike, default_column_name: str = "x",
                 rows_per_slice: int = 0, encoding_rle: bool = True) -> None: ...