fix(contracts): mixed-format datetimes, polars diff_schema, robust baseline keys, label and tz handling

[kevincostner17]

Summary

Input-robustness fixes for the contract / baseline entry points in enterprise/contracts.py:

• Mixed-format datetime bounds (min_datetime/max_datetime contracts silently pass mixed-format date strings on pandas 2 #242): on pandas >= 2, string columns checked by min_datetime/max_datetime are parsed with format="mixed" (the utc=True fallback for mixed offsets is kept), so values in a second date format are no longer coerced to NaT and silently dropped. Non-null values that still fail to parse are reported as a warning-level contract.unparseable_datetime finding with a count and examples. pandas 1.5 parsing is unchanged.
• diff_schema on polars (diff_schema raises AttributeError on polars DataFrames #274): the input is converted with to_pandas first.
• Key-level changes (compare_to_baseline(key=...) miscounts NaN keys and crashes on mixed int/str keys #276): keys are matched with Index.difference / Index.intersection (sort=False) and aligned with .loc. A NaN key is treated as one key value, consistent with drop_duplicates, so identical frames report added=0 removed=0 changed=0; mixed int/str keys no longer raise TypeError.
• Non-string column labels (Non-string column labels crash or silently misbehave in six APIs #232 part 4): a shared _resolve_label maps a declared column name to the frame's label (exact label first, then a unique str() match, ValueError if ambiguous). Used by column contracts, strict_columns, compound_unique, distribution drift, key/event_time lookups and diff_schema, so contract column 0 or "0" finds integer label 0, and absent columns still produce missing-column findings.
• tz-aware vs naive baselines (tz-aware vs naive datetimes crash contracts, semantic checks, domain checks and cdc_profile #233 part 5): baseline min/max timestamps are compared in UTC (naive taken as UTC), and a drift.timezone_change warning is emitted when exactly one side is tz-aware, instead of raising TypeError.
• Duplicate column labels (Duplicate column labels crash detect_pii/anonymize, fd.validate and explain_clean #265 part 2): build_baseline, compare_to_baseline, enforce_contract and diff_schema raise a ValueError naming the duplicated labels (or labels that collide when converted to str, which would otherwise overwrite each other's profile).

Behaviour changes

• Frames with duplicate (or string-colliding) column labels now raise ValueError in these entry points, and through them in fd.validate(suite=...), fd.clean(contract=...) and the enterprise drift step.
• On pandas 2, mixed-format date strings can now fail datetime-bound contracts that previously passed silently.

Tests

New module tests/test_contracts_input_robustness.py (33 tests) with each issue's reproduction plus edge cases: unparseable examples, mixed time zones without FutureWarning, polars diff_schema, NaN and composite NaN keys, mixed int/str keys, integer labels across enforce/diff/baseline/compound-unique/key, ambiguous label resolution, timezone added and dropped, and duplicate labels across all entry points including fd.validate.

Verification

• ruff check .: clean; mypy src/freshdata: no issues (202 files)
• Python 3.12 / pandas 2.3.3: 5073 passed, 6 skipped
• Python 3.9 / pandas 1.5.3: 5069 passed, 10 skipped

Closes #242
Closes #274
Closes #276
Refs #232 (part 4)
Refs #233 (part 5)
Refs #265 (part 2)

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: c51fe15b-fe48-4f85-b172-4d480b398d82

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

FreshData benchmark report — performance

• freshdata: ?
• python: ?
• platform: ?

fixture	n_rows	n_cols	p50 s	p95 s	peak MB	repair %	false-repair %	preserve %	trust	monotonic	export %

Authored-code reduction (Metric 6)