Fix Expressions API docs to be flat namespace

daft/__init__.py

@@ -66,7 +66,7 @@ def get_build_type() -> str:
 from daft.daft import ImageFormat, ImageMode, ResourceRequest
 from daft.dataframe import DataFrame
 from daft.datatype import DataType, TimeUnit
-from daft.expressions import col, lit
+from daft.expressions import Expression, col, lit
 from daft.io import from_glob_path, read_csv, read_iceberg, read_json, read_parquet
 from daft.series import Series
 from daft.udf import udf
@@ -85,6 +85,7 @@ def get_build_type() -> str:
     "read_parquet",
     "read_iceberg",
     "DataFrame",
+    "Expression",
     "col",
     "DataType",
     "ImageMode",

daft/expressions/expressions.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import builtins
+import os
 import sys
 from datetime import date, datetime
 from typing import TYPE_CHECKING, Callable, Iterable, Iterator, TypeVar, overload
@@ -28,6 +29,32 @@
     from daft.io import IOConfig
 
 
+# Implementation taken from: https://github.com/pola-rs/polars/blob/main/py-polars/polars/utils/various.py#L388-L399
+# This allows Sphinx to correctly work against our "namespaced" accessor functions by overriding @property to
+# return a class instance of the namespace instead of a property object.
+accessor_namespace_property: type[property] = property
+if os.getenv("DAFT_SPHINX_BUILD") == "1":
+    from typing import Any
+
+    # when building docs (with Sphinx) we need access to the functions
+    # associated with the namespaces from the class, as we don't have
+    # an instance; @sphinx_accessor is a @property that allows this.
+    NS = TypeVar("NS")
+
+    class sphinx_accessor(property):  # noqa: D101
+        def __get__(  # type: ignore[override]
+            self,
+            instance: Any,
+            cls: type[NS],
+        ) -> NS:
+            try:
+                return self.fget(instance if isinstance(instance, cls) else cls)  # type: ignore[misc]
+            except (AttributeError, ImportError):
+                return self  # type: ignore[return-value]
+
+    accessor_namespace_property = sphinx_accessor
+
+
 def lit(value: object) -> Expression:
     """Creates an Expression representing a column with every value set to the provided value
 
@@ -72,47 +99,47 @@ def col(name: str) -> Expression:
 
 
 class Expression:
-    _expr: _PyExpr
+    _expr: _PyExpr = None  # type: ignore
 
     def __init__(self) -> None:
         raise NotImplementedError("We do not support creating a Expression via __init__ ")
 
-    @property
+    @accessor_namespace_property
     def str(self) -> ExpressionStringNamespace:
         """Access methods that work on columns of strings"""
         return ExpressionStringNamespace.from_expression(self)
 
-    @property
+    @accessor_namespace_property
     def dt(self) -> ExpressionDatetimeNamespace:
         """Access methods that work on columns of datetimes"""
         return ExpressionDatetimeNamespace.from_expression(self)
 
-    @property
+    @accessor_namespace_property
     def float(self) -> ExpressionFloatNamespace:
         """Access methods that work on columns of floats"""
         return ExpressionFloatNamespace.from_expression(self)
 
-    @property
+    @accessor_namespace_property
     def url(self) -> ExpressionUrlNamespace:
         """Access methods that work on columns of URLs"""
         return ExpressionUrlNamespace.from_expression(self)
 
-    @property
+    @accessor_namespace_property
     def list(self) -> ExpressionListNamespace:
         """Access methods that work on columns of lists"""
         return ExpressionListNamespace.from_expression(self)
 
-    @property
+    @accessor_namespace_property
     def struct(self) -> ExpressionStructNamespace:
         """Access methods that work on columns of structs"""
         return ExpressionStructNamespace.from_expression(self)
 
-    @property
+    @accessor_namespace_property
     def image(self) -> ExpressionImageNamespace:
         """Access methods that work on columns of images"""
         return ExpressionImageNamespace.from_expression(self)
 
-    @property
+    @accessor_namespace_property
     def partitioning(self) -> ExpressionPartitioningNamespace:
         """Access methods that support partitioning operators"""
         return ExpressionPartitioningNamespace.from_expression(self)

docs/source/api_docs/creation.rst

@@ -58,7 +58,7 @@ Data Catalogs
 -------------
 
 Apache Iceberg
-^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~
 
 .. autosummary::
     :nosignatures:

docs/source/api_docs/expressions.rst

@@ -1,19 +1,166 @@
 Expressions
 ===========
 
-.. toctree::
-    :hidden:
-    :maxdepth: 1
-
-    expressions/constructors
-    expressions/generic
-    expressions/logical
-    expressions/numeric
-    expressions/strings
-    expressions/temporal
-    expressions/list
-    expressions/struct
-    expressions/image
-    expressions/partitioning
-    expressions/url
-    expressions/float
+Daft Expressions allow you to express some computation that needs to happen in a DataFrame.
+
+This page provides an overview of all the functionality that is provided by Daft Expressions.
+
+.. currentmodule:: daft
+
+Constructors
+############
+
+.. autosummary::
+   :nosignatures:
+   :toctree: doc_gen/expression_methods
+
+    DataFrame.__getitem__
+
+.. autosummary::
+   :nosignatures:
+   :toctree: doc_gen/expression_methods
+
+    col
+
+.. autosummary::
+   :nosignatures:
+   :toctree: doc_gen/expression_methods
+
+    lit
+
+Generic
+#######
+
+.. autosummary::
+   :nosignatures:
+   :toctree: doc_gen/expression_methods
+
+   Expression.alias
+   Expression.cast
+   Expression.if_else
+   Expression.is_null
+   Expression.not_null
+   Expression.apply
+
+Numeric
+#######
+
+.. autosummary::
+   :nosignatures:
+   :toctree: doc_gen/expression_methods
+
+    Expression.__abs__
+    Expression.__add__
+    Expression.__sub__
+    Expression.__mul__
+    Expression.__truediv__
+    Expression.__mod__
+
+Logical
+#######
+
+.. autosummary::
+   :nosignatures:
+   :toctree: doc_gen/expression_methods
+
+    Expression.__invert__
+    Expression.__and__
+    Expression.__or__
+    Expression.__lt__
+    Expression.__le__
+    Expression.__eq__
+    Expression.__ne__
+    Expression.__gt__
+    Expression.__ge__
+
+Strings
+#######
+
+The following methods are available under the ``expr.str`` attribute.
+
+.. autosummary::
+   :nosignatures:
+   :toctree: doc_gen/expression_methods
+   :template: autosummary/accessor_method.rst
+
+   Expression.str.contains
+   Expression.str.endswith
+   Expression.str.startswith
+   Expression.str.concat
+   Expression.str.length
+   Expression.str.split
+
+Temporal
+########
+
+.. autosummary::
+   :nosignatures:
+   :toctree: doc_gen/expression_methods
+   :template: autosummary/accessor_method.rst
+
+   Expression.dt.date
+   Expression.dt.hour
+   Expression.dt.day
+   Expression.dt.month
+   Expression.dt.year
+   Expression.dt.day_of_week
+
+List
+####
+
+.. autosummary::
+   :nosignatures:
+   :toctree: doc_gen/expression_methods
+   :template: autosummary/accessor_method.rst
+
+   Expression.list.join
+   Expression.list.lengths
+   Expression.list.get
+
+Struct
+######
+
+.. autosummary::
+   :nosignatures:
+   :toctree: doc_gen/expression_methods
+   :template: autosummary/accessor_method.rst
+
+   Expression.struct.get
+
+Image
+#####
+
+.. autosummary::
+   :nosignatures:
+   :toctree: doc_gen/expression_methods
+   :template: autosummary/accessor_method.rst
+
+   Expression.image.decode
+   Expression.image.encode
+   Expression.image.resize
+   Expression.image.crop
+
+Partitioning
+############
+
+.. autosummary::
+   :nosignatures:
+   :toctree: doc_gen/expression_methods
+   :template: autosummary/accessor_method.rst
+
+   Expression.partitioning.days
+   Expression.partitioning.hours
+   Expression.partitioning.months
+   Expression.partitioning.years
+   Expression.partitioning.iceberg_bucket
+   Expression.partitioning.iceberg_truncate
+
+URLs
+####
+
+.. autosummary::
+   :nosignatures:
+   :toctree: doc_gen/expression_methods
+   :template: autosummary/accessor_method.rst
+
+   Expression.url.download