feat(python): Support loading data from multiple Excel/ODS workbooks

[alexander-beedie]

Closes #20354.

Allows read_excel and read_ods to take a list or glob pattern in the "source" parameter. This enables loading a given sheet from multiple workbooks (for example: directories containing workbooks that contain the same sheet data for different dates - can be useful to be able to easily load them all into a single frame).

Also: tidied up some "source" docstrings (rogue linebreaks), and renamed the "ScanSource" type to "FileSource" (as it isn't just used for scan funcs).

Example

Load the "data" sheet from all "trades" workbooks found in subdirs of the "2024" directory into a single DataFrame.

df = pl.read_excel("~/2024/**/trades*.xlsx", sheet_name="data")

[codecov]

Codecov Report

Attention: Patch coverage is 85.29412% with 5 lines in your changes missing coverage. Please review.

Project coverage is 78.96%. Comparing base (676f10d) to head (fedb71f).
Report is 31 commits behind head on main.

Files with missing lines	Patch %	Lines
py-polars/polars/io/spreadsheet/functions.py	84.84%	3 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #20404      +/-   ##
==========================================
- Coverage   79.13%   78.96%   -0.17%     
==========================================
  Files        1572     1562      -10     
  Lines      219839   220103     +264     
  Branches     2462     2486      +24     
==========================================
- Hits       173961   173811     -150     
- Misses      45310    45719     +409     
- Partials      568      573       +5     

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

[ritchie46]

Nice!

[ldacey]

Is it possible to add the filename when reading from multiple files similar to the scan_ methods? I have been using include_file_paths when reading csv/parquet/ndjson.

For Excel, I have been looping through files and concatenating:

            df = df.with_columns(pl.lit(path).alias("raw_file_path"))
            dfs.append(df)

I am not sure how this would work if I just passed a list or glob to the the source argument though. Normally there are fields in the blob metadata (GCS/Azure) that I want to add to the dataframe so I make a dataframe of all of the metadata and join it back to the actual data using that file_paths column.

[alexander-beedie]

Is it possible to add the filename when reading from multiple files similar to the scan_ methods? I have been using include_file_paths when reading csv/parquet/ndjson.

@ldacey: Sure, it's do-able; can you make this a proper feature request so it's easier to track?
If the request only exists in a closed PR it's likely to get lost ;)