docs: update deprecation warnings and references for TableProvider to use Table instead

Author: kosiew

docs/source/user-guide/data-sources.rst

@@ -167,7 +167,9 @@ work with custom table providers from Python libraries such as Delta Lake.
    :py:meth:`~datafusion.context.SessionContext.register_table_provider` is
    deprecated. Use
    :py:meth:`~datafusion.context.SessionContext.register_table` with a
-   :py:class:`~datafusion.TableProvider` instead.
+   :py:class:`~datafusion.Table` instead. The
+   :py:class:`~datafusion.table_provider.TableProvider` compatibility shim continues
+   to work but emits :class:`DeprecationWarning` when used.
 
 On older versions of ``deltalake`` (prior to 0.22) you can use the
 `Arrow DataSet <https://arrow.apache.org/docs/python/generated/pyarrow.dataset.Dataset.html>`_

python/datafusion/__init__.py

@@ -50,7 +50,7 @@
 from .io import read_avro, read_csv, read_json, read_parquet
 from .plan import ExecutionPlan, LogicalPlan
 from .record_batch import RecordBatch, RecordBatchStream
-from .table_provider import TableProvider
+from .table_provider import TableProvider  # Deprecated compatibility shim
 from .user_defined import (
     Accumulator,
     AggregateUDF,

python/datafusion/catalog.py

@@ -20,9 +20,12 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import TYPE_CHECKING, Protocol
+from typing import TYPE_CHECKING, Any, Protocol
+
+import warnings
 
 import datafusion._internal as df_internal
+from datafusion._internal import EXPECTED_PROVIDER_MSG
 from datafusion.utils import _normalize_table_provider
 
 if TYPE_CHECKING:
@@ -136,7 +139,9 @@ def register_table(
         """Register a table or table provider in this schema.
 
         Objects implementing ``__datafusion_table_provider__`` are also supported
-        and treated as :class:`TableProvider` instances.
+        and treated as table provider instances. The deprecated
+        :class:`~datafusion.table_provider.TableProvider` wrapper remains accepted
+        for backwards compatibility.
         """
         provider = _normalize_table_provider(table)
         return self._raw_schema.register_table(name, provider)
@@ -151,31 +156,108 @@ class Database(Schema):
     """See `Schema`."""
 
 
+_InternalRawTable = df_internal.catalog.RawTable
+_InternalTableProvider = df_internal.TableProvider
+
+# Keep in sync with ``datafusion._internal.TableProvider.from_view``.
+_FROM_VIEW_WARN_STACKLEVEL = 2
+
+
 class Table:
-    """DataFusion table."""
+    """DataFusion table or table provider wrapper."""
 
-    def __init__(self, table: df_internal.catalog.RawTable) -> None:
-        """This constructor is not typically called by the end user."""
-        self.table = table
+    __slots__ = ("_table",)
+
+    def __init__(
+        self,
+        table: _InternalRawTable | _InternalTableProvider | Table,
+    ) -> None:
+        """Wrap a low level table or table provider."""
+
+        if isinstance(table, Table):
+            table = table.table
+
+        if not isinstance(table, (_InternalRawTable, _InternalTableProvider)):
+            raise TypeError(EXPECTED_PROVIDER_MSG)
+
+        self._table = table
+
+    def __getattribute__(self, name: str) -> Any:
+        """Restrict provider-specific helpers to compatible tables."""
+
+        if name == "__datafusion_table_provider__":
+            table = object.__getattribute__(self, "_table")
+            if not hasattr(table, "__datafusion_table_provider__"):
+                raise AttributeError(name)
+        return object.__getattribute__(self, name)
 
     def __repr__(self) -> str:
         """Print a string representation of the table."""
-        return self.table.__repr__()
+        return repr(self._table)
 
-    @staticmethod
-    def from_dataset(dataset: pa.dataset.Dataset) -> Table:
-        """Turn a pyarrow Dataset into a Table."""
-        return Table(df_internal.catalog.RawTable.from_dataset(dataset))
+    @property
+    def table(self) -> _InternalRawTable | _InternalTableProvider:
+        """Return the wrapped low level table object."""
+        return self._table
+
+    @classmethod
+    def from_dataset(cls, dataset: pa.dataset.Dataset) -> Table:
+        """Turn a :mod:`pyarrow.dataset` ``Dataset`` into a :class:`Table`."""
+
+        return cls(_InternalRawTable.from_dataset(dataset))
+
+    @classmethod
+    def from_capsule(cls, capsule: Any) -> Table:
+        """Create a :class:`Table` from a PyCapsule exported provider."""
+
+        provider = _InternalTableProvider.from_capsule(capsule)
+        return cls(provider)
+
+    @classmethod
+    def from_dataframe(cls, df: Any) -> Table:
+        """Create a :class:`Table` from tabular data."""
+
+        from datafusion.dataframe import DataFrame as DataFrameWrapper
+
+        dataframe = df if isinstance(df, DataFrameWrapper) else DataFrameWrapper(df)
+        return dataframe.into_view()
+
+    @classmethod
+    def from_view(cls, df: Any) -> Table:
+        """Deprecated helper for constructing tables from views."""
+
+        from datafusion.dataframe import DataFrame as DataFrameWrapper
+
+        if isinstance(df, DataFrameWrapper):
+            df = df.df
+
+        provider = _InternalTableProvider.from_view(df)
+        warnings.warn(
+            "Table.from_view is deprecated; use DataFrame.into_view or "
+            "Table.from_dataframe instead.",
+            category=DeprecationWarning,
+            stacklevel=_FROM_VIEW_WARN_STACKLEVEL,
+        )
+        return cls(provider)
 
     @property
     def schema(self) -> pa.Schema:
         """Returns the schema associated with this table."""
-        return self.table.schema
+        return self._table.schema
 
     @property
     def kind(self) -> str:
         """Returns the kind of table."""
-        return self.table.kind
+        return self._table.kind
+
+    def __datafusion_table_provider__(self) -> Any:
+        """Expose the wrapped provider for FFI integrations."""
+
+        exporter = getattr(self._table, "__datafusion_table_provider__", None)
+        if exporter is None:
+            msg = "Underlying object does not export __datafusion_table_provider__()"
+            raise AttributeError(msg)
+        return exporter()
 
 
 class CatalogProvider(ABC):
@@ -241,7 +323,9 @@ def register_table(  # noqa: B027
         not need to implement this method.
 
         Objects implementing ``__datafusion_table_provider__`` are also supported
-        and treated as :class:`TableProvider` instances.
+        and treated as table provider instances. The deprecated
+        :class:`~datafusion.table_provider.TableProvider` wrapper remains accepted
+        for backwards compatibility.
         """
 
     def deregister_table(self, name: str, cascade: bool) -> None:  # noqa: B027

python/datafusion/context.py

@@ -754,23 +754,25 @@ def register_view(self, name: str, df: DataFrame) -> None:
     def register_table(
         self, name: str, table: Table | TableProvider | TableProviderExportable
     ) -> None:
-        """Register a Table or TableProvider.
+        """Register a :py:class:`~datafusion.Table` with this context.
 
         The registered table can be referenced from SQL statements executed against
         this context.
 
         Plain :py:class:`~datafusion.dataframe.DataFrame` objects are not supported;
         convert them first with :meth:`datafusion.dataframe.DataFrame.into_view` or
-        :meth:`datafusion.TableProvider.from_dataframe`.
+        :meth:`datafusion.Table.from_dataframe`.
 
         Objects implementing ``__datafusion_table_provider__`` are also supported
-        and treated as :py:class:`~datafusion.TableProvider` instances.
+        and treated as table provider instances. The deprecated
+        :py:class:`~datafusion.table_provider.TableProvider` wrapper remains accepted
+        for backwards compatibility.
 
         Args:
             name: Name of the resultant table.
-            table: DataFusion :class:`Table`, :class:`TableProvider`, or any object
-                implementing ``__datafusion_table_provider__`` to add to the session
-                context.
+            table: DataFusion :class:`Table`, deprecated :class:`TableProvider`, or
+                any object implementing ``__datafusion_table_provider__`` to add to
+                the session context.
         """
         provider = _normalize_table_provider(table)
         self.ctx.register_table(name, provider)
@@ -800,7 +802,7 @@ def register_table_provider(
         Deprecated: use :meth:`register_table` instead.
 
         Objects implementing ``__datafusion_table_provider__`` are also supported
-        and treated as :py:class:`~datafusion.TableProvider` instances.
+        and treated as table provider instances.
         """
         warnings.warn(
             "register_table_provider is deprecated; use register_table",

python/datafusion/dataframe.py

@@ -60,7 +60,7 @@
     import polars as pl
     import pyarrow as pa
 
-    from datafusion.table_provider import TableProvider
+    from datafusion.catalog import Table
 
 from enum import Enum
 
@@ -315,8 +315,8 @@ def __init__(self, df: DataFrameInternal) -> None:
         """
         self.df = df
 
-    def into_view(self) -> TableProvider:
-        """Convert ``DataFrame`` into a ``TableProvider`` view for registration.
+    def into_view(self) -> Table:
+        """Convert ``DataFrame`` into a :class:`~datafusion.Table` for registration.
 
         This is the preferred way to obtain a view for
         :py:meth:`~datafusion.context.SessionContext.register_table` for several reasons:
@@ -325,13 +325,13 @@ def into_view(self) -> TableProvider:
            ``DataFrame.into_view()`` method without intermediate delegations.
         2. **Clear semantics**: The ``into_`` prefix follows Rust conventions,
            indicating conversion from one type to another.
-        3. **Canonical method**: Other approaches like ``TableProvider.from_dataframe``
+        3. **Canonical method**: Other approaches like ``Table.from_dataframe``
            delegate to this method internally, making this the single source of truth.
-        4. **Deprecated alternatives**: The older ``TableProvider.from_view`` helper
+        4. **Deprecated alternatives**: The older ``Table.from_view`` helper
            is deprecated and issues warnings when used.
 
-        ``datafusion.TableProvider.from_dataframe`` calls this method under the hood,
-        and the older ``TableProvider.from_view`` helper is deprecated.
+        ``datafusion.Table.from_dataframe`` calls this method under the hood, and the
+        older ``Table.from_view`` helper is deprecated.
 
         The ``DataFrame`` remains valid after conversion, so it can still be used for
         additional queries alongside the returned view.
@@ -345,9 +345,9 @@ def into_view(self) -> TableProvider:
             >>> df.collect()  # The DataFrame is still usable
             >>> ctx.sql("SELECT value FROM values_view").collect()
         """
-        from datafusion.table_provider import TableProvider as _TableProvider
+        from datafusion.catalog import Table as _Table
 
-        return _TableProvider(self.df.into_view())
+        return _Table(self.df.into_view())
 
     def __getitem__(self, key: str | list[str]) -> DataFrame:
         """Return a new :py:class`DataFrame` with the specified column or columns.