Fix type annotations in pylibucdf hybrid scan

[TomAugspurger]

Description

This changes the list[Span] type annotations in the pylibucdf hybrid scan module to Sequence[Span]. It's tested by adding type annotations to the hybrid scan tests, which surfaced the error reported in the original issue:

❯ mypy python/pylibcudf/tests/io/test_experimental_hybrid_scan.py                                                                                                                                                                                                                                                        (base) 
python/pylibcudf/tests/io/test_experimental_hybrid_scan.py:360: error: Argument 2 to "materialize_filter_columns" of "HybridScanReader" has incompatible type "list[gpumemoryview]"; expected "list[Span]"  [arg-type]
python/pylibcudf/tests/io/test_experimental_hybrid_scan.py:360: note: "list" is invariant -- see https://mypy.readthedocs.io/en/stable/common_issues.html#variance
python/pylibcudf/tests/io/test_experimental_hybrid_scan.py:360: note: Consider using "Sequence" instead, which is covariant
python/pylibcudf/tests/io/test_experimental_hybrid_scan.py:395: error: Argument 2 to "materialize_payload_columns" of "HybridScanReader" has incompatible type "list[gpumemoryview]"; expected "list[Span]"  [arg-type]
python/pylibcudf/tests/io/test_experimental_hybrid_scan.py:395: note: "list" is invariant -- see https://mypy.readthedocs.io/en/stable/common_issues.html#variance
python/pylibcudf/tests/io/test_experimental_hybrid_scan.py:395: note: Consider using "Sequence" instead, which is covariant
python/pylibcudf/tests/io/test_experimental_hybrid_scan.py:410: error: Argument 1 to "SourceInfo" has incompatible type "list[BytesIO]"; expected "Sequence[str] | Sequence[PathLike[Any]] | Sequence[Datasource]"  [arg-type]
python/pylibcudf/tests/io/test_experimental_hybrid_scan.py:499: error: Argument 1 to "SourceInfo" has incompatible type "list[BytesIO]"; expected "Sequence[str] | Sequence[PathLike[Any]] | Sequence[Datasource]"  [arg-type]
python/pylibcudf/tests/io/test_experimental_hybrid_scan.py:572: error: Argument 6 to "setup_chunking_for_filter_columns" of "HybridScanReader" has incompatible type "list[gpumemoryview]"; expected "list[Span]"  [arg-type]
python/pylibcudf/tests/io/test_experimental_hybrid_scan.py:572: note: "list" is invariant -- see https://mypy.readthedocs.io/en/stable/common_issues.html#variance
python/pylibcudf/tests/io/test_experimental_hybrid_scan.py:572: note: Consider using "Sequence" instead, which is covariant
python/pylibcudf/tests/io/test_experimental_hybrid_scan.py:645: error: Argument 6 to "setup_chunking_for_filter_columns" of "HybridScanReader" has incompatible type "list[gpumemoryview]"; expected "list[Span]"  [arg-type]
python/pylibcudf/tests/io/test_experimental_hybrid_scan.py:645: note: "list" is invariant -- see https://mypy.readthedocs.io/en/stable/common_issues.html#variance
python/pylibcudf/tests/io/test_experimental_hybrid_scan.py:645: note: Consider using "Sequence" instead, which is covariant
Found 6 errors in 1 file (checked 1 source file)

Closes #22117

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[TomAugspurger]

/ok to test 7f6dc45

[mroeschke]

non-blocking: The docs in python/pylibcudf/pylibcudf/io/experimental/hybrid_scan.pyx generally still state list[Span] so it would be nice to update those.

Also the Cython annotations do use list for these arguments, but I don't think this annotation change directly conflicts with this new annotation

[TomAugspurger]

Also the Cython annotations do use list for these arguments, but I don't think this annotation change directly conflicts with this new annotation

I'll look into this. I wasn't sure offhand whether cython does something special for list[T] that it wouldn't for Sequence[T].

[vyasr]

It does matter for Cython. If you type a function in Cython with a built-in type like list, it will strictly validate at runtime, so Sequence and list are not equivalent.

I think your best option here is to use a cast instead. Either that, or change the type annotation in the pyi to be a generic list rather than list[T] so that you give up verification of the type inside the list and just validate the top level of the list.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: cda0ebc0-36bb-4f81-b74f-dbb6a4415413

📥 Commits

Reviewing files that changed from the base of the PR and between 0712ba3 and 79f61c6.

📒 Files selected for processing (3)

• pyproject.toml
• python/pylibcudf/pylibcudf/io/experimental/hybrid_scan.pyx
• python/pylibcudf/tests/io/test_experimental_hybrid_scan.py

✅ Files skipped from review due to trivial changes (1)

• python/pylibcudf/pylibcudf/io/experimental/hybrid_scan.pyx

🚧 Files skipped from review as they are similar to previous changes (1)

• python/pylibcudf/tests/io/test_experimental_hybrid_scan.py

---

📝 Walkthrough

Summary by CodeRabbit

• Refactor
  • Loosened type annotations for “Span-like” inputs in the experimental hybrid scan reader stubs and related documentation, keeping behavior unchanged.
• Tests
  • Added/expanded Python type hints across the hybrid scan test suite (fixtures and test signatures) for clearer static checking.
• Chores
  • Updated SPDX copyright attribution.
• Style
  • Added a Ruff-compatible tooling configuration section for cython-lint (max line length 120).

Walkthrough

Seven HybridScanReader method parameters typed as list[Span] in the .pyi stub are relaxed to untyped list, and the Span import is removed. Matching docstring annotations in the .pyx file are updated the same way. Copyright headers are updated in both source files. Cython-lint configuration is added to pyproject.toml. All test fixtures and test function signatures in the hybrid scan test module gain explicit Python type annotations.

Changes

HybridScanReader type annotation relaxation

Layer / File(s)	Summary
Stub and docstring: list[Span] → list python/pylibcudf/pylibcudf/io/experimental/hybrid_scan.pyi, python/pylibcudf/pylibcudf/io/experimental/hybrid_scan.pyx	Removes the Span import from the stub and changes dictionary_page_data, bloom_filter_data, and column_chunk_data parameters from list[Span] to list across seven HybridScanReader methods in both the .pyi stub and .pyx docstrings. Copyright headers are updated to include "NVIDIA CORPORATION & AFFILIATES".
Build configuration: cython-lint max line length pyproject.toml	Adds a new [tool.cython-lint] section with max-line-length set to 120.
Test fixture and function type annotations python/pylibcudf/tests/io/test_experimental_hybrid_scan.py	Adds explicit type annotations (int, bytes, pa.Table, plc.io.parquet.ParquetReaderOptions, HybridScanReader, `Stream

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Suggested labels

improvement

Suggested reviewers

• galipremsagar
• Matt711

🚥 Pre-merge checks | ❌ 5

❌ Failed checks (5 warnings)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	The title mentions fixing type annotations in hybrid scan, but the PR changes list[Span] to list (untyped), not to Sequence[Span] as described in objectives.	Update PR title to accurately reflect the actual changes made (e.g., 'Remove type annotations from hybrid_scan Span parameters' or verify if changes should use Sequence[Span] instead).
Description check	⚠️ Warning	The description claims changes convert list[Span] to Sequence[Span], but the raw_summary shows changes convert to untyped list instead.	Update PR description to accurately reflect that parameters are being changed to untyped list, or correct the actual implementation to use Sequence[Span] as described.
Linked Issues check	⚠️ Warning	Issue #22117 requires changing list[Span] to Sequence[Span] for covariance, but the PR changes to untyped list instead, which does not solve the mypy type compatibility problem.	Update the code changes to use Sequence[Span] instead of untyped list, or clarify why the alternative approach of using untyped list is preferred.
Out of Scope Changes check	⚠️ Warning	The pyproject.toml modification adding cython-lint configuration appears unrelated to the hybrid_scan type annotation fixes specified in linked issue #22117.	Remove the cython-lint configuration change from pyproject.toml or document its relationship to the hybrid_scan type annotation fix.
Docstring Coverage	⚠️ Warning	Docstring coverage is 70.37% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

python/pylibcudf/tests/io/test_experimental_hybrid_scan.py (1)

671-708: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Missing type annotations on test function parameters and return type.

The test function test_hybrid_scan_construct_row_group_passes (lines 671–708) lacks type annotations on its parameters and return type, while all other test functions in this module have been explicitly annotated. This is inconsistent with the PR objective to add explicit type annotations to all test functions.

🔧 Proposed fix

 def test_hybrid_scan_construct_row_group_passes(
-    simple_hybrid_scan_reader,
-    simple_parquet_options,
-):
+    simple_hybrid_scan_reader: HybridScanReader,
+    simple_parquet_options: plc.io.parquet.ParquetReaderOptions,
+) -> None:

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@python/pylibcudf/tests/io/test_experimental_hybrid_scan.py` around lines 671
- 708, The test function `test_hybrid_scan_construct_row_group_passes` is
missing type annotations on its parameters and return type annotation. Add type
annotations to the function parameters `simple_hybrid_scan_reader` and
`simple_parquet_options`, and add a return type annotation (which should be
`None` for test functions). This aligns the function with the type annotation
standards applied to other test functions in the module.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@python/pylibcudf/tests/io/test_experimental_hybrid_scan.py`:
- Around line 671-708: The test function
`test_hybrid_scan_construct_row_group_passes` is missing type annotations on its
parameters and return type annotation. Add type annotations to the function
parameters `simple_hybrid_scan_reader` and `simple_parquet_options`, and add a
return type annotation (which should be `None` for test functions). This aligns
the function with the type annotation standards applied to other test functions
in the module.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: b792fc51-54b3-4ea9-a0e8-f1347d723bac

📥 Commits

Reviewing files that changed from the base of the PR and between ba74d66 and 0712ba3.

📒 Files selected for processing (3)

• python/pylibcudf/pylibcudf/io/experimental/hybrid_scan.pyi
• python/pylibcudf/pylibcudf/io/experimental/hybrid_scan.pyx
• python/pylibcudf/tests/io/test_experimental_hybrid_scan.py

[vyasr]

This change is necessary because of #22905. The copyright notice used by the latest version of our copyright hook (rapidsai/pre-commit-hooks#120) is too long for cython-lint, but this is the first PR that is using that hook. We already ignore E501 for ruff in Python code (although in that case we're better off because ruff format will still try to fix the line lengths) so I'm accepting this change as well for now. We'll need to look at the copyright and see if there's anything we can do to improve this situation going forward.

[vyasr]

/merge