add examples

Author: MarcoGorelli

spec/API_specification/examples/example_3.py

@@ -0,0 +1,20 @@
+from typing import Callable, Any, cast
+
+from dataframe_api import EagerColumn
+
+my_plotting_function: Callable[[Any, Any], Any]
+
+def group_by_and_plot(x_any: Any, y_any: Any, color_any: Any) -> None:
+    x = cast(EagerColumn[Any], x_any.__column_consortium_standard__())
+    y = cast(EagerColumn[Any], y_any.__column_consortium_standard__())
+    color = cast(EagerColumn[Any], color_any.__column_consortium_standard__())
+
+    namespace = x.__column_namespace__()
+
+    df = namespace.dataframe_from_dict({"x": x, "y": y, "color": color})
+
+    agg = df.groupby("color").mean().collect()
+    x = agg.get_column("x").to_array_object(namespace.Float64)
+    y = agg.get_column("y").to_array_object(namespace.Float64)
+
+    my_plotting_function(x, y)

spec/API_specification/examples/example_4.py

@@ -0,0 +1,23 @@
+from typing import Any, cast
+
+from dataframe_api import DataFrame
+
+df: DataFrame
+namespace = df.__dataframe_namespace__()
+col = namespace.col
+
+# You can select columns using column names or expressions
+# the following are all valid
+df.select('a')
+df.select('a', 'b')
+df.select(col('a'))
+df.select((col('a')+1).rename('b'))
+
+# You can filter using expressions
+df = df.filter(col('width') > col('height'))
+
+# EagerColumn can be thought of as a trivial expression.
+# So, filtering using EagerColumn works too, though is less readable
+df_eager = df.collect()
+df_eager = df_eager.filter(df_eager.get_column('width') > df_eager.get_column('height'))
+