Multifile hybrid scan python bindings to enable page-level IO

docs/cudf/source/conf.py

@@ -693,6 +693,7 @@ def on_missing_reference(app, env, node, contnode):
     ("py:class", "SupportsArrayInterface"),
     ("py:class", "SupportsCudaArrayInterface"),
     ("py:class", "T"),
+    ("py:class", "Buffer"),
 ]
 # Temporarily disable nitpick warnings for pandas: https://github.com/pandas-dev/pandas/issues/64584
 nitpick_ignore_regex = [

python/pylibcudf/pylibcudf/io/experimental/CMakeLists.txt

@@ -1,11 +1,11 @@
 # =============================================================================
 # cmake-format: off
-# SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION.
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 # cmake-format: on
 # =============================================================================
 
-set(cython_sources hybrid_scan.pyx)
+set(cython_sources hybrid_scan.pyx hybrid_scan_multifile.pyx)
 
 set(linked_libraries cudf::cudf)
 rapids_cython_create_modules(

python/pylibcudf/pylibcudf/io/experimental/__init__.pxd

@@ -1,7 +1,8 @@
-# SPDX-FileCopyrightText: Copyright (c) 2025, NVIDIA CORPORATION.
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
 from pylibcudf.io.experimental.hybrid_scan cimport (
     FileMetaData,
     HybridScanReader,
 )
+from pylibcudf.io.experimental.hybrid_scan_multifile cimport HybridScanMultiFile

python/pylibcudf/pylibcudf/io/experimental/__init__.py

@@ -6,11 +6,13 @@
     HybridScanReader,
     UseDataPageMask,
 )
+from pylibcudf.io.experimental.hybrid_scan_multifile import HybridScanMultiFile
 from pylibcudf.io.parquet_metadata import FileMetaData
 
 __all__ = [
     "FileMetaData",  # backwards compatibility
     "HybridScanMetadata",
+    "HybridScanMultiFile",
     "HybridScanReader",
     "UseDataPageMask",
 ]

python/pylibcudf/pylibcudf/io/experimental/hybrid_scan_multifile.pxd

@@ -0,0 +1,23 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+from libcpp.memory cimport unique_ptr
+from libcpp.vector cimport vector
+
+from rmm.pylibrmm.memory_resource cimport DeviceMemoryResource
+from rmm.pylibrmm.stream cimport Stream
+
+from pylibcudf.libcudf.io.hybrid_scan_multifile cimport (
+    hybrid_scan_multifile as cpp_hybrid_scan_multifile,
+)
+from pylibcudf.libcudf.types cimport size_type
+
+
+cdef vector[vector[size_type]] _get_row_group_indices(object row_group_indices) except *
+
+
+cdef class HybridScanMultiFile:
+    cdef unique_ptr[cpp_hybrid_scan_multifile] c_obj
+    cdef Stream _stream
+    cdef DeviceMemoryResource mr
+    cdef object _payload_page_data

python/pylibcudf/pylibcudf/io/experimental/hybrid_scan_multifile.pyi

@@ -0,0 +1,62 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+from collections.abc import Sequence
+
+from rmm.pylibrmm.memory_resource import DeviceMemoryResource
+
+from pylibcudf.column import Column
+from pylibcudf.io.parquet import ParquetReaderOptions
+from pylibcudf.io.parquet_metadata import FileMetaData
+from pylibcudf.io.text import ByteRangeInfo
+from pylibcudf.io.types import TableWithMetadata
+from pylibcudf.span import Span
+from pylibcudf.utils import CudaStreamLike
+
+try:
+    from collections.abc import Buffer
+except ImportError:
+    from typing_extensions import Buffer
+
+class HybridScanMultiFile:
+    @staticmethod
+    def from_parquet_metadatas(
+        parquet_metadatas: Sequence[FileMetaData],
+        options: ParquetReaderOptions,
+    ) -> HybridScanMultiFile: ...
+    def parquet_metadatas(self) -> list[FileMetaData]: ...
+    def page_index_byte_ranges(self) -> list[ByteRangeInfo]: ...
+    def setup_page_indexes(
+        self, page_index_bytes: Sequence[Buffer]
+    ) -> None: ...
+    def total_rows_in_row_groups(
+        self, row_group_indices: list[list[int]]
+    ) -> int: ...
+    def payload_pages_byte_ranges(
+        self,
+        row_group_indices: list[list[int]],
+        row_mask: Column,
+        options: ParquetReaderOptions,
+        stream: CudaStreamLike | None = None,
+    ) -> tuple[list[ByteRangeInfo], list[int]]: ...
+    def setup_chunking_for_payload_columns(
+        self,
+        chunk_read_limit: int,
+        pass_read_limit: int,
+        row_group_indices: list[list[int]],
+        row_mask: Column,
+        page_data: Sequence[Span | None],
+        options: ParquetReaderOptions,
+        stream: CudaStreamLike | None = None,
+        mr: DeviceMemoryResource | None = None,
+    ) -> None: ...
+    def materialize_payload_columns_chunk(
+        self,
+        row_mask: Column,
+    ) -> TableWithMetadata: ...
+    def construct_row_group_passes(
+        self,
+        row_group_indices: list[list[int]],
+        pass_read_limit: int,
+    ) -> list[list[list[int]]]: ...
+    def has_next_table_chunk(self) -> bool: ...