docs(python): Add Excel page to user guide (pola-rs#12055)

Co-authored-by: Liam Brannigan <[email protected]> Co-authored-by: Stijn de Gooijer <[email protected]>
pirr · Oct 27, 2023 · 18d9856 · 18d9856
1 parent 4b2bd83
commit 18d9856
Show file tree

Hide file tree

Showing 4 changed files with 77 additions and 0 deletions.
diff --git a/docs/_build/API_REFERENCE_LINKS.yml b/docs/_build/API_REFERENCE_LINKS.yml
@@ -10,6 +10,8 @@ python:
   hstack: https://pola-rs.github.io/polars/py-polars/html/reference/dataframe/api/polars.DataFrame.hstack.html
   read_csv: https://pola-rs.github.io/polars/py-polars/html/reference/api/polars.read_csv.html
   write_csv: https://pola-rs.github.io/polars/py-polars/html/reference/api/polars.DataFrame.write_csv.html
+  read_excel: https://pola-rs.github.io/polars/py-polars/html/reference/api/polars.read_excel.html
+  write_excel: https://pola-rs.github.io/polars/py-polars/html/reference/api/polars.DataFrame.write_excel.html
   read_json: https://pola-rs.github.io/polars/py-polars/html/reference/api/polars.read_json.html
   write_json: https://pola-rs.github.io/polars/py-polars/html/reference/api/polars.DataFrame.write_json.html
   read_ipc: https://pola-rs.github.io/polars/py-polars/html/reference/api/polars.read_ipc.html

diff --git a/docs/src/python/user-guide/io/excel.py b/docs/src/python/user-guide/io/excel.py
@@ -0,0 +1,26 @@
+# --8<-- [start:setup]
+import polars as pl
+
+# --8<-- [end:setup]
+
+"""
+# --8<-- [start:read]
+df = pl.read_excel("docs/data/path.xlsx")
+# --8<-- [end:read]
+
+# --8<-- [start:read_sheet_name]
+df = pl.read_excel("docs/data/path.xlsx", sheet_name="Sales")
+# --8<-- [end:read_sheet_name]
+"""
+
+# --8<-- [start:write]
+df = pl.DataFrame({"foo": [1, 2, 3], "bar": [None, "bak", "baz"]})
+df.write_excel("docs/data/path.xlsx")
+# --8<-- [end:write]
+
+"""
+# --8<-- [start:write_sheet_name]
+df = pl.DataFrame({"foo": [1, 2, 3], "bar": [None, "bak", "baz"]})
+df.write_excel("docs/data/path.xlsx", worksheet="Sales")
+# --8<-- [end:write_sheet_name]
+"""
diff --git a/docs/user-guide/io/excel.md b/docs/user-guide/io/excel.md
@@ -0,0 +1,48 @@
+# Excel
+
+Polars can read and write to Excel files from Python.
+From a performance perspective, we recommend using other formats if possible, such as Parquet or CSV files.
+
+## Read
+
+Polars does not have a native Excel reader.
+Instead, it uses external libraries to parse Excel files into objects that Polars can parse.
+To read Excel files, we must install either the (default) xls2csv library or one of the alternatives as an additional dependency.
+
+=== ":fontawesome-brands-python: Python"
+
+    ```shell
+    $ pip install xls2csv openpyxl pyxlsb
+    ```
+
+The default Excel reader is xls2csv.
+It is a Python library which parses the Excel file into a CSV file which Polars then reads with the native CSV reader.
+We read an Excel file with `read_excel`:
+
+{{code_block('user-guide/io/excel','read',['read_excel'])}}
+
+We can specify the sheet name to read with the `sheet_name` argument. If we do not specify a sheet name, the first sheet will be read.
+
+{{code_block('user-guide/io/excel','read_sheet_name',['read_excel'])}}
+
+## Write
+
+We need the xlswriter library installed as an additional dependency to write to Excel files.
+
+=== ":fontawesome-brands-python: Python"
+
+    ```shell
+    $ pip install xlsxwriter
+    ```
+
+Writing to Excel files is not currently available in Rust Polars, though it is possible to [use this crate](https://docs.rs/crate/xlsxwriter/latest) to write to Excel files from Rust.
+
+Writing a `DataFrame` to an Excel file is done with the `write_excel` method:
+
+{{code_block('user-guide/io/excel','write',['write_excel'])}}
+
+The name of the worksheet can be specified with the `worksheet` argument.
+
+{{code_block('user-guide/io/excel','write_sheet_name',['write_excel'])}}
+
+Polars can create rich Excel files with multiple sheets and formatting. For more details, see the API docs for `write_excel`.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -63,6 +63,7 @@ nav:
       - user-guide/lazy/streaming.md
     - IO:
       - user-guide/io/csv.md
+      - user-guide/io/excel.md
       - user-guide/io/parquet.md
       - user-guide/io/json.md
       - user-guide/io/multiple.md