refactor: update snapshot expiration method calls for consistency and clarity

Author: ForeverAngry

mkdocs/docs/api.md

@@ -1363,12 +1363,12 @@ def cleanup_old_snapshots(table_name: str, snapshot_ids: list[int]):
     """Remove specific snapshots from a table."""
     catalog = load_catalog("production")
     table = catalog.load_table(table_name)
-    
+
     # Use context manager for safe transaction handling
     with table.maintenance.expire_snapshots() as expire:
         for snapshot_id in snapshot_ids:
             expire.by_id(snapshot_id)
-    
+
     print(f"Expired {len(snapshot_ids)} snapshots from {table_name}")
 
 # Usage
@@ -1384,17 +1384,6 @@ The maintenance API leverages Iceberg's transaction system:
 - **Rollback**: If an error occurs in a context manager, changes are automatically rolled back
 - **Atomic Operations**: All operations within a single transaction are applied atomically
 
-<!-- prettier-ignore-start -->
-
-!!! note "Future Maintenance Operations"
-    The maintenance API is designed to be extensible. Future versions may include additional maintenance operations such as:
-    
-    * `table.maintenance.compact_data()` - Data file compaction
-    * `table.maintenance.optimize_metadata()` - Metadata optimization
-    * `table.maintenance.rewrite_manifests()` - Manifest rewriting
-
-<!-- prettier-ignore-end -->
-
 ## Views
 
 PyIceberg supports view operations.

pyiceberg/table/inspect.py

@@ -706,4 +706,4 @@ def all_data_files(self) -> "pa.Table":
         return self._all_files({DataFileContent.DATA})
 
     def all_delete_files(self) -> "pa.Table":
-        return self._all_files({DataFileContent.POSITION_DELETES, DataFileContent.EQUALITY_DELETES})
+        return self._all_files({DataFileContent.POSITION_DELETES, DataFileContent.EQUALITY_DELETES})

pyiceberg/table/update/snapshot.py

@@ -985,7 +985,7 @@ def by_ids(self, snapshot_ids: List[int]) -> "ExpireSnapshots":
             This for method chaining.
         """
         for snapshot_id in snapshot_ids:
-            self.expire_snapshot_by_id(snapshot_id)
+            self.by_id(snapshot_id)
         return self
 
     def older_than(self, timestamp_ms: int) -> "ExpireSnapshots":
@@ -1002,4 +1002,4 @@ def older_than(self, timestamp_ms: int) -> "ExpireSnapshots":
         for snapshot in self._transaction.table_metadata.snapshots:
             if snapshot.timestamp_ms < timestamp_ms and snapshot.snapshot_id not in protected_ids:
                 self._snapshot_ids_to_expire.add(snapshot.snapshot_id)
-        return self
+        return self

tests/table/test_expire_snapshots.py

@@ -42,8 +42,8 @@ def test_cannot_expire_protected_head_snapshot(table_v2: Table) -> None:
     assert any(ref.snapshot_id == HEAD_SNAPSHOT for ref in table_v2.metadata.refs.values())
 
     # Attempt to expire the HEAD snapshot and expect a ValueError
-    with pytest.raises(ValueError, match=f"Snapshot with ID {HEAD_SNAPSHOT} is protected and cannot be expired."):
-        table_v2.expire_snapshots().expire_snapshot_by_id(HEAD_SNAPSHOT).commit()
+    with pytest.raises(ValueError, match=f"Cannot expire snapshot {HEAD_SNAPSHOT} as it is referenced by a branch or tag."):
+        table_v2.maintenance.expire_snapshots().by_id(HEAD_SNAPSHOT).commit()
 
     table_v2.catalog.commit_table.assert_not_called()
 
@@ -65,8 +65,8 @@ def test_cannot_expire_tagged_snapshot(table_v2: Table) -> None:
     )
     assert any(ref.snapshot_id == TAGGED_SNAPSHOT for ref in table_v2.metadata.refs.values())
 
-    with pytest.raises(ValueError, match=f"Snapshot with ID {TAGGED_SNAPSHOT} is protected and cannot be expired."):
-        table_v2.expire_snapshots().expire_snapshot_by_id(TAGGED_SNAPSHOT).commit()
+    with pytest.raises(ValueError, match=f"Cannot expire snapshot {TAGGED_SNAPSHOT} as it is referenced by a branch or tag."):
+        table_v2.maintenance.expire_snapshots().by_id(TAGGED_SNAPSHOT).commit()
 
     table_v2.catalog.commit_table.assert_not_called()
 
@@ -98,7 +98,7 @@ def test_expire_unprotected_snapshot(table_v2: Table) -> None:
     assert all(ref.snapshot_id != EXPIRE_SNAPSHOT for ref in table_v2.metadata.refs.values())
 
     # Expire the snapshot
-    table_v2.expire_snapshots().expire_snapshot_by_id(EXPIRE_SNAPSHOT).commit()
+    table_v2.maintenance.expire_snapshots().by_id(EXPIRE_SNAPSHOT).commit()
 
     table_v2.catalog.commit_table.assert_called_once()
     remaining_snapshots = table_v2.metadata.snapshots
@@ -114,7 +114,7 @@ def test_expire_nonexistent_snapshot_raises(table_v2: Table) -> None:
     table_v2.metadata = table_v2.metadata.model_copy(update={"refs": {}})
 
     with pytest.raises(ValueError, match=f"Snapshot with ID {NONEXISTENT_SNAPSHOT} does not exist."):
-        table_v2.expire_snapshots().expire_snapshot_by_id(NONEXISTENT_SNAPSHOT).commit()
+        table_v2.maintenance.expire_snapshots().by_id(NONEXISTENT_SNAPSHOT).commit()
 
     table_v2.catalog.commit_table.assert_not_called()
 
@@ -152,7 +152,7 @@ def test_expire_snapshots_by_timestamp_skips_protected(table_v2: Table) -> None:
     )
     table_v2.catalog.commit_table.return_value = mock_response
 
-    table_v2.expire_snapshots().expire_snapshots_older_than(future_timestamp).commit()
+    table_v2.maintenance.expire_snapshots().older_than(future_timestamp).commit()
     # Update metadata to reflect the commit (as in other tests)
     table_v2.metadata = mock_response.metadata
 
@@ -215,10 +215,10 @@ def test_expire_snapshots_by_ids(table_v2: Table) -> None:
     assert all(ref.snapshot_id not in (EXPIRE_SNAPSHOT_1, EXPIRE_SNAPSHOT_2) for ref in table_v2.metadata.refs.values())
 
     # Expire the snapshots
-    table_v2.expire_snapshots().expire_snapshots_by_ids([EXPIRE_SNAPSHOT_1, EXPIRE_SNAPSHOT_2]).commit()
+    table_v2.maintenance.expire_snapshots().by_ids([EXPIRE_SNAPSHOT_1, EXPIRE_SNAPSHOT_2]).commit()
 
     table_v2.catalog.commit_table.assert_called_once()
     remaining_snapshots = table_v2.metadata.snapshots
     assert EXPIRE_SNAPSHOT_1 not in remaining_snapshots
     assert EXPIRE_SNAPSHOT_2 not in remaining_snapshots
-    assert len(table_v2.metadata.snapshots) == 1
+    assert len(table_v2.metadata.snapshots) == 1