feat(python): support DataFrame export to numpy structured/record arrays

[alexander-beedie]

Closes #8564 (in conjunction with #8620, which provides structured array init support).

Adds an optional "structured" parameter to to_numpy, allowing for straightforward export to structured arrays¹ (and, via a zero-copy .view(np.recarray) call, to record arrays).

Example

import numpy as np
import polars as pl

df = pl.DataFrame(
    {
        "foo": [1, 2, 3],
        "bar": [6.5, 7.0, 8.5],
        "ham": ["a", "b", "c"],
    },
    schema_overrides = {"foo": pl.UInt8, "bar": pl.Float32},
)

Standard export to 2D array:

df.to_numpy()
# array([[1, 6.5, 'a'],
#        [2, 7.0, 'b'],
#        [3, 8.5, 'c']], dtype=object)

Structured array export:

df.to_numpy( structured=True )
# array([(1, 6.5, 'a'), (2, 7. , 'b'), (3, 8.5, 'c')],
#       dtype=[('foo', 'u1'), ('bar', '<f4'), ('ham', '<U1')])

Structured array to record array:

df.to_numpy( structured=True ).view( np.recarray )
# rec.array([(1, 6.5, 'a'), (2, 7. , 'b'), (3, 8.5, 'c')],
#           dtype=[('foo', 'u1'), ('bar', '<f4'), ('ham', '<U1')])

Footnotes

1. Numpy structured arrays: https://numpy.org/doc/stable/user/basics.rec.html ↩