Tighten IncrementalAppendScan docstrings

Drop references to other Iceberg clients (Java, Spark) and re-shape
the prose to match the style already used by `Table.scan` and
`DataScan` (which the original PR #2235 also mirrored).

- Trim `BaseScan` docstring to a single line, matching `TableScan`.
- Reduce `IncrementalAppendScan` class docstring to the args block,
  mirroring `DataScan`'s shape. Roll the "from may be expired" note
  into the `from_snapshot_id_exclusive` arg description.
- Match `from_snapshot_exclusive` / `to_snapshot_inclusive` chaining
  docstrings to PR #2235's wording ("this for method chaining").
- Simplify `is_parent_ancestor_of` and `plan_files` docstrings.
- Drop the "matches iceberg-java" comment from the test parametrize.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: smaheshwar-pltr

pyiceberg/table/__init__.py

@@ -1754,13 +1754,7 @@ def _parse_row_filter(expr: str | BooleanExpression) -> BooleanExpression:
 
 
 class BaseScan(ABC):
-    """A base class for all table scans.
-
-    Holds the snapshot-independent state (row filter, projected columns, case sensitivity,
-    options, limit) and shared chaining helpers. Concrete subclasses are :class:`TableScan`
-    (single-snapshot scans, e.g. :class:`DataScan`) and :class:`IncrementalAppendScan`
-    (a range of append-operation snapshots).
-    """
+    """A base class for all table scans."""
 
     table_metadata: TableMetadata
     io: FileIO
@@ -2230,29 +2224,17 @@ def count(self) -> int:
 
 
 class IncrementalAppendScan(BaseScan):
-    """An incremental scan that accumulates data appended between two snapshots.
-
-    The configured snapshot range corresponds to Spark's ``start-snapshot-id`` (exclusive)
-    and ``end-snapshot-id`` (inclusive) read options. An explicit ``from_snapshot_id_exclusive``
-    is required: defaulting to the table's oldest ancestor (as the Java API does) is rarely the
-    user's intent, and erroring is safer. ``to_snapshot_id_inclusive`` defaults to the table's
-    current snapshot when omitted.
-
-    Unsupported (relative to iceberg-java's ``IncrementalAppendScan``):
-
-    - Snapshot references / ``useBranch``: the configured snapshots must be passed as IDs.
-    - Counting rows (``count()``) and rolling time-travel via ``use_ref(...)``: these belong to
-      single-snapshot scans (:class:`TableScan` / :class:`DataScan`).
+    """An incremental scan of a table's data that accumulates appended data between two snapshots.
 
     Args:
         row_filter:
             A string or BooleanExpression that describes the
-            desired rows.
+            desired rows
         selected_fields:
             A tuple of strings representing the column names
             to return in the output dataframe.
         case_sensitive:
-            If True column matching is case sensitive.
+            If True column matching is case sensitive
         options:
             Additional Table properties as a dictionary of
             string key value pairs to use for this scan.
@@ -2261,15 +2243,12 @@ class IncrementalAppendScan(BaseScan):
             return in the scan result. If None, fetches all
             matching rows.
         from_snapshot_id_exclusive:
-            ID of the "from" snapshot, to start the incremental scan from, exclusively. When the
-            scan is ultimately planned, this must not be None. This snapshot does not need to be
-            present in the table metadata (it may have been expired), as long as it is the parent
-            of some ancestor of the "to" snapshot. Corresponds to Spark's ``start-snapshot-id``
-            read option.
+            Optional ID of the "from" snapshot, to start the incremental scan from, exclusively. When the scan is
+            ultimately planned, this must not be None. The snapshot does not need to be present in the table metadata
+            (it may have been expired), as long as it is the parent of some ancestor of the "to" snapshot.
         to_snapshot_id_inclusive:
             Optional ID of the "to" snapshot, to end the incremental scan at, inclusively.
-            Omitting it will default to the table's current snapshot. Corresponds to Spark's
-            ``end-snapshot-id`` read option.
+            Omitting it will default to the table's current snapshot.
     """
 
     from_snapshot_id_exclusive: int | None
@@ -2300,24 +2279,24 @@ def __init__(
         self.to_snapshot_id_inclusive = to_snapshot_id_inclusive
 
     def from_snapshot_exclusive(self: IAS, from_snapshot_id_exclusive: int | None) -> IAS:
-        """Instruct this scan to look for changes starting from a particular snapshot (exclusive).
+        """Instructs this scan to look for changes starting from a particular snapshot (exclusive).
 
         Args:
-            from_snapshot_id_exclusive: the start snapshot ID (exclusive).
+            from_snapshot_id_exclusive: the start snapshot ID (exclusive)
 
         Returns:
-            A copy of this scan with the specified ``from`` snapshot.
+            this for method chaining
         """
         return self.update(from_snapshot_id_exclusive=from_snapshot_id_exclusive)
 
     def to_snapshot_inclusive(self: IAS, to_snapshot_id_inclusive: int | None) -> IAS:
-        """Instruct this scan to look for changes up to a particular snapshot (inclusive).
+        """Instructs this scan to look for changes up to a particular snapshot (inclusive).
 
         Args:
-            to_snapshot_id_inclusive: the end snapshot ID (inclusive).
+            to_snapshot_id_inclusive: the end snapshot ID (inclusive)
 
         Returns:
-            A copy of this scan with the specified ``to`` snapshot.
+            this for method chaining
         """
         return self.update(to_snapshot_id_inclusive=to_snapshot_id_inclusive)
 
@@ -2328,11 +2307,7 @@ def projection(self) -> Schema:
         return current_schema.select(*self.selected_fields, case_sensitive=self.case_sensitive)
 
     def plan_files(self) -> Iterable[FileScanTask]:
-        """Plan the relevant files added between the specified snapshots.
-
-        Returns:
-            An iterable of FileScanTasks for data files added by append snapshots in the configured range.
-        """
+        """Plans the relevant files added between the specified snapshots."""
         from_snapshot_id, to_snapshot_id = self._validate_and_resolve_snapshots()
 
         append_snapshots = [
@@ -2425,7 +2400,7 @@ def _validate_and_resolve_snapshots(self) -> tuple[int, int]:
 
         # The start snapshot is exclusive, so it does not need to be present in the table metadata
         # (it may have been expired). It is valid as long as it is the parent of some ancestor of
-        # the end snapshot. This matches the behavior of `BaseIncrementalScan` in iceberg-java.
+        # the end snapshot.
         if not is_parent_ancestor_of(to_snapshot_id, self.from_snapshot_id_exclusive, self.table_metadata):
             raise ValueError(
                 f"Starting snapshot (exclusive) {self.from_snapshot_id_exclusive} is not a parent "

pyiceberg/table/snapshots.py

@@ -457,12 +457,7 @@ def ancestors_between_ids(
 
 
 def is_parent_ancestor_of(snapshot_id: int, ancestor_parent_snapshot_id: int, table_metadata: TableMetadata) -> bool:
-    """Return whether any ancestor of ``snapshot_id`` has ``ancestor_parent_snapshot_id`` as its parent.
-
-    This is used to validate an exclusive "from" snapshot for an incremental scan: the start snapshot
-    is exclusive, so it only needs to be the parent of some ancestor of the end snapshot, not an ancestor
-    itself. This admits start snapshots that have since been expired from the table metadata.
-    """
+    """Return whether any ancestor of ``snapshot_id`` has ``ancestor_parent_snapshot_id`` as its parent."""
     snapshot = table_metadata.snapshot_by_id(snapshot_id)
     if snapshot is None:
         return False

tests/table/test_init.py

@@ -395,7 +395,7 @@ def test_incremental_append_scan_invalid_to_snapshot(table_v2: Table) -> None:
         (42, 3055729675574597004, "Starting snapshot .exclusive. 42 is not a parent ancestor"),
         # 'from' and 'to' reversed (newer used as exclusive start).
         (3055729675574597004, 3051729675574597004, "is not a parent ancestor of end snapshot"),
-        # Equal from/to: a snapshot is never its own parent ancestor (matches iceberg-java).
+        # Equal from/to: a snapshot is never its own parent ancestor.
         (3055729675574597004, 3055729675574597004, "is not a parent ancestor of end snapshot"),
     ],
 )