pandera.backends.narwhals.container.DataFrameSchemaBackend

class pandera.backends.narwhals.container.DataFrameSchemaBackend

Methods

add_missing_columns(check_obj, schema, column_info)

Add schema columns missing from the frame.

Absent columns must either declare a default value or be nullable; otherwise an ADD_MISSING_COLUMN_NO_DEFAULT error is raised. Missing columns are inserted in schema order relative to the existing columns.

Column construction is hybrid, mirroring the coerce path: plain numpy dtypes with a concrete default are built Narwhals-native (nw.lit(value).cast(...)); extension dtypes (nullable Int64 etc.) and null-valued columns are given their schema dtype through the pandas dtype engine, since nw.cast cannot represent them (e.g. a null integer).

check_column_presence(check_obj, schema, column_info)

Check that all columns in the schema are present in the dataframe.

Return type:

list[CoreCheckResult]

check_column_values_are_unique(check_obj, schema)

Check that column values are unique.

Return type:

CoreCheckResult

check_native_column_names_unique(check_obj, schema)

Return a SchemaError if duplicate column labels are present.

Mirrors the native pandas check_column_names_are_unique. Runs on the native pandas frame (before Narwhals wrapping) because Narwhals rejects duplicate column labels at construction time. Returns None when the check passes or unique_column_names is not set.

coerce_dtype(check_obj, schema)

Coerce dtypes to the schema (Narwhals-native).

Two cases are handled:

• Row-wise auto_coerce dtypes (e.g. PydanticModel): coerced by the dtype engine itself over the whole frame — works for any backend.

• Column- and schema-level dtypes: coerced with nw.cast for eager pandas-like frames. Narwhals normalizes pandas dtypes, so native pandas dtype fidelity (nullable Int64, Categorical, tz-aware datetimes) is not guaranteed. Cast failures are reported as DATATYPE_COERCION errors.

Column-level coercion remains a no-op for non-pandas Narwhals backends (a known gap). Accepts and returns either a Narwhals frame (validate path) or a native frame (direct schema.coerce_dtype(df) calls).

coerce_native_index(check_obj, schema, error_handler)

Coerce the pandas index dtype via the native Index component.

Index/MultiIndex is the one pandas concept Narwhals cannot express, so index coercion is delegated to the native pandas Index backend. Done on the native frame before wrapping so the coerced index propagates through Narwhals (which preserves the pandas index) to the output.

collect_column_info(check_obj, schema)

Collect column metadata for the dataframe.

collect_schema_components(check_obj, schema, column_info)

Collects all schema components to use for validation.

run_checks(check_obj, schema)

Run a list of checks on the check object.

Return type:

list[CoreCheckResult]

run_index_checks(check_obj, schema, lazy)

Validate the pandas index / MultiIndex component.

Delegates to the native pandas Index/MultiIndex backends (which stay registered even when the Narwhals backend is active). Narwhals preserves the pandas index through its operations, so _to_native of the parsed Narwhals frame still carries the original index.

For non-pandas frames this is a no-op — those schemas have no index component, and the validate method already warned if one is present.

Return type:

list[CoreCheckResult]

run_native_parsers(check_obj, schema)

Run custom schema.parsers on the native pandas frame.

Narwhals has no parser step, and custom parsers are arbitrary user code written against the native pandas frame. The parser function is applied directly here (self-contained — no dispatch to the pandas schema backend): dataframe-level parsers receive the whole frame, and element_wise parsers are applied row-wise.

run_schema_component_checks(check_obj, schema, schema_components, lazy)

Run checks for all schema components.

Return type:

list[CoreCheckResult]

set_defaults(check_obj, schema)

Fill null values in columns that declare a default (Narwhals-native).

strict_filter_columns(check_obj, schema, column_info)

Filter columns that aren’t specified in the schema.

validate(check_obj, schema, *, head=None, tail=None, sample=None, random_state=None, lazy=False, inplace=False)

Parse and validate a check object, returning type-coerced and validated object.