docs: improve .case() and .cases() docstrings

the one set of examples wasn't rendering because interactive mode was off, and it wasn't very useful anyway because it wasn't acting on concrete data.
ibis-project · Oct 4, 2023 · 7fc89e8 · 7fc89e8
1 parent a086134
commit 7fc89e8
Show file tree

Hide file tree

Showing 2 changed files with 78 additions and 19 deletions.
diff --git a/ibis/expr/api.py b/ibis/expr/api.py
@@ -966,6 +966,15 @@ def case() -> bl.SearchedCaseBuilder:
     Use the `.when` method on the resulting object followed by `.end` to create a
     complete case expression.
 
+    Returns
+    -------
+    SearchedCaseBuilder
+        A builder object to use for constructing a case expression.
+
+    See Also
+    --------
+    [`Value.case()`](./expression-generic.qmd#ibis.expr.types.generic.Value.case)
+
     Examples
     --------
     >>> import ibis
@@ -998,11 +1007,6 @@ def case() -> bl.SearchedCaseBuilder:
     │     3 │ *      │     7 │    21.0 │
     │     4 │ /      │     8 │     0.5 │
     └───────┴────────┴───────┴─────────┘
-
-    Returns
-    -------
-    SearchedCaseBuilder
-        A builder object to use for constructing a case expression.
     """
     return bl.SearchedCaseBuilder()
 

diff --git a/ibis/expr/types/generic.py b/ibis/expr/types/generic.py
@@ -703,29 +703,78 @@ def case(self) -> bl.SimpleCaseBuilder:
         """Create a SimpleCaseBuilder to chain multiple if-else statements.
 
         Add new search expressions with the `.when()` method. These must be
-        comparable with this column expression. Conclude by calling `.end()`
+        comparable with this column expression. Conclude by calling `.end()`.
 
         Returns
         -------
         SimpleCaseBuilder
             A case builder
 
+        See Also
+        --------
+        [`Value.substitute()`](./expression-generic.qmd#ibis.expr.types.generic.Value.substitute)
+        [`ibis.cases()`](./expression-generic.qmd#ibis.expr.types.generic.Value.cases)
+        [`ibis.case()`](./expression-generic.qmd#ibis.case)
+
         Examples
         --------
         >>> import ibis
-        >>> t = ibis.table([("string_col", "string")], name="t")
-        >>> expr = t.string_col
-        >>> case_expr = (
-        ...     expr.case()
-        ...     .when("a", "an a")
-        ...     .when("b", "a b")
-        ...     .else_("null or (not a and not b)")
-        ...     .end()
-        ... )
-        >>> case_expr
-        r0 := UnboundTable: t
-          string_col string
-        SimpleCase(...)
+        >>> ibis.options.interactive = True
+        >>> x = ibis.examples.penguins.fetch().head(5)["sex"]
+        >>> x
+        ┏━━━━━━━━┓
+        ┃ sex    ┃
+        ┡━━━━━━━━┩
+        │ string │
+        ├────────┤
+        │ male   │
+        │ female │
+        │ female │
+        │ NULL   │
+        │ female │
+        └────────┘
+        >>> x.case().when("male", "M").when("female", "F").else_("U").end()
+        ┏━━━━━━━━━━━━━━━━━━━━━━┓
+        ┃ SimpleCase(sex, 'U') ┃
+        ┡━━━━━━━━━━━━━━━━━━━━━━┩
+        │ string               │
+        ├──────────────────────┤
+        │ M                    │
+        │ F                    │
+        │ F                    │
+        │ U                    │
+        │ F                    │
+        └──────────────────────┘
+
+        Cases not given result in the ELSE case
+
+        >>> x.case().when("male", "M").else_("OTHER").end()
+        ┏━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+        ┃ SimpleCase(sex, 'OTHER') ┃
+        ┡━━━━━━━━━━━━━━━━━━━━━━━━━━┩
+        │ string                   │
+        ├──────────────────────────┤
+        │ M                        │
+        │ OTHER                    │
+        │ OTHER                    │
+        │ OTHER                    │
+        │ OTHER                    │
+        └──────────────────────────┘
+
+        If you don't supply an ELSE, then NULL is used
+
+        >>> x.case().when("male", "M").end()
+        ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+        ┃ SimpleCase(sex, Cast(None, string)) ┃
+        ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
+        │ string                              │
+        ├─────────────────────────────────────┤
+        │ M                                   │
+        │ NULL                                │
+        │ NULL                                │
+        │ NULL                                │
+        │ NULL                                │
+        └─────────────────────────────────────┘
         """
         import ibis.expr.builders as bl
 
@@ -750,6 +799,12 @@ def cases(
         Value
             Value expression
 
+        See Also
+        --------
+        [`Value.substitute()`](./expression-generic.qmd#ibis.expr.types.generic.Value.substitute)
+        [`ibis.cases()`](./expression-generic.qmd#ibis.expr.types.generic.Value.cases)
+        [`ibis.case()`](./expression-generic.qmd#ibis.case)
+
         Examples
         --------
         >>> import ibis