feat(pagination): add count, index, reversed, copy, and + to PaginationList

These were inherited from list's C implementation, which reads the
underlying array directly and bypasses _fetch_all()/_fetch_through_index().
On a multi-page result they silently operated on only the already-fetched
pages. Each is now overridden to fetch all remaining pages first, then
delegate to list's implementation. __add__ also needed an @overload to
match list.__add__'s own overloaded signature for mypy.

Author: stark256-spec

pyiceberg/typedef.py

@@ -16,6 +16,7 @@
 # under the License.
 from __future__ import annotations
 
+import sys
 from abc import abstractmethod
 from collections.abc import Callable, Iterator
 from datetime import date, datetime, time
@@ -155,6 +156,7 @@ def model_dump_json(
 
 
 T = TypeVar("T")
+S = TypeVar("S")
 
 
 class IcebergRootModel(RootModel[T], Generic[T]):
@@ -305,3 +307,39 @@ def __getitem__(self, idx: SupportsIndex | slice) -> T | list[T]:
             else:
                 self._fetch_through_index(i)
         return list.__getitem__(self, idx)
+
+    def count(self, value: T) -> int:
+        """Return the number of occurrences of value, fetching all pages first."""
+        self._fetch_all()
+        return list.count(self, value)
+
+    def index(self, value: T, start: SupportsIndex = 0, stop: SupportsIndex = sys.maxsize, /) -> int:
+        """Return the index of the first occurrence of value, fetching all pages first."""
+        self._fetch_all()
+        return list.index(self, value, start, stop)
+
+    def __reversed__(self) -> Iterator[T]:
+        """Return an iterator over the items in reverse order, fetching all pages first."""
+        self._fetch_all()
+        return list.__reversed__(self)
+
+    def copy(self) -> list[T]:
+        """Return a plain list with all items, fetching all pages first."""
+        self._fetch_all()
+        return list.copy(self)
+
+    @overload
+    def __add__(self, other: list[T]) -> list[T]: ...
+
+    @overload
+    def __add__(self, other: list[S]) -> list[S | T]: ...
+
+    def __add__(self, other: list[Any]) -> list[Any]:
+        """Return self + other as a plain list, fetching all pages first."""
+        self._fetch_all()
+        return list.__add__(self, other)
+
+    def __radd__(self, other: list[T]) -> list[T]:
+        """Return other + self as a plain list, fetching all pages first."""
+        self._fetch_all()
+        return list.__add__(other, self)

tests/utils/test_pagination.py

@@ -17,6 +17,8 @@
 
 from __future__ import annotations
 
+import pytest
+
 from pyiceberg.typedef import PaginationList
 
 
@@ -77,6 +79,38 @@ def test_single_page_is_list_subclass() -> None:
     assert isinstance(pl, list)
 
 
+def test_single_page_count() -> None:
+    pl, _ = _simple_pagination_list([[1, 2, 2, 3]])
+    assert pl.count(2) == 2
+
+
+def test_single_page_index() -> None:
+    pl, _ = _simple_pagination_list([[10, 20, 30]])
+    assert pl.index(30) == 2
+
+
+def test_single_page_reversed() -> None:
+    pl, _ = _simple_pagination_list([[1, 2, 3]])
+    assert list(reversed(pl)) == [3, 2, 1]
+
+
+def test_single_page_copy() -> None:
+    pl, expected = _simple_pagination_list([[1, 2, 3]])
+    copied = pl.copy()
+    assert copied == expected
+    assert type(copied) is list
+
+
+def test_single_page_add() -> None:
+    pl, _ = _simple_pagination_list([[1, 2]])
+    assert pl + [3] == [1, 2, 3]
+
+
+def test_single_page_radd() -> None:
+    pl, _ = _simple_pagination_list([[2, 3]])
+    assert [1] + pl == [1, 2, 3]
+
+
 # ---------------------------------------------------------------------------
 # Multi-page: lazily fetches subsequent pages
 # ---------------------------------------------------------------------------
@@ -178,6 +212,44 @@ def test_multi_page_equality_with_plain_list() -> None:
     assert pl == expected
 
 
+def test_multi_page_count_fetches_all() -> None:
+    pl, _ = _simple_pagination_list([[1, 2], [2, 3]])
+    assert pl.count(2) == 2
+
+
+def test_multi_page_index_fetches_all() -> None:
+    pl, _ = _simple_pagination_list([[1, 2], [3, 4]])
+    assert pl.index(4) == 3
+
+
+def test_multi_page_index_raises_for_missing_value() -> None:
+    pl, _ = _simple_pagination_list([[1, 2], [3, 4]])
+    with pytest.raises(ValueError):
+        pl.index(99)
+
+
+def test_multi_page_reversed_fetches_all() -> None:
+    pl, expected = _simple_pagination_list([[1, 2], [3, 4]])
+    assert list(reversed(pl)) == list(reversed(expected))
+
+
+def test_multi_page_copy_fetches_all() -> None:
+    pl, expected = _simple_pagination_list([[1, 2], [3, 4]])
+    copied = pl.copy()
+    assert copied == expected
+    assert type(copied) is list
+
+
+def test_multi_page_add_fetches_all() -> None:
+    pl, expected = _simple_pagination_list([[1, 2], [3, 4]])
+    assert pl + [5] == expected + [5]
+
+
+def test_multi_page_radd_fetches_all() -> None:
+    pl, expected = _simple_pagination_list([[1, 2], [3, 4]])
+    assert [0] + pl == [0] + expected
+
+
 # ---------------------------------------------------------------------------
 # Performance: len() should not eagerly fetch all pages for a single-page list
 # ---------------------------------------------------------------------------