feat(python): Improve dtype inference and load for DataFrame cols constructed from Python Enum values

[alexander-beedie]

Improved detection and loading of Python Enum values from all flavours of Python Enum base class.

Added new tests (and new parametrisation to existing Enum unit tests) to provide good coverage.

Examples

Ingest/inference for Python string-valued Enums:

import polars as pl
import enum

for EnumBase in (
    (enum.Enum,),
    (enum.StrEnum,),
    (str, enum.Enum),
):
    class Portfolio(*EnumBase):  # type: ignore[misc]
        TECH = "Technology"
        RETAIL = "Retail"
        OTHER = "Other"

    df = pl.DataFrame({
        "trade_id": [123, 456], 
        "portfolio": [Portfolio.OTHER, Portfolio.TECH],
    })
    # shape: (2, 2)
    # ┌──────────┬────────────┐
    # │ trade_id ┆ portfolio  │
    # │ ---      ┆ ---        │
    # │ i64      ┆ enum       │
    # ╞══════════╪════════════╡
    # │ 123      ┆ Other      │
    # │ 456      ┆ Technology │
    # └──────────┴────────────┘

    df.schema["portfolio"]
    # Enum(categories=['Technology', 'Retail', 'Other'])

We don't support Python integer-valued Enums as Polars Enums, but we do expect to be able to load them by value:

for EnumBase in (
    (enum.Enum,),
    (enum.Flag,),
    (enum.IntEnum,),
    (enum.IntFlag,),
    (int, enum.Enum),
):
    class Number(*EnumBases):  # type: ignore[misc]
        ONE = 1
        TWO = 2
        FOUR = 4
        EIGHT = 8
    
    s = pl.Series(values=[Number.EIGHT, Number.TWO, Number.FOUR])

    shape: (3,)
    # Series: '' [i64]
    # [
    #     8
    #     2
    #     4
    # ]

Miscellaneous

Following #20166, string-based enum values load roughly 50% faster than before (as they are now ingested via the new_str constructor instead of new_object).

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 79.61%. Comparing base (36b1244) to head (1feb153).
Report is 8 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #20180      +/-   ##
==========================================
- Coverage   79.63%   79.61%   -0.03%     
==========================================
  Files        1564     1564              
  Lines      217472   217550      +78     
  Branches     2474     2476       +2     
==========================================
+ Hits       173188   173204      +16     
- Misses      43715    43777      +62     
  Partials      569      569              

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