Update docs

Author: schloerke

shiny/_deprecated.py

@@ -23,8 +23,8 @@ class ShinyDeprecationWarning(RuntimeWarning):
 warnings.simplefilter("always", ShinyDeprecationWarning)
 
 
-def warn_deprecated(message: str):
-    warnings.warn(message, ShinyDeprecationWarning, stacklevel=3)
+def warn_deprecated(message: str, stacklevel: int = 3):
+    warnings.warn(message, ShinyDeprecationWarning, stacklevel=stacklevel)
 
 
 def render_text():

shiny/render/_data_frame.py

@@ -64,10 +64,11 @@ class data_frame(
     ]
 ):
     """
-    Decorator for a function that returns a [pandas](https://pandas.pydata.org/) or
-    [polars](https://pola.rs/) `DataFrame` object to render as an interactive table or
-    grid. Features fast virtualized scrolling, sorting, filtering, and row selection
-    (single or multiple).
+    Decorator for a function that returns a [pandas](https://pandas.pydata.org/),
+    [polars](https://pola.rs/), or eager
+    [`narwhals`](https://narwhals-dev.github.io/narwhals/) compatible `DataFrame` object
+    to render as an interactive table or grid. Features fast virtualized scrolling,
+    sorting, filtering, and row selection (single or multiple).
 
     Returns
     -------
@@ -77,8 +78,10 @@ class data_frame(
         1. A :class:`~shiny.render.DataGrid` or :class:`~shiny.render.DataTable` object,
            which can be used to customize the appearance and behavior of the data frame
            output.
-        2. A pandas `DataFrame` object or a polars `DataFrame` object. This object will
-           be internally upgraded to `shiny.render.DataGrid(df)`.
+        2. A [pandas](https://pandas.pydata.org/), [polars](https://pola.rs/), or eager
+           [`narwhals`](https://narwhals-dev.github.io/narwhals/) compatible `DataFrame`
+           object. This object will be internally upgraded to a default
+           `shiny.render.DataGrid(df)`.
 
     Row selection
     -------------
@@ -228,7 +231,9 @@ def data_view(self, *, selected: bool = False) -> IntoDataFrameT:
 
         See Also
         --------
-        * [`pandas.DataFrame.copy` API documentation]h(ttps://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.copy.html)
+        * [`pandas.DataFrame.copy` API documentation](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.copy.html)
+        * [`polars.DataFrame.clone` API documentation](https://docs.pola.rs/api/python/stable/reference/dataframe/api/polars.DataFrame.clone.html)
+        * [`narwhals.DataFrame.clone` API documentation](https://narwhals-dev.github.io/narwhals/api-reference/dataframe/#narwhals.dataframe.DataFrame.clone)
         """
         # Return reactive calculations so that they can be cached for other calculations
         if selected:

shiny/render/_data_frame_utils/_datagridtable.py

@@ -1,3 +1,6 @@
+# TODO-future-barret; Maybe use a `._options()` method to return a `JsonifiableDict` within the DataGrid/DataTable classes?
+# TODO-future-barret; Really feals as if we should have a base class that does most of this for us
+
 from __future__ import annotations
 
 import abc
@@ -39,8 +42,9 @@ class DataGrid(AbstractTabularData, Generic[IntoDataFrameT]):
     Parameters
     ----------
     data
-        A pandas or polars `DataFrame` object. If the object has a `.to_pandas()`
-        method, use the pandas form of your data.
+        A [pandas](https://pandas.pydata.org/), [polars](https://pola.rs/), or
+        eager [`narwhals`](https://narwhals-dev.github.io/narwhals/) compatible `DataFrame`
+        object.
     width
         A _maximum_ amount of horizontal space for the data grid to occupy, in CSS units
         (e.g. `"400px"`) or as a number, which will be interpreted as pixels. The
@@ -136,10 +140,6 @@ def __init__(
         styles: StyleInfo | list[StyleInfo] | StyleFn[IntoDataFrameT] | None = None,
         row_selection_mode: RowSelectionModeDeprecated = "deprecated",
     ):
-
-        # self._data_is_nw = isinstance(data, NwDataFrameRaw)
-        # self.data = as_narwhals(data)
-        # self.data = as_nw_friendly_data_frame(data)
         self.data = data
 
         self.width = width
@@ -201,8 +201,9 @@ class DataTable(AbstractTabularData, Generic[IntoDataFrameT]):
     Parameters
     ----------
     data
-        A pandas or polars `DataFrame` object. If the object has a `.to_pandas()`
-        method, use the pandas form of your data.
+        A [pandas](https://pandas.pydata.org/), [polars](https://pola.rs/), or
+        eager [`narwhals`](https://narwhals-dev.github.io/narwhals/) compatible `DataFrame`
+        object.
     width
         A _maximum_ amount of vertical space for the data table to occupy, in CSS units
         (e.g. `"400px"`) or as a number, which will be interpreted as pixels. The

shiny/render/_data_frame_utils/_tbl_data.py

@@ -55,7 +55,8 @@ def as_data_frame(
         return nw.from_native(data, eager_only=True)
     except TypeError as e:
         try:
-            return nw.from_native(compatible_to_pandas(data), eager_only=True)
+            compatible_data = compatible_to_pandas(data)
+            return nw.from_native(compatible_data, eager_only=True)
         except TypeError:
             # Couldn't convert to pandas, so raise the original error
             raise e
@@ -79,7 +80,8 @@ def compatible_to_pandas(
             "A `.to_pandas()` was found on your object and will be called. "
             "To remove this warning, please call `.to_pandas()` on your data "
             "and use the pandas result in your returned value. "
-            "In the future, this will raise an error."
+            "In the future, this will raise an error.",
+            stacklevel=3,
         )
         return data.to_pandas()