Update documentation

Author: timsaucer

python/datafusion/catalog.py

@@ -130,13 +130,11 @@ def table(self, name: str) -> Table:
         return Table(self._raw_schema.table(name))
 
     def register_table(
-        self, name: str, table: Table | TableProviderExportable | Any
+        self,
+        name: str,
+        table: Table | TableProviderExportable | DataFrame | pa.dataset.Dataset,
     ) -> None:
-        """Register a table or table provider in this schema.
-
-        Objects implementing ``__datafusion_table_provider__`` are also supported
-        and treated as table provider instances.
-        """
+        """Register a table in this schema."""
         return self._raw_schema.register_table(name, table)
 
     def deregister_table(self, name: str) -> None:
@@ -155,8 +153,7 @@ class Table:
     __slots__ = ("_inner",)
 
     def __init__(
-        self,
-        table: DataFrame | TableProviderExportable | pa.dataset.Dataset,
+        self, table: Table | TableProviderExportable | DataFrame | pa.dataset.Dataset
     ) -> None:
         """Wrap a low level table or table provider."""
         self._inner = df_internal.catalog.RawTable(table)

python/datafusion/context.py

@@ -750,7 +750,9 @@ def register_view(self, name: str, df: DataFrame) -> None:
         self.ctx.register_table(name, view)
 
     def register_table(
-        self, name: str, table: Table | TableProviderExportable | Any
+        self,
+        name: str,
+        table: Table | TableProviderExportable | DataFrame | pa.dataset.Dataset,
     ) -> None:
         """Register a :py:class:`~datafusion.Table` with this context.
 

src/table.rs

@@ -24,6 +24,9 @@ use crate::dataframe::PyDataFrame;
 use crate::dataset::Dataset;
 use crate::utils::table_provider_from_pycapsule;
 
+/// This struct is used as a common method for all TableProviders,
+/// whether they refer to an FFI provider, an internally known
+/// implementation, a dataset, or a dataframe view.
 #[pyclass(name = "RawTable", module = "datafusion.catalog", subclass)]
 #[derive(Clone)]
 pub struct PyTable {
@@ -38,6 +41,15 @@ impl PyTable {
 
 #[pymethods]
 impl PyTable {
+    /// Instantiate from any Python object that supports any of the table
+    /// types. We do not know a priori when using this method if the object
+    /// will be passed a wrapped or raw class. Here we handle all of the
+    /// following object types:
+    ///
+    /// - PyTable (essentially a clone operation), but either raw or wrapped
+    /// - DataFrame, either raw or wrapped
+    /// - FFI Table Providers via PyCapsule
+    /// - PyArrow Dataset objects
     #[new]
     pub fn new(obj: &Bound<'_, PyAny>) -> PyResult<Self> {
         if let Ok(py_table) = obj.extract::<PyTable>() {