Migrate daft.catalog top-level functions

Author: rchowell

daft/catalog/__init__.py

@@ -8,11 +8,15 @@
 
 **Catalog**
 
-Daft recognizes a default catalog which it will attempt to use when no specific catalog name is provided.
-
 ```python
-# This will hit the default catalog
-daft.read_table("my_db.my_namespace.my_table")
+# without any qualifiers, the default catalog and namespace are used.
+daft.read_table("my_table")
+
+# with a qualified identifier (uses default catalog)
+daft.read_table("my_namespace.my_table")
+
+# with a fully qualified identifier
+daft.read_table("my_catalog.my_namespace.my_table")
 ```
 
 **Named Tables**
@@ -24,11 +28,8 @@
 ```python
 df = daft.from_pydict({"foo": [1, 2, 3]})
 
-# TODO deprecated catalog APIs #3819
-daft.catalog.register_table(
-    "my_table",
-    df,
-)
+# Attach the DataFrame for use across other APIs.
+daft.attach_table(df, "my_table")
 
 # Your table is now accessible from Daft-SQL, or Daft's `read_table`
 df1 = daft.read_table("my_table")
@@ -42,10 +43,7 @@
 
 from abc import ABC, abstractmethod
 from collections.abc import Sequence
-from daft.daft import catalog as native_catalog
 from daft.daft import PyIdentifier, PyTable
-from daft.logical.builder import LogicalPlanBuilder
-
 from daft.dataframe import DataFrame
 
 from typing import TYPE_CHECKING
@@ -65,14 +63,46 @@
     "unregister_catalog",
 ]
 
+
 # TODO deprecated catalog APIs #3819
-unregister_catalog = native_catalog.unregister_catalog
+def unregister_catalog(catalog_name: str | None) -> bool:
+    """Unregisters a catalog from the Daft catalog system.
+
+    DEPRECATED: This is deprecated and will be removed in daft >= 0.5.0; please use `daft.detach_catalog`.
+
+    This function removes a previously registered catalog from the Daft catalog system.
+
+    Args:
+        catalog_name (Optional[str]): The name of the catalog to unregister. If None, the default catalog will be unregistered.
+
+    Returns:
+        bool: True if a catalog was successfully unregistered, False otherwise.
+
+    Example:
+        >>> import daft
+        >>> daft.unregister_catalog("my_catalog")
+        True
+    """
+    from daft.session import detach_catalog
+
+    warnings.warn(
+        "This is deprecated and will be removed in daft >= 0.5.0; please use `daft.detach_catalog`.",
+        category=DeprecationWarning,
+    )
+    try:
+        alias = catalog_name if catalog_name else "default"
+        detach_catalog(alias)
+        return True
+    except Exception:
+        return False
 
 
 # TODO deprecated catalog APIs #3819
 def read_table(name: str) -> DataFrame:
     """Finds a table with the specified name and reads it as a DataFrame.
 
+    DEPRECATED: This is deprecated and will be removed in daft >= 0.5.0; please use `daft.read_table`.
+
     The provided name can be any of the following, and Daft will return them with the following order of priority:
 
     1. Name of a registered dataframe/SQL view (manually registered using `daft.register_table`): `"my_registered_table"`
@@ -85,14 +115,21 @@ def read_table(name: str) -> DataFrame:
     Returns:
         A DataFrame containing the data from the specified table.
     """
-    native_logical_plan_builder = native_catalog.read_table(name)
-    return DataFrame(LogicalPlanBuilder(native_logical_plan_builder))
+    from daft.session import read_table
+
+    warnings.warn(
+        "This is deprecated and will be removed in daft >= 0.5.0; please use `daft.read_table`.",
+        category=DeprecationWarning,
+    )
+    return read_table(name)
 
 
 # TODO deprecated catalog APIs #3819
 def register_table(name: str, dataframe: DataFrame) -> str:
     """Register a DataFrame as a named table.
 
+    DEPRECATED: This is deprecated and will be removed in daft >= 0.5.0; please use `daft.attach_table`.
+
     This function registers a DataFrame as a named table, making it accessible
     via Daft-SQL or Daft's `read_table` function.
 
@@ -108,13 +145,22 @@ def register_table(name: str, dataframe: DataFrame) -> str:
         >>> daft.catalog.register_table("my_table", df)
         >>> daft.read_table("my_table")
     """
-    return native_catalog.register_table(name, dataframe._builder._builder)
+    from daft.session import attach_table
+
+    warnings.warn(
+        "This is deprecated and will be removed in daft >= 0.5.0; please use `daft.attach_table`.",
+        category=DeprecationWarning,
+    )
+    _ = attach_table(dataframe, name)
+    return name
 
 
 # TODO deprecated catalog APIs #3819
 def register_python_catalog(catalog: object, name: str | None = None) -> str:
     """Registers a Python catalog with Daft.
 
+    DEPRECATED: This is deprecated and will be removed in daft >= 0.5.0; please use `daft.attach_catalog`.
+
     Currently supports:
 
     * [PyIceberg Catalogs](https://py.iceberg.apache.org/api/)
@@ -136,7 +182,16 @@ def register_python_catalog(catalog: object, name: str | None = None) -> str:
         >>> daft.catalog.register_python_catalog(catalog, "my_daft_catalog")
 
     """
-    return native_catalog.register_python_catalog(Catalog._from_obj(catalog), name)
+    from daft.session import attach_catalog
+
+    warnings.warn(
+        "This is deprecated and will be removed in daft >= 0.5.0; please use `daft.attach_catalog`.",
+        category=DeprecationWarning,
+    )
+    if name is None:
+        raise ValueError("implicit catalog aliases are not supported")
+    _ = attach_catalog(catalog, name)
+    return name
 
 
 class Catalog(ABC):

daft/daft/catalog.pyi

@@ -1,10 +1,3 @@
-from typing import TYPE_CHECKING
-
-from daft.daft import LogicalPlanBuilder as PyLogicalPlanBuilder
-
-if TYPE_CHECKING:
-    from daft.catalog.python_catalog import PythonCatalog
-
 class PyIdentifier:
     def __init__(self, namespace: tuple[str, ...], name: str): ...
     @staticmethod
@@ -13,8 +6,3 @@ class PyIdentifier:
     def getitem(self, index: int) -> str: ...
     def __len__(self) -> int: ...
     def __repr__(self) -> str: ...
-
-def read_table(name: str) -> PyLogicalPlanBuilder: ...
-def register_table(name: str, plan_builder: PyLogicalPlanBuilder) -> str: ...
-def register_python_catalog(catalog: PythonCatalog, catalog_name: str | None) -> str: ...
-def unregister_catalog(catalog_name: str | None) -> bool: ...

daft/session.py

@@ -65,13 +65,17 @@ def _from_env() -> Session:
     # attach & detach
     ###
 
-    def attach_catalog(self, catalog: object | Catalog, alias: str) -> Catalog:
+    def attach_catalog(self, catalog: object | Catalog, alias: str | None = None) -> Catalog:
         """Attaches an external catalog to this session."""
+        if alias is None:
+            raise ValueError("implicit catalog aliases are not yet supported")
         c = catalog if isinstance(catalog, Catalog) else Catalog._from_obj(catalog)
         return self._session.attach_catalog(c, alias)
 
-    def attach_table(self, table: object | Table, alias: str) -> Table:
+    def attach_table(self, table: object | Table, alias: str | None = None) -> Table:
         """Attaches an external table to this session."""
+        if alias is None:
+            raise ValueError("implicit table aliases are not yet supported")
         t = table if isinstance(table, Table) else Table._from_obj(table)
         return self._session.attach_table(t, alias)
 
@@ -174,12 +178,12 @@ def _session() -> Session:
 ###
 
 
-def attach_catalog(catalog: object | Catalog, alias: str) -> Catalog:
+def attach_catalog(catalog: object | Catalog, alias: str | None = None) -> Catalog:
     """Attaches an external catalog to the current session."""
     return _session().attach_catalog(catalog, alias)
 
 
-def attach_table(table: object | Table, alias: str) -> Table:
+def attach_table(table: object | Table, alias: str | None = None) -> Table:
     """Attaches an external table to the current session."""
     return _session().attach_table(table, alias)