feat: update DataFrame view methods and deprecate old API

Author: kosiew

docs/source/user-guide/io/table_provider.rst

@@ -51,7 +51,7 @@ Once you have this library available, you can construct a
 :py:class:`~datafusion.catalog.Table` in Python and register it with the
 ``SessionContext``.  Tables can be created either from the PyCapsule exposed by
 your Rust provider or from an existing :py:class:`~datafusion.dataframe.DataFrame`
-view.
+view created via ``df.into_view()`` (or the alias ``Table.from_dataframe(df)``).
 
 .. code-block:: python
 
@@ -63,10 +63,13 @@ view.
     table_from_capsule = Table.from_capsule(provider)
 
     df = ctx.from_pydict({"a": [1]})
-    table_from_view = Table.from_view(df)
+    provider_from_view = df.into_view()
 
     ctx.register_table("capsule_table", table_from_capsule)
-    ctx.register_table("view_table", table_from_view)
+    ctx.register_table("view_table", provider_from_view)
 
     ctx.table("capsule_table").show()
     ctx.table("view_table").show()
+
+``Table.from_dataframe(df)`` is available as an alias for ``df.into_view()``,
+but the latter is the preferred API.

python/datafusion/dataframe.py

@@ -309,7 +309,13 @@ def __init__(self, df: DataFrameInternal) -> None:
         self.df = df
 
     def into_view(self) -> TableProviderInternal:
-        """Convert ``DataFrame`` into a ``TableProvider`` view for registration."""
+        """Convert ``DataFrame`` into a ``TableProvider`` view for registration.
+
+        This is the preferred way to obtain a view for
+        :py:meth:`~datafusion.context.SessionContext.register_table`.
+        ``TableProvider.from_dataframe`` calls this method under the hood,
+        and the older ``TableProvider.from_view`` helper is deprecated.
+        """
         return self.df.into_view()
 
     def __getitem__(self, key: str | list[str]) -> DataFrame:

src/dataframe.rs

@@ -268,7 +268,7 @@ impl PyDataFrame {
         }
     }
 
-    pub(crate) fn into_view_provider(&self) -> Arc<dyn TableProvider + Send> {
+    pub(crate) fn to_view_provider(&self) -> Arc<dyn TableProvider + Send> {
         self.df.as_ref().clone().into_view()
     }
 
@@ -409,7 +409,7 @@ impl PyDataFrame {
         // Call the underlying Rust DataFrame::into_view method.
         // Note that the Rust method consumes self; here we clone the inner Arc<DataFrame>
         // so that we don’t invalidate this PyDataFrame.
-        let table_provider = self.into_view_provider();
+        let table_provider = self.to_view_provider();
         Ok(PyTableProvider::new(table_provider))
     }
 

src/table.rs

@@ -20,6 +20,7 @@ use std::sync::Arc;
 
 use datafusion::datasource::TableProvider;
 use datafusion_ffi::table_provider::{FFI_TableProvider, ForeignTableProvider};
+use pyo3::exceptions::PyDeprecationWarning;
 use pyo3::prelude::*;
 use pyo3::types::PyCapsule;
 
@@ -53,21 +54,39 @@ impl PyTableProvider {
     #[staticmethod]
     pub fn from_capsule(capsule: Bound<'_, PyAny>) -> PyResult<Self> {
         let capsule = capsule.downcast::<PyCapsule>().map_err(py_datafusion_err)?;
-        validate_pycapsule(&capsule, "datafusion_table_provider")?;
+        validate_pycapsule(capsule, "datafusion_table_provider")?;
 
         let provider = unsafe { capsule.reference::<FFI_TableProvider>() };
         let provider: ForeignTableProvider = provider.into();
 
         Ok(Self::new(Arc::new(provider)))
     }
 
-    /// Create a `TableProvider` from a DataFrame by converting it into a view
+    /// Create a `TableProvider` from a `DataFrame`.
+    ///
+    /// This method simply delegates to `DataFrame.into_view`.
     #[staticmethod]
-    pub fn from_view(df: &PyDataFrame) -> PyDataFusionResult<Self> {
-        let table_provider = df.into_view_provider();
+    pub fn from_dataframe(df: &PyDataFrame) -> PyDataFusionResult<Self> {
+        let table_provider = df.to_view_provider();
         Ok(Self::new(table_provider))
     }
 
+    /// Create a `TableProvider` from a `DataFrame` by converting it into a view.
+    ///
+    /// Deprecated: prefer `DataFrame.into_view` or
+    /// `TableProvider.from_dataframe` instead.
+    #[staticmethod]
+    pub fn from_view(py: Python<'_>, df: &PyDataFrame) -> PyDataFusionResult<Self> {
+        py.import("warnings")?.call_method1(
+            "warn",
+            (
+                "PyTableProvider.from_view() is deprecated; use DataFrame.into_view() or TableProvider.from_dataframe() instead.",
+                py.get_type::<PyDeprecationWarning>(),
+            ),
+        )?;
+        Self::from_dataframe(df)
+    }
+
     fn __datafusion_table_provider__<'py>(
         &self,
         py: Python<'py>,