refactor(api): group ergonomic API under substrait.dataframe

Move the six new higher-level modules out of the shared substrait
namespace root into a dedicated substrait.dataframe subpackage:

  api.py                -> dataframe/__init__.py
  dtypes.py             -> dataframe/dtypes.py
  expr.py               -> dataframe/expr.py
  frame.py              -> dataframe/frame.py
  functions.py          -> dataframe/functions.py
  extension_relations.py -> dataframe/extension_relations.py

substrait is a PEP 420 namespace package shared with substrait-protobuf /
-antlr / -extensions, so scattering generic top-level names (expr, frame,
functions, ...) at the namespace root risks colliding with sibling
distributions. Grouping them under one owned subpackage gives a single
import surface and matches the existing per-entry-point layout (builders/,
sql/, narwhals/). The name is now consistent with those siblings -- named
for what it is rather than the generic "api".

Entry point becomes `import substrait.dataframe as sub`. Also renames
tests/api -> tests/dataframe and examples/api_example -> dataframe_example,
and updates docstring cross-references.

Per the review discussion in PR #204.

Author: nielspardon

examples/api_example.py examples/dataframe_example.pyexamples/api_example.py renamed to examples/dataframe_example.py

@@ -1,10 +1,10 @@
-"""Example usage of the ergonomic `substrait.api` facade.
+"""Example usage of the ergonomic `substrait.dataframe` facade.
 
 Compare this with `builder_example.py`, which builds the same kinds of plans
 with the lower-level `substrait.builders.*` functions.
 """
 
-import substrait.api as sub
+import substrait.dataframe as sub
 from substrait.utils.display import pretty_print_plan
 
 

examples/narwhals_example.py

@@ -2,8 +2,8 @@
 # construction through Narwhals (`nw.from_native`), so backend-agnostic Narwhals
 # code compiles to a Substrait plan.
 #
-# For building plans directly (without Narwhals), see `api_example.py`, which
-# uses the Substrait-native DataFrame in `substrait.api` / `substrait.frame`.
+# For building plans directly (without Narwhals), see `dataframe_example.py`,
+# which uses the Substrait-native DataFrame in `substrait.dataframe`.
 #
 # /// script
 # dependencies = [

src/substrait/api.py src/substrait/dataframe/__init__.pysrc/substrait/api.py renamed to src/substrait/dataframe/__init__.py

@@ -2,7 +2,7 @@
 
 A single, shallow import that gets you productive::
 
-    import substrait.api as sub
+    import substrait.dataframe as sub
 
     plan = (
         sub.read_named_table("people", {"id": sub.i64, "age": sub.i64, "name": sub.string})
@@ -12,10 +12,16 @@
         .to_plan()
     )
 
-This lives as a *submodule* (``substrait.api``) rather than the package root on
-purpose: ``substrait`` is a PEP 420 namespace package shared with the
-``substrait-protobuf`` distribution, so adding ``substrait/__init__.py`` would
-shadow ``substrait.algebra_pb2`` and friends.
+This is the Substrait-*native* fluent DataFrame/Expr API -- the higher-level
+counterpart to the lower-level ``substrait.builders`` layer, and a sibling to
+the other entry points (``substrait.sql``, ``substrait.narwhals``). It lives in
+its own subpackage rather than at the ``substrait`` package root because
+``substrait`` is a PEP 420 namespace package shared with the
+``substrait-protobuf`` distribution: an ``substrait/__init__.py`` would shadow
+``substrait.algebra_pb2`` and friends, and scattering ``expr`` / ``frame`` /
+... at the shared namespace root would risk colliding with the sibling
+distributions. Grouping them under ``substrait.dataframe`` keeps a single,
+clearly owned import surface.
 
 Everything here is an additive facade over the existing ``substrait.builders``,
 ``substrait.extension_registry`` and ``substrait.proto`` layers, which remain
@@ -44,7 +50,7 @@
 
 # Primitive / no-argument type shortcuts as nullability-aware DataType objects
 # (sub.i64 -> nullable; sub.i64.non_null -> required; sub.i64() still callable).
-from substrait.dtypes import (
+from substrait.dataframe.dtypes import (
     DataType,
     binary,
     boolean,
@@ -59,7 +65,7 @@
     string,
     uuid,
 )
-from substrait.expr import (
+from substrait.dataframe.expr import (
     Expr,
     all_,
     any_,
@@ -78,12 +84,12 @@
     when,
 )
 from substrait.extension_registry import ExtensionRegistry
-from substrait.extension_relations import (
+from substrait.dataframe.extension_relations import (
     ExtensionLeafDetail,
     ExtensionMultiDetail,
     ExtensionSingleDetail,
 )
-from substrait.frame import (
+from substrait.dataframe.frame import (
     DataFrame,
     create_table,
     create_view,
@@ -100,7 +106,7 @@
     read_parquet,
     update_table,
 )
-from substrait.functions import f, functions_for
+from substrait.dataframe.functions import f, functions_for
 
 __all__ = [
     # entry points

src/substrait/dtypes.py src/substrait/dataframe/dtypes.pysrc/substrait/dtypes.py renamed to src/substrait/dataframe/dtypes.py

@@ -5,10 +5,10 @@
 Daft's own native frame). It is a thin, chainable wrapper over the
 ``substrait.builders.plan`` functions: it carries an ``ExtensionRegistry`` so it
 does not have to be threaded through every call, and it takes
-:class:`~substrait.expr.Expr` objects (or bare column names / Python scalars)
-rather than raw ``scalar_function`` invocations::
+:class:`~substrait.dataframe.expr.Expr` objects (or bare column names / Python
+scalars) rather than raw ``scalar_function`` invocations::
 
-    import substrait.api as sub
+    import substrait.dataframe as sub
 
     plan = (
         sub.read_named_table("people", {"id": sub.i64, "age": sub.i64})
@@ -38,7 +38,7 @@
 
 from substrait.builders import plan as _plan
 from substrait.builders import type as _type
-from substrait.expr import Expr, Measure, col, lit
+from substrait.dataframe.expr import Expr, Measure, col, lit
 from substrait.extension_registry import ExtensionRegistry
 from substrait.type_inference import infer_plan_schema, reference_subtrees
 
@@ -204,7 +204,7 @@ def f(self):
         """
         cached = getattr(self, "_functions_ns", None)
         if cached is None:
-            from substrait.functions import functions_for
+            from substrait.dataframe.functions import functions_for
 
             cached = functions_for(self._registry)
             self._functions_ns = cached
@@ -485,7 +485,7 @@ def extension(self, detail: Any) -> "DataFrame":
         """Apply a custom single-input relation (ExtensionSingleRel).
 
         ``detail`` is an
-        :class:`~substrait.extension_relations.ExtensionSingleDetail` (its
+        :class:`~substrait.dataframe.extension_relations.ExtensionSingleDetail` (its
         ``derive_schema`` defines the output) or a raw ``google.protobuf.Any``
         (the input schema is then assumed to pass through). Register the detail
         class via ``ExtensionRegistry.register_extension_relation`` for schema
@@ -498,7 +498,7 @@ def extension_multi(
     ) -> "DataFrame":
         """A custom multi-input relation (ExtensionMultiRel) over this frame and
         ``others``; ``detail`` is an
-        :class:`~substrait.extension_relations.ExtensionMultiDetail`."""
+        :class:`~substrait.dataframe.extension_relations.ExtensionMultiDetail`."""
         inputs = [self._plan, *(o._plan for o in others)]
         return self._next(_plan.extension_multi(inputs, detail))
 
@@ -754,7 +754,7 @@ def extension_leaf(
     """Start a DataFrame from a custom leaf relation (ExtensionLeafRel).
 
     ``detail`` is an
-    :class:`~substrait.extension_relations.ExtensionLeafDetail`; its
+    :class:`~substrait.dataframe.extension_relations.ExtensionLeafDetail`; its
     ``derive_schema`` defines the source's output columns.
     """
     return DataFrame(_plan.extension_leaf(detail), registry)

src/substrait/expr.py src/substrait/dataframe/expr.pysrc/substrait/expr.py renamed to src/substrait/dataframe/expr.py

@@ -4,15 +4,16 @@
 extensions -- scalar, aggregate and window -- so anything the specification
 ships is reachable by name and hides the extension-URN / signature plumbing::
 
-    import substrait.api as sub
+    import substrait.dataframe as sub
 
     sub.f.sum(sub.col("amount"))
     sub.f.substring(sub.col("name"), 1, 3)
     sub.f.coalesce(sub.col("a"), sub.col("b"))
     sub.f.row_number()
 
-Each helper returns an :class:`~substrait.expr.Expr`. The namespace is built
-lazily on first attribute access from :func:`substrait.frame.default_registry`,
+Each helper returns an :class:`~substrait.dataframe.expr.Expr`. The namespace is
+built lazily on first attribute access from
+:func:`substrait.dataframe.frame.default_registry`,
 and supports ``dir(sub.f)`` for discovery/tab-completion.
 
 Some function names appear in more than one extension (e.g. ``add`` in
@@ -40,7 +41,7 @@
     scalar_function,
     window_function,
 )
-from substrait.expr import Expr
+from substrait.dataframe.expr import Expr
 from substrait.extension_registry.function_entry import FunctionType
 from substrait.type_inference import infer_extended_expression_schema
 
@@ -141,7 +142,7 @@ def _ensure(self) -> dict:
         if self._fns is None:
             registry = self._registry
             if registry is None:
-                from substrait.frame import default_registry
+                from substrait.dataframe.frame import default_registry
 
                 registry = default_registry()
             object.__setattr__(self, "_fns", _build_functions(registry))

src/substrait/extension_relations.py …bstrait/dataframe/extension_relations.pysrc/substrait/extension_relations.py renamed to src/substrait/dataframe/extension_relations.py src/substrait/extension_relations.py renamed to src/substrait/dataframe/extension_relations.py

@@ -53,7 +53,7 @@ def register_extension_relation(self, detail_cls) -> None:
         Enables schema inference for ``ExtensionLeaf/Single/MultiRel`` built with
         an instance of ``detail_cls``: inference reconstructs the detail from the
         plan's ``Any`` and calls its ``derive_schema``. See
-        :mod:`substrait.extension_relations`. Registration is process-global
+        :mod:`substrait.dataframe.extension_relations`. Registration is process-global
         (type_urls are globally unique), so inference works on any plan.
         """
         from substrait.type_inference import register_extension_relation

src/substrait/frame.py src/substrait/dataframe/frame.pysrc/substrait/frame.py renamed to src/substrait/dataframe/frame.py

@@ -5,12 +5,13 @@
 hooks (``__narwhals_lazyframe__`` / ``__narwhals_namespace__``) and translating
 Narwhals calls into Substrait plan builders.
 
-It is distinct from :mod:`substrait.frame`, which is the Substrait-*native*
-fluent DataFrame you can call directly without Narwhals. This layer sits on top
-of that native machinery; the two compose rather than compete.
+It is distinct from :mod:`substrait.dataframe.frame`, which is the
+Substrait-*native* fluent DataFrame you can call directly without Narwhals. This
+layer sits on top of that native machinery; the two compose rather than compete.
 
 Status: experimental / minimal -- it currently implements only a subset of the
-Narwhals compliant protocol, to be built out on top of :mod:`substrait.frame`.
+Narwhals compliant protocol, to be built out on top of
+:mod:`substrait.dataframe.frame`.
 """
 
 from typing import Iterable, Union
@@ -24,7 +25,7 @@ class DataFrame:
     """Narwhals-compliant wrapper around a Substrait plan.
 
     Presents as a Narwhals ``LazyFrame`` backend. For direct, non-Narwhals plan
-    building use :class:`substrait.frame.DataFrame` instead.
+    building use :class:`substrait.dataframe.frame.DataFrame` instead.
     """
 
     def __init__(self, plan):