feat(python): Support loading Excel Table objects by name

[alexander-beedie]

Closes #18949.

• Adds a "table_name" parameter to read_excel, supporting load of named Excel Table objects¹; works with "openpyxl" and "calamine" (requiring fastexcel >= 0.12 for the latter).

• Table names are unique across the workbook, so it is not required to provide a value to the "sheet_name" or "sheet_id" parameter.

• If a "sheet_name" or "sheet_id" is given, an error is raised if the named table is not found on that sheet.

Example

import polars as pl

df = pl.DataFrame({
  "x": ["aa", "bb", "cc"],
  "y": [100, 325, -250],
  "z": [975, -444, 123],
})

# note: when we read back a named table object with a total
# row we expect the read to automatically omit that row as 
# it is *not* part of the actual table data
df.write_excel(
  "demo.xlsx",
  worksheet="data",
  table_name="PolarsFrameTable",
  column_totals=True,
)

# optional to specify a sheet; table names are guaranteed to
# be unique (but if a sheet is specified, the table must
# exist on *that* sheet or we'll raise an error)
pl.read_excel("demo.xlsx", table_name="PolarsFrameTable")
# shape: (3, 3)
# ┌─────┬──────┬──────┐
# │ x   ┆ y    ┆ z    │
# │ --- ┆ ---  ┆ ---  │
# │ str ┆ i64  ┆ i64  │
# ╞═════╪══════╪══════╡
# │ aa  ┆ 100  ┆ 975  │
# │ bb  ┆ 325  ┆ -444 │
# │ cc  ┆ -250 ┆ 123  │
# └─────┴──────┴──────┘

Footnotes

1. Using structured references with Excel tables ↩

[codecov]

Codecov Report

Attention: Patch coverage is 60.97561% with 16 lines in your changes missing coverage. Please review.

Project coverage is 78.97%. Comparing base (6cd9988) to head (5fd87c9).
Report is 11 commits behind head on main.

Files with missing lines	Patch %	Lines
py-polars/polars/io/spreadsheet/functions.py	60.97%	12 Missing and 4 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #20654      +/-   ##
==========================================
- Coverage   79.01%   78.97%   -0.05%     
==========================================
  Files        1557     1557              
  Lines      220552   220725     +173     
  Branches     2514     2527      +13     
==========================================
+ Hits       174274   174322      +48     
- Misses      45705    45825     +120     
- Partials      573      578       +5     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.