polars.ScanCastOptions

class polars.ScanCastOptions(
    *,
    integer_cast: Literal['upcast',
    'allow-float',
    'forbid'] | Collection[Literal['upcast',
    'allow-float',
    'forbid']] = 'forbid',
    float_cast: Literal['upcast',
    'downcast',
    'forbid'] | Collection[Literal['upcast',
    'downcast',
    'forbid']] = 'forbid',
    datetime_cast: Literal['convert-timezone',
    'nanosecond-downcast',
    'microsecond-downcast',
    'microsecond-upcast',
    'millisecond-upcast',
    'downcast',
    'upcast',
    'forbid'] | Collection[Literal['convert-timezone',
    'nanosecond-downcast',
    'microsecond-downcast',
    'microsecond-upcast',
    'millisecond-upcast',
    'downcast',
    'upcast',
    'forbid']] = 'forbid',
    missing_struct_fields: Literal['insert',
    'raise'] = 'raise',
    extra_struct_fields: Literal['ignore',
    'raise'] = 'raise',
    categorical_to_string: Literal['allow',
    'forbid'] = 'forbid',
    _internal_call: bool = False,
)

Cast options applied when scanning files.

__init__(
    *,
    integer_cast: Literal['upcast',
    'allow-float',
    'forbid'] | Collection[Literal['upcast',
    'allow-float',
    'forbid']] = 'forbid',
    float_cast: Literal['upcast',
    'downcast',
    'forbid'] | Collection[Literal['upcast',
    'downcast',
    'forbid']] = 'forbid',
    datetime_cast: Literal['convert-timezone',
    'nanosecond-downcast',
    'microsecond-downcast',
    'microsecond-upcast',
    'millisecond-upcast',
    'downcast',
    'upcast',
    'forbid'] | Collection[Literal['convert-timezone',
    'nanosecond-downcast',
    'microsecond-downcast',
    'microsecond-upcast',
    'millisecond-upcast',
    'downcast',
    'upcast',
    'forbid']] = 'forbid',
    missing_struct_fields: Literal['insert',
    'raise'] = 'raise',
    extra_struct_fields: Literal['ignore',
    'raise'] = 'raise',
    categorical_to_string: Literal['allow',
    'forbid'] = 'forbid',
    _internal_call: bool = False,
) → None

Common configuration for scanning files.

Warning

This functionality is considered unstable. It may be changed at any point without it being considered a breaking change.

Parameters:

integer_cast

Configuration for casting from integer types:

• upcast: Allow lossless casting to wider integer types.
• allow-float: Allow casting integers to float types.
• forbid: Raises an error if dtypes do not match.

float_cast

Configuration for casting from float types:

• upcast: Allow casting to higher precision float types.
• downcast: Allow casting to lower precision float types.
• forbid: Raises an error if dtypes do not match.

datetime_cast

Configuration for casting from datetime types:

• nanosecond-downcast: Allow nanosecond precision datetime to be downcasted to any lower precision. This has a similar effect to PyArrow’s coerce_int96_timestamp_unit.
• microsecond-downcast: Allow microsecond precision datetime to be downcasted to millisecond precision.
• microsecond-upcast: Allow microsecond precision datetime to be upcasted to nanosecond precision.
• millisecond-upcast: Allow millisecond precision datetime to be upcasted to microsecond or nanosecond precision.
• downcast: Allow downcasting to any lower precision (convenience aggregate of nanosecond-downcast and microsecond-downcast).
• upcast: Allow upcasting to any higher precision (convenience aggregate of millisecond-upcast and microsecond-upcast).
• convert-timezone: Allow casting to a different timezone.
• forbid: Raises an error if dtypes do not match.

missing_struct_fields

Configuration for behavior when struct fields defined in the schema are missing from the data:

• insert: Inserts the missing fields.
• raise: Raises an error.

extra_struct_fields

Configuration for behavior when extra struct fields outside of the defined schema are encountered in the data:

• ignore: Silently ignores.
• raise: Raises an error.

categorical_to_string

Configuration for behavior when reading in a column whose expected type is string, but type in the file is categorical.

• allow: Categorical is casted to string.
• forbid: Raises an error.

Methods

__init__(*[, integer_cast, float_cast, ...])

Common configuration for scanning files.

Attributes

integer_cast
float_cast
datetime_cast
missing_struct_fields
extra_struct_fields
categorical_to_string