REST: Rename rest-scan-planning-enabled to scan-planning-mode (#3376)

# Rationale for this change

Boolean properties should be avoided as much as possible. 
We may consider introducing a new scan planning mode in the future.

The Java implementation has already changed from
`rest-scan-planning-enabled` to `scan-planning-mode` in
apache/iceberg#15572.

## Are these changes tested?

Yes.

## Are there any user-facing changes?

Rename `rest-scan-planning-enabled` to `scan-planning-mode`.

<!-- In the case of user-facing changes, please add the changelog label.
-->

Author: ebyhr

pyiceberg/catalog/rest/__init__.py

@@ -225,6 +225,11 @@ class IdentifierKind(Enum):
     VIEW = "view"
 
 
+class ScanPlanningMode(Enum):
+    CLIENT = "client"
+    SERVER = "server"
+
+
 ACCESS_DELEGATION_DEFAULT = "vended-credentials"
 AUTHORIZATION_HEADER = "Authorization"
 BEARER_PREFIX = "Bearer"
@@ -255,8 +260,8 @@ class IdentifierKind(Enum):
 SNAPSHOT_LOADING_MODE = "snapshot-loading-mode"
 AUTH = "auth"
 CUSTOM = "custom"
-REST_SCAN_PLANNING_ENABLED = "rest-scan-planning-enabled"
-REST_SCAN_PLANNING_ENABLED_DEFAULT = False
+SCAN_PLANNING_MODE = "scan-planning-mode"
+SCAN_PLANNING_MODE_DEFAULT = ScanPlanningMode.CLIENT.value
 # for backwards compatibility with older REST servers where it can be assumed that a particular
 # server supports view endpoints but doesn't send the "endpoints" field in the ConfigResponse
 VIEW_ENDPOINTS_SUPPORTED = "view-endpoints-supported"
@@ -480,9 +485,8 @@ def _load_file_io(self, properties: Properties = EMPTY_DICT, location: str | Non
     @override
     def supports_server_side_planning(self) -> bool:
         """Check if the catalog supports server-side scan planning."""
-        return Capability.V1_SUBMIT_TABLE_SCAN_PLAN in self._supported_endpoints and property_as_bool(
-            self.properties, REST_SCAN_PLANNING_ENABLED, REST_SCAN_PLANNING_ENABLED_DEFAULT
-        )
+        scan_planning_mode = ScanPlanningMode(self.properties.get(SCAN_PLANNING_MODE, SCAN_PLANNING_MODE_DEFAULT))
+        return Capability.V1_SUBMIT_TABLE_SCAN_PLAN in self._supported_endpoints and scan_planning_mode == ScanPlanningMode.SERVER
 
     @retry(**_RETRY_ARGS)
     def _plan_table_scan(self, identifier: str | Identifier, request: PlanTableScanRequest) -> PlanningResponse:

tests/catalog/test_rest.py

@@ -42,6 +42,7 @@
     Endpoint,
     HttpMethod,
     RestCatalog,
+    ScanPlanningMode,
 )
 from pyiceberg.exceptions import (
     AuthorizationExpiredError,
@@ -2546,7 +2547,7 @@ def test_server_side_planning_enabled_by_property(self, rest_mock: Mocker) -> No
             "rest",
             uri=TEST_URI,
             token=TEST_TOKEN,
-            **{"rest-scan-planning-enabled": "true"},
+            **{"scan-planning-mode": ScanPlanningMode.SERVER.value},
         )
 
         assert catalog.supports_server_side_planning() is True
@@ -2562,7 +2563,7 @@ def test_server_side_planning_disabled_when_endpoint_unsupported(self, requests_
             "rest",
             uri=TEST_URI,
             token=TEST_TOKEN,
-            **{"rest-scan-planning-enabled": "true"},
+            **{"scan-planning-mode": ScanPlanningMode.SERVER.value},
         )
 
         assert catalog.supports_server_side_planning() is False
@@ -2572,7 +2573,7 @@ def test_server_side_planning_explicitly_disabled(self, rest_mock: Mocker) -> No
             "rest",
             uri=TEST_URI,
             token=TEST_TOKEN,
-            **{"rest-scan-planning-enabled": "false"},
+            **{"scan-planning-mode": ScanPlanningMode.CLIENT.value},
         )
 
         assert catalog.supports_server_side_planning() is False
@@ -2581,7 +2582,7 @@ def test_server_side_planning_enabled_from_server_config(self, rest_mock: Mocker
         rest_mock.get(
             f"{TEST_URI}v1/config",
             json={
-                "defaults": {"rest-scan-planning-enabled": "true"},
+                "defaults": {"scan-planning-mode": "server"},
                 "overrides": {},
                 "endpoints": ["POST /v1/{prefix}/namespaces/{namespace}/tables/{table}/plan"],
             },