Merge pull request #51 from edwinvehmaanpera/update-how-to-do-nothing

Update tutorial to reflect new cookiecutter template and Polars version

Author: MarcoGorelli

docs/abs.md

@@ -15,10 +15,10 @@ we did for `noop`, we'll just change the names. Please add this to
 `minimal_plugin/__init__.py`, right below the definition of `noop`:
 ```python
 def abs_i64(expr: IntoExpr) -> pl.Expr:
-    return register_plugin(
+    return register_plugin_function(
         args=[expr],
-        lib=lib,
-        symbol="abs_i64",
+        plugin_path=LIB,
+        function_name="abs_i64",
         is_elementwise=True,
     )
 ```
@@ -90,10 +90,10 @@ First, add the following definition to `minimal_plugin/__init__.py`:
 
 ```python
 def abs_numeric(expr: IntoExpr) -> pl.Expr:
-    return register_plugin(
+    return register_plugin_function(
         args=[expr],
-        lib=lib,
-        symbol="abs_numeric",
+        plugin_path=LIB,
+        function_name="abs_numeric",
         is_elementwise=True,
     )
 ```

docs/aggregate.md

@@ -19,10 +19,10 @@ Nothing fancy here:
 
 ```python
 def vertical_weighted_mean(values: IntoExpr, weights: IntoExpr) -> pl.Expr:
-    return register_plugin(
+    return register_plugin_function(
         args=[values, weights],
-        lib=lib,
-        symbol="vertical_weighted_mean",
+        plugin_path=LIB,
+        function_name="vertical_weighted_mean",
         is_elementwise=False,
         returns_scalar=True,
     )

docs/arguments.md

@@ -17,10 +17,10 @@ following:
 
 ```python
 def add_suffix(expr: IntoExpr, *, suffix: str) -> pl.Expr:
-    return register_plugin(
+    return register_plugin_function(
         args=[expr],
-        lib=lib,
-        symbol="add_suffix",
+        plugin_path=LIB,
+        function_name="add_suffix",
         is_elementwise=True,
         kwargs={"suffix": suffix},
     )

docs/cum_sum.md

@@ -16,10 +16,10 @@ We're going to implement `cum_sum`.
 Add this to `minimal_plugin/__init__.py`:
 ```python
 def cum_sum(expr: IntoExpr) -> pl.Expr:
-    return register_plugin(
+    return register_plugin_function(
         args=[expr],
-        lib=lib,
-        symbol="cum_sum",
+        plugin_path=LIB,
+        function_name="cum_sum",
         is_elementwise=False,
     )
 ```

docs/life_pt1.md

@@ -42,8 +42,7 @@ from typing import Iterable, Any
 
 import polars as pl
 from polars._typing import IntoExpr
-
-from game_of_life.utils import register_plugin
+from polars.plugins import register_plugin_function
 
 
 # Parse a board from a file or stdin
@@ -161,10 +160,10 @@ def life_step(left: IntoExpr, mid: IntoExpr, right: IntoExpr) -> pl.Expr:
     the same column names as the original data frame, so the resulting df will
     have the same shape. See how this is done in the `step(df, n)` function.
     """
-    return register_plugin(
+    return register_plugin_function(
         args=[left, mid, right],
-        lib=lib,
-        symbol="life_step",
+        plugin_path=LIB,
+        function_name="life_step",
         is_elementwise=False,
     )
 ```

docs/lists.md

@@ -42,10 +42,10 @@ On the Python side, this'll be similar to `sum_i64`:
 
 ```python
 def weighted_mean(expr: IntoExpr, weights: IntoExpr) -> pl.Expr:
-    return register_plugin(
+    return register_plugin_function(
         args=[expr, weights],
-        lib=lib,
-        symbol="weighted_mean",
+        plugin_path=LIB,
+        function_name="weighted_mean",
         is_elementwise=True,
     )
 ```

docs/lists_in_lists_out.md

@@ -84,8 +84,8 @@ To finish this off, the Python side will be a bog-standard:
 
 ```python
 def non_zero_indices(expr: IntoExpr) -> pl.Expr:
-    return register_plugin(
-        args=[expr], lib=lib, symbol="non_zero_indices", is_elementwise=True
+    return register_plugin_function(
+        args=[expr], plugin_path=LIB, function_name="non_zero_indices", is_elementwise=True
     )
 ```
 

docs/lost_in_space.md

@@ -48,8 +48,8 @@ We'll start easy by dealing with the Python side. Add the following to `minimal_
 
 ```python
 def reverse_geocode(lat: IntoExpr, long: IntoExpr) -> pl.Expr:
-    return register_plugin(
-        args=[lat, long], lib=lib, symbol="reverse_geocode", is_elementwise=True
+    return register_plugin_function(
+        args=[lat, long], plugin_path=LIB, function_name="reverse_geocode", is_elementwise=True
     )
 ```
 

docs/noop.md

@@ -13,13 +13,18 @@ should look a bit like the following:
 ├── Cargo.toml
 ├── minimal_plugin
 │   ├── __init__.py
-│   └── utils.py
+│   └── typing.py
 ├── pyproject.toml
-└── src
-    ├── expressions.rs
-    ├── lib.rs
-    └── utils.rs
+├── run.py
+├── src
+│   ├── expressions.rs
+│   └── lib.rs
+└── tests
 ```
+The cookiecutter command you ran earlier set up a Polars plugin project with a 
+sample function called `pig_latinnify` already implemented. The [Polars Plugins Cookiecutter](https://github.com/MarcoGorelli/cookiecutter-polars-plugins) 
+helps you quickly start a Polars plugin project, skipping the boilerplate setup. 
+Check it out for more details!
 
   [Prerequisites]: ../prerequisites/
 
@@ -31,22 +36,20 @@ Start by adding the following to `minimal_plugin/__init__.py`:
 
 ```python
 def noop(expr: IntoExpr) -> pl.Expr:
-    return register_plugin(
+    return register_plugin_function(
         args=[expr],
-        lib=lib,
-        symbol="noop",
+        plugin_path=LIB,
+        function_name="noop",
         is_elementwise=True,
     )
 ```
 Let's go through this line-by-line:
 
 - when we compile Rust, it generates a Shared Object file.
-  The `lib` variable holds its filepath;
+  The `LIB` variable holds its filepath;
 - We'll cover `is_elementwise` in [Yes we SCAN], for now don't pay attention to it;
-- We use the utility function `register_plugin`, provided to us by the cookiecutter.
-  Polars actually has a public [register_plugin_function](https://docs.pola.rs/py-polars/html/reference/plugins.html#polars.plugins.register_plugin_function) utility for this, but it was only introduced in
-  Polars 0.20.16. The `register_plugin` function we introduce here handles backwards-compatibility
-  until Polars 0.20.6, so we use that in this tutorial.
+- We use the Polars utility function [register_plugin_function](https://docs.pola.rs/py-polars/html/reference/plugins.html#polars.plugins.register_plugin_function) to extend its functionality with our own.
+  
 
 Note that string literals are parsed as expressions, so that if somebody
 calls `noop('a')`, it gets interpreted as `noop(pl.col('a'))`.
@@ -103,9 +106,9 @@ and return a (cheap!) clone of it.
 
 ## Putting it all together
 
-Right, does this all work? Let's make a Python file `run.py` with which to
-test it out. We'll just make a toy dataframe and apply `noop`
-to each column!
+Right, does this all work? Let's edit the Python file `run.py`, 
+which we will use for testing. We'll just make a toy dataframe 
+and apply `noop` to each column!
 ```python
 import polars as pl
 import minimal_plugin as mp
@@ -118,22 +121,6 @@ df = pl.DataFrame({
 print(df.with_columns(mp.noop(pl.all()).name.suffix('_noop')))
 ```
 
-Your working directory should now look a bit like this:
-
-```
-.
-├── Cargo.toml
-├── minimal_plugin
-│   ├── __init__.py
-│   └── utils.py
-├── pyproject.toml
-├── run.py
-└── src
-    ├── expressions.rs
-    ├── lib.rs
-    └── utils.rs
-```
-
 Let's compile! Please run `maturin develop` (or `maturin develop --release` if benchmarking).
 You'll need to do this every time you change any of your Rust code.
 It may take a while the first time, but subsequent executions will

docs/prerequisites.md

@@ -45,7 +45,7 @@ Please navigate to it with `cd minimal_plugin`.
 
 Next, [create a Python3.8+ virtual environment](https://docs.python.org/3/library/venv.html), and install:
 
-- `polars>=0.20.0`
+- `polars>=1.3.0`
 - `maturin>=1.4.0`
 
 Finally, you'll also need to [install Rust](https://rustup.rs/).