Align upgrade path with the Java implementation

Support upgrading via the format-version table property in
set_properties, matching TableMetadata.replaceProperties in Java: the
property triggers UpgradeFormatVersionUpdate instead of being stored.
Add tests for parity with TestTableMetadata and TestRowLineageMetadata:
direct v1-to-v3 upgrade, same-version no-op, and property-based
upgrade.

Author: moomindani

pyiceberg/table/__init__.py

@@ -26,7 +26,7 @@
 from functools import cached_property
 from itertools import chain
 from types import TracebackType
-from typing import TYPE_CHECKING, Any, TypeVar
+from typing import TYPE_CHECKING, Any, TypeVar, cast
 
 from pydantic import Field
 
@@ -316,6 +316,9 @@ def set_properties(self, properties: Properties = EMPTY_DICT, **kwargs: Any) ->
 
         When a property is already set, it will be overwritten.
 
+        Setting the `format-version` property upgrades the table to that format
+        version instead of storing it as a property.
+
         Args:
             properties: The properties set on the table.
             kwargs: properties can also be pass as kwargs.
@@ -325,8 +328,12 @@ def set_properties(self, properties: Properties = EMPTY_DICT, **kwargs: Any) ->
         """
         if properties and kwargs:
             raise ValueError("Cannot pass both properties and kwargs")
-        updates = properties or kwargs
-        return self._apply((SetPropertiesUpdate(updates=updates),))
+        updates = dict(properties or kwargs)
+        if (new_format_version := updates.pop(TableProperties.FORMAT_VERSION, None)) is not None:
+            self.upgrade_table_version(format_version=cast(TableVersion, int(new_format_version)))
+        if updates:
+            return self._apply((SetPropertiesUpdate(updates=updates),))
+        return self
 
     def _set_ref_snapshot(
         self,

tests/table/test_init.py

@@ -1255,6 +1255,46 @@ def test_update_metadata_upgrade_to_v3(table_v2: Table) -> None:
     assert validated.next_row_id == 0
 
 
+def test_update_metadata_upgrade_v1_to_v3(table_v1: Table) -> None:
+    from pyiceberg.table.metadata import TableMetadataV3
+
+    new_metadata = update_table_metadata(table_v1.metadata, (UpgradeFormatVersionUpdate(format_version=3),))
+    assert isinstance(new_metadata, TableMetadataV3)
+    assert new_metadata.format_version == 3
+    assert new_metadata.next_row_id == 0
+
+    # rebuild the metadata to trigger validation
+    validated = TableMetadataUtil.parse_obj(copy(new_metadata.model_dump()))
+    assert validated.format_version == 3
+    assert validated.next_row_id == 0
+
+
+def test_update_metadata_upgrade_same_version_is_noop(table_v2: Table) -> None:
+    new_metadata = update_table_metadata(table_v2.metadata, (UpgradeFormatVersionUpdate(format_version=2),))
+    assert new_metadata == table_v2.metadata
+    assert new_metadata.format_version == 2
+
+
+def test_set_properties_format_version_upgrades(table_v2: Table) -> None:
+    transaction = table_v2.transaction()
+    transaction.set_properties({"format-version": "3", "owner": "test"})
+
+    assert transaction.table_metadata.format_version == 3
+    assert transaction.table_metadata.next_row_id == 0
+    assert transaction.table_metadata.properties["owner"] == "test"
+    assert "format-version" not in transaction.table_metadata.properties
+    assert UpgradeFormatVersionUpdate(format_version=3) in transaction._updates
+
+
+def test_set_properties_same_format_version_is_noop(table_v2: Table) -> None:
+    transaction = table_v2.transaction()
+    transaction.set_properties({"format-version": "2"})
+
+    assert transaction.table_metadata.format_version == 2
+    assert "format-version" not in transaction.table_metadata.properties
+    assert transaction._updates == ()
+
+
 def test_update_metadata_schema_immutability(
     table_v2_with_fixed_and_decimal_types: TableMetadataV2,
 ) -> None: