From 0880ce40600ab51f6926ec062c650e06846c2537 Mon Sep 17 00:00:00 2001
From: Vincent Arel-Bundock <vincent.arel-bundock@umontreal.ca>
Date: Fri, 25 Oct 2024 19:41:34 -0400
Subject: [PATCH] data frame conversion tutorial: executable code

---
 docs/basics/dataframe_conversion.md | 37 +++++++++++++++++++++--------
 1 file changed, 27 insertions(+), 10 deletions(-)

diff --git a/docs/basics/dataframe_conversion.md b/docs/basics/dataframe_conversion.md
index 8cfab99be..d9d75d42e 100644
--- a/docs/basics/dataframe_conversion.md
+++ b/docs/basics/dataframe_conversion.md
@@ -6,28 +6,45 @@ Imagine that you maintain a library with a function that operates on Pandas data
 
 One solution is to use Narwhals as a thin "DataFrame ingestion" layer, to convert user-supplied data frames to the format that your library uses internally. Since Narwhals is 0-dependency, this is a much more lightweight solution than including all the data frame libraries as dependencies.
 
-For example, this function can ingest any data frame type supported by Narwhals, and convert it to a Pandas DataFrame for internal use:
+To illustrate, we create data frames in various formats:
 
-```python
+```python exec="1" source="above"
 import narwhals as nw
+from narwhals.typing import IntoDataFrame
 
+import duckdb
+import polars as pl
+import pandas as pd
+
+df_polars = pl.DataFrame( {
+        "A": [1, 2, 3, 4, 5],
+        "fruits": ["banana", "banana", "apple", "apple", "banana"],
+        "B": [5, 4, 3, 2, 1],
+        "cars": ["beetle", "audi", "beetle", "beetle", "beetle"],
+} )
+df_pandas = df_polars.to_pandas()
+df_duckdb = duckdb.sql("SELECT * FROM df")
+```
+
+Now, we define a function that can ingest any data frame type supported by Narwhals, and convert it to a Pandas DataFrame for internal use:
 
-def df_to_pandas(df):
+```python exec="1" source="above"
+def df_to_pandas(df: IntoDataFrame) -> pd.DataFrame:
     out = nw.from_native(df)
     out = out.to_pandas()
     return out
-```
-
-Similarly, if your library uses Polars internally, you can convert any user-supplied data frames to Polars format using Narwhals.
 
-```python
-import narwhals as nw
-import polars as pl
+df_to_pandas(df_duckdb)
+```
 
+Similarly, if your library uses Polars internally, you can convert any user-supplied data frame to Polars format using Narwhals.
 
-def df_to_polars(df):
+```python exec="1" source="above"
+def df_to_polars(df: IntoDataFrame) -> pl.DataFrame:
     out = nw.from_native(df)
     out = out.to_arrow()
     return pl.DataFrame(out)
+
+df_to_polars(df_pandas)
 ```