chore: add an example of deferred literal inputs

ibis-project · Aug 23, 2024 · 3bfc4f6 · 3bfc4f6
1 parent 9868380
commit 3bfc4f6
Showing 1 changed file with 27 additions and 0 deletions.
diff --git a/ibis/expr/types/generic.py b/ibis/expr/types/generic.py
@@ -2481,6 +2481,33 @@ def literal(value: Any, type: dt.DataType | str | None = None) -> Scalar:
     Traceback (most recent call last):
       ...
     TypeError: Value 'foobar' cannot be safely coerced to int64
+
+    Literals can also be used in a deferred context.
+
+    Here's an example of constructing a table of a column's type repeated for
+    every row:
+
+    >>> from ibis import _, selectors as s
+    >>> ibis.options.interactive = True
+    >>> t = ibis.examples.penguins.fetch()
+    >>> t.select(s.across(s.all(), ibis.literal(_.type(), type=str).name(_.get_name())))
+    ┏━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━┓
+    ┃ species ┃ island ┃ bill_length_mm ┃ bill_depth_mm ┃ flipper_length_mm ┃ … ┃
+    ┡━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━┩
+    │ string  │ string │ string         │ string        │ string            │ … │
+    ├─────────┼────────┼────────────────┼───────────────┼───────────────────┼───┤
+    │ string  │ string │ float64        │ float64       │ int64             │ … │
+    │ string  │ string │ float64        │ float64       │ int64             │ … │
+    │ string  │ string │ float64        │ float64       │ int64             │ … │
+    │ string  │ string │ float64        │ float64       │ int64             │ … │
+    │ string  │ string │ float64        │ float64       │ int64             │ … │
+    │ string  │ string │ float64        │ float64       │ int64             │ … │
+    │ string  │ string │ float64        │ float64       │ int64             │ … │
+    │ string  │ string │ float64        │ float64       │ int64             │ … │
+    │ string  │ string │ float64        │ float64       │ int64             │ … │
+    │ string  │ string │ float64        │ float64       │ int64             │ … │
+    │ …       │ …      │ …              │ …             │ …                 │ … │
+    └─────────┴────────┴────────────────┴───────────────┴───────────────────┴───┘
     """
     if isinstance(value, Expr):
         node = value.op()