docs: add docs for str functions

docs/api.yml

@@ -96,16 +96,11 @@ sidebar:
       - "api-reference/expressions/typeof"
       - "api-reference/expressions/when"
       # - "api-reference/expressions/datetime"
-      # - "api-reference/expressions/str/lower"
-      # - "api-reference/expressions/str/upper"
-      # - "api-reference/expressions/str/endswith"
-      # - "api-reference/expressions/str/concat"
-      # - "api-reference/expressions/str/parse"
-      # - "api-reference/expressions/str/len"
-      # - "api-reference/expressions/str/contains"
-      # - "api-reference/expressions/list.len"
-      # - "api-reference/expressions/list.hasnull"
-      # - "api-reference/expressions/list.contains"
+      # - "api-reference/expressions/from_epoch"
+
+  - slug: "api-reference/expressions/dt"
+    title: "Datetime Expressions"
+    pages:
       # - "api-reference/expressions/dt.since"
       # - "api-reference/expressions/dt.since_epoch"
       # - "api-reference/expressions/dt.year"
@@ -115,14 +110,13 @@ sidebar:
       # - "api-reference/expressions/dt.minute"
       # - "api-reference/expressions/dt.second"
       # - "api-reference/expressions/dt.strftime"
-      # - "api-reference/expressions/struct"
-      # - "api-reference/expressions/from_epoch"
-      # - "api-reference/expressions/struct.get"
 
-  - slug: "api-reference/expressions/str"
-    title: "String Expressions"
+  - slug: "api-reference/expressions/list"
+    title: "List Expressions"
     pages:
-      - "api-reference/expressions/str/startswith"
+      # - "api-reference/expressions/list.len"
+      # - "api-reference/expressions/list.hasnull"
+      # - "api-reference/expressions/list.contains"
 
   - slug: "api-reference/expressions/num"
     title: "Num Expressions"
@@ -132,6 +126,26 @@ sidebar:
       - "api-reference/expressions/num/floor"
       - "api-reference/expressions/num/round"
 
+  - slug: "api-reference/expressions/str"
+    title: "String Expressions"
+    pages:
+      - "api-reference/expressions/str/concat"
+      - "api-reference/expressions/str/contains"
+      - "api-reference/expressions/str/endswith"
+      - "api-reference/expressions/str/len"
+      - "api-reference/expressions/str/lower"
+      - "api-reference/expressions/str/parse"
+      - "api-reference/expressions/str/startswith"
+      - "api-reference/expressions/str/strptime"
+      - "api-reference/expressions/str/upper"
+
+  - slug: "api-reference/expressions/struct"
+    title: "Struct Expressions"
+    pages:
+      - "api-reference/expressions/struct/get"
+      # - "api-reference/expressions/struct/init"
+
+
   - slug: "api-reference/decorators"
     title: "Decorators"
     pages:

docs/examples/api-reference/expressions/basic.py

@@ -2,25 +2,6 @@
 from typing import Optional
 import pandas as pd
 
-def test_num_abs():
-    # docsnip expr_num_abs
-    from fennel.expr import col
-
-    # docsnip-highlight next-line
-    expr = col("x").num.abs()
-    assert expr.typeof(schema={"x": int}) == int
-    assert expr.typeof(schema={"x": Optional[int]}) == Optional[int]
-    assert expr.typeof(schema={"x": float}) == float
-    assert expr.typeof(schema={"x": Optional[float]}) == Optional[float]
-
-    # can be evaluated with a dataframe
-    df = pd.DataFrame({"x": pd.Series([1, -2, None], dtype=pd.Int64Dtype())})
-    assert expr.eval(df, schema={"x": Optional[int]}).tolist() == [1, 2, None]
-
-    with pytest.raises(ValueError):
-        expr.typeof(schema={"x": str})
-    # /docsnip
-
 def test_unary_not():
     # docsnip expr_unary_not
     from fennel.expr import lit
@@ -63,7 +44,7 @@ def test_col():
 
 def test_when_then():
     # docsnip expr_when_then
-    from fennel.expr import when, col
+    from fennel.expr import when, col, InvalidExprException
 
     # docsnip-highlight next-line
     expr = when(col("x")).then(1).otherwise(0)
@@ -84,8 +65,8 @@ def test_when_then():
     assert expr.eval(df, schema={"x": bool}).tolist() == [1, 0, 1]
 
     # not valid if only when is provided
-    expr = when(col("x"))
-    with pytest.raises(ValueError):
+    with pytest.raises(InvalidExprException):
+        expr = when(col("x"))
         expr.typeof(schema={"x": bool})
 
     # if otherwise is not provided, it defaults to None
@@ -114,7 +95,7 @@ def test_isnull():
     import pandas as pd
 
     df = pd.DataFrame({"x": pd.Series([1, 2, None], dtype=pd.Int64Dtype())})
-    assert expr.eval(df, schema={"x": Optional[int]}).tolist() == [True, False, False]
+    assert expr.eval(df, schema={"x": Optional[int]}).tolist() == [False, False, True]
     # /docsnip
 
 def test_fillnull():
@@ -153,5 +134,5 @@ def test_lit():
     # can be evaluated with a dataframe
     expr = col("x") + lit(1)
     df = pd.DataFrame({"x": pd.Series([1, 2, None], dtype=pd.Int64Dtype())})
-    assert expr.eval(df, schema={"x": Optional[int]}).tolist() == [2, 3, None]
+    assert expr.eval(df, schema={"x": Optional[int]}).tolist() == [2, 3, pd.NA]
     # /docsnip

docs/examples/api-reference/expressions/binary.py

@@ -14,14 +14,14 @@ def test_typeof():
 
     df = pd.DataFrame({"x": [1, 2, None]})
     expr = lit(1) + col("x")
-    assert expr.eval(df, schema={"x": Optional[int]}).tolist() == [2, 3, None]
+    assert expr.eval(df, schema={"x": Optional[int]}).tolist() == [2, 3, pd.NA]
 
     expr = lit(1) - col("x")
-    assert expr.eval(df, schema={"x": Optional[int]}).tolist() == [0, -1, None]
+    assert expr.eval(df, schema={"x": Optional[int]}).tolist() == [0, -1, pd.NA]
 
     expr = lit(1) * col("x")
-    assert expr.eval(df, schema={"x": Optional[int]}).tolist() == [1, 2, None]
+    assert expr.eval(df, schema={"x": Optional[int]}).tolist() == [1, 2, pd.NA]
 
     expr = lit(1) / col("x")
-    assert expr.eval(df, schema={"x": Optional[int]}).tolist() == [1, 0.5, None]
+    assert expr.eval(df, schema={"x": Optional[int]}).tolist() == [1, 0.5, pd.NA]
     # /docsnip

docs/examples/api-reference/expressions/eval.py

@@ -46,7 +46,7 @@ def test_eval():
 
     # dataframe doesn't have the required column even though schema is provided
     df = pd.DataFrame({"other": [1, 2, 3]})
-    with pytest.raises(KeyError):
+    with pytest.raises(Exception):
         expr.eval(df, schema={"amount": int})
 
     # /docsnip

docs/examples/api-reference/expressions/num.py

@@ -60,4 +60,45 @@ def test_ceil():
 
     with pytest.raises(ValueError):
         expr.typeof(schema={"x": str})
-    # /docsnip
+    # /docsnip
+
+
+def test_round():
+    # docsnip round
+    from fennel.expr import col
+
+    # docsnip-highlight next-line
+    expr = col("x").round() # equivalent to col("x").num.round()
+
+    assert expr.typeof(schema={"x": int}) == int
+    assert expr.typeof(schema={"x": Optional[int]}) == Optional[int]
+    assert expr.typeof(schema={"x": float}) == int
+    assert expr.typeof(schema={"x": Optional[float]}) == Optional[int]
+
+    # can be evaluated with a dataframe
+    df = pd.DataFrame({"x": pd.Series([1.1, -2.3, None])})
+    assert expr.eval(df, schema={"x": Optional[float]}).tolist() == [1, -2, pd.NA]
+
+    # can also explicit specify the number of decimals
+    # docsnip-highlight next-line
+    expr = col("x").round(1)
+
+    assert expr.typeof(schema={"x": int}) == float
+    assert expr.typeof(schema={"x": Optional[int]}) == Optional[float]
+    assert expr.typeof(schema={"x": float}) == float
+    assert expr.typeof(schema={"x": Optional[float]}) == Optional[float]
+
+    df = pd.DataFrame({"x": pd.Series([1.12, -2.37, None])})
+    assert expr.eval(df, schema={"x": Optional[float]}).tolist() == [1.1, -2.4, pd.NA]
+
+    df = pd.DataFrame({"x": pd.Series([1, -2, None])})
+    assert expr.eval(df, schema={"x": Optional[float]}).tolist() == [1.0, -2.0, pd.NA]
+
+    # /docsnip
+
+    # invalid number of decimals
+    with pytest.raises(Exception):
+        expr = col("x").round(-1)
+
+    with pytest.raises(Exception):
+        expr = col("x").round(1.1)