refactor!: Replace eager: bool with "lazy-in-lazy-out"

[Oliver Borchert (borchero)]

Motivation

Currently, we have a parameter eager: bool to govern whether validation and filtering is performed eagerly or lazily. This is a little inconsistent with what one would expect when familiar with the polars API:

• For schema validation/filtering, we can easily replace the parameter entirely with "lazy-in-lazy-out"/"eager-in-eager-out" behavior. This also makes user code more consistent as collection is not implicit in the case of a lazy input, but requires an explicit collect.
• For collection validation/filtering, we take the same approach as for sink_parquet: by default, we collect, but this can be "disabled" by setting lazy=True (unless the collection defines at least one eager member).

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@f32b155). Learn more about missing BASE report.

Additional details and impacted files

@@           Coverage Diff            @@
##             main      #372   +/-   ##
========================================
  Coverage        ?   100.00%           
========================================
  Files           ?        56           
  Lines           ?      3513           
  Branches        ?         0           
========================================
  Hits            ?      3513           
  Misses          ?         0           
  Partials        ?         0           

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR removes the eager: bool toggle from schema-level validation/filtering APIs in favor of Polars-style “lazy-in-lazy-out / eager-in-eager-out” behavior, and introduces a lazy: bool switch for collection-level validation/filtering to control whether collections are returned lazily (with restrictions when eager members exist).

Changes:

• Refactored Schema.validate / Schema.filter to determine eager vs lazy behavior from the input frame type rather than an eager flag.
• Updated Collection.validate / Collection.filter to use lazy: bool (default False) and added validation that lazy=True cannot be used when the collection has eager members.
• Updated tests and benchmarks to match the new API and semantics.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/schema/test_validate.py	Removes eager parametrization and adjusts expectations based on input frame type.
tests/schema/test_filter.py	Updates helper and tests to rely on input frame type for eager vs lazy filtering behavior.
tests/collection/test_skip_member_validation.py	Migrates collection calls from eager=False to lazy=True.
tests/collection/test_filter_validate.py	Renames eager parametrization to lazy and updates calls accordingly.
tests/collection/test_dataframe_members.py	Adds coverage ensuring lazy=True is rejected for collections with eager members.
tests/benches/test_schema.py	Adjusts benchmark to validate either eager or lazy inputs without eager=.
tests/benches/test_collection.py	Updates benchmark to use lazy=True for collection filtering.
dataframely/schema.py	Removes eager parameter and implements type-driven eager vs lazy semantics; adds Polars-version guard for efficient filtering.
dataframely/collection/collection.py	Replaces eager with lazy, enforces eager-member restriction, and updates eager vs lazy execution paths.

Comments suppressed due to low confidence (1)

dataframely/collection/collection.py:599

• Collection.filter's docstring claims member frames are always eagerly collected, but the new lazy parameter allows returning a fully lazy result. The parameter description should reflect the conditional behavior.

                All data frames passed here will be eagerly collected within the method,
                regardless of whether they are a :class:`~polars.DataFrame` or
                :class:`~polars.LazyFrame`.