docs: update documentation to reflect removal of TableProvider and usage of Table instead

Author: kosiew

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

@@ -152,9 +152,11 @@ as Delta Lake. This will require a recent version of
 .. code-block:: python
 
     from deltalake import DeltaTable
+    from datafusion import Table
 
     delta_table = DeltaTable("path_to_table")
-    ctx.register_table("my_delta_table", delta_table)
+    table = Table.from_capsule(delta_table.__datafusion_table_provider__())
+    ctx.register_table("my_delta_table", table)
     df = ctx.table("my_delta_table")
     df.show()
 
@@ -167,7 +169,7 @@ 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.
 
 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>`_

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

@@ -46,45 +46,40 @@ A complete example can be found in the `examples folder <https://github.com/apac
         }
     }
 
-Once you have this library available, you can instantiate the Rust-backed
-provider directly in Python and register it with the
-:py:meth:`~datafusion.context.SessionContext.register_table` method.
-Objects implementing ``__datafusion_table_provider__`` are accepted as-is, so
-there is no need to build a Python ``TableProvider`` wrapper just to integrate
-with DataFusion.
-
-When you need to register a DataFusion
-:py:class:`~datafusion.dataframe.DataFrame`, call
-:py:meth:`~datafusion.dataframe.DataFrame.into_view` to obtain an in-memory
-view.  This is equivalent to the legacy ``TableProvider.from_dataframe()``
-helper.
+Once you have this library available, you can construct a
+:py:class:`~datafusion.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`.
+Call the provider's ``__datafusion_table_provider__()`` method to obtain the capsule
+before constructing a ``Table``. The ``Table.from_view()`` helper is
+deprecated; instead use ``Table.from_dataframe()`` or ``DataFrame.into_view()``.
 
 .. note::
 
    :py:meth:`~datafusion.context.SessionContext.register_table_provider` is
    deprecated. Use
    :py:meth:`~datafusion.context.SessionContext.register_table` with the
-   provider instance or view returned by
-   :py:meth:`~datafusion.dataframe.DataFrame.into_view` instead.
+   resulting :py:class:`~datafusion.Table` instead.
 
 .. code-block:: python
 
-    from datafusion import SessionContext
+    from datafusion import SessionContext, Table
 
     ctx = SessionContext()
     provider = MyTableProvider()
 
+    capsule = provider.__datafusion_table_provider__()
+    capsule_table = Table.from_capsule(capsule)
+
     df = ctx.from_pydict({"a": [1]})
-    view_provider = df.into_view()
+    view_table = Table.from_dataframe(df)
+    # or: view_table = df.into_view()
 
-    ctx.register_table("provider_table", provider)
-    ctx.register_table("view_table", view_provider)
+    ctx.register_table("capsule_table", capsule_table)
+    ctx.register_table("view_table", view_table)
 
-    ctx.table("provider_table").show()
+    ctx.table("capsule_table").show()
     ctx.table("view_table").show()
 
-The capsule-based helpers remain available for advanced integrations that need
-to manipulate FFI objects explicitly.  ``TableProvider.from_capsule()`` continues
-to wrap an ``FFI_TableProvider`` (and will stay available as a compatibility
-alias if it is renamed in :issue:`1`), while ``TableProvider.from_dataframe()``
-simply forwards to :py:meth:`DataFrame.into_view` for convenience.
+Both ``Table.from_capsule()`` and ``Table.from_dataframe()`` create
+table providers that can be registered with the SessionContext using ``register_table()``.

python/datafusion/__init__.py

@@ -50,7 +50,6 @@
 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 .user_defined import (
     Accumulator,
     AggregateUDF,
@@ -88,7 +87,6 @@
     "SessionContext",
     "Table",
     "TableFunction",
-    "TableProvider",
     "WindowFrame",
     "WindowUDF",
     "catalog",

python/datafusion/catalog.py

@@ -20,15 +20,17 @@
 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:
     import pyarrow as pa
 
-    from datafusion import TableProvider
     from datafusion.context import TableProviderExportable
 
 try:
@@ -131,12 +133,12 @@ def table(self, name: str) -> Table:
         return Table(self._raw_schema.table(name))
 
     def register_table(
-        self, name: str, table: Table | TableProvider | TableProviderExportable
+        self, name: str, table: Table | TableProviderExportable | Any
     ) -> None:
         """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.
         """
         provider = _normalize_table_provider(table)
         return self._raw_schema.register_table(name, provider)
@@ -151,31 +153,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):
@@ -233,15 +312,15 @@ def table(self, name: str) -> Table | None:
         ...
 
     def register_table(  # noqa: B027
-        self, name: str, table: Table | TableProvider | TableProviderExportable
+        self, name: str, table: Table | TableProviderExportable | Any
     ) -> None:
         """Add a table to this schema.
 
         This method is optional. If your schema provides a fixed list of tables, you do
         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.
         """
 
     def deregister_table(self, name: str, cascade: bool) -> None:  # noqa: B027

python/datafusion/context.py

@@ -48,7 +48,6 @@
     import pandas as pd
     import polars as pl  # type: ignore[import]
 
-    from datafusion import TableProvider
     from datafusion.catalog import CatalogProvider, Table
     from datafusion.expr import SortKey
     from datafusion.plan import ExecutionPlan, LogicalPlan
@@ -752,25 +751,24 @@ def register_view(self, name: str, df: DataFrame) -> None:
         self.ctx.register_table(name, view)
 
     def register_table(
-        self, name: str, table: Table | TableProvider | TableProviderExportable
+        self, name: str, table: Table | TableProviderExportable | Any
     ) -> 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.
 
         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` or any object implementing
+                ``__datafusion_table_provider__`` to add to the session context.
         """
         provider = _normalize_table_provider(table)
         self.ctx.register_table(name, provider)
@@ -793,14 +791,14 @@ def register_catalog_provider(
             self.ctx.register_catalog_provider(name, provider)
 
     def register_table_provider(
-        self, name: str, provider: Table | TableProvider | TableProviderExportable
+        self, name: str, provider: Table | TableProviderExportable | Any
     ) -> None:
         """Register a 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.