Skip CDC tests on pyarrow < 21, fix stale comment

The CDC tests raised ImportError on pyarrow 18-20, which pyproject
still declares as supported.

Author: kszucs

mkdocs/docs/configuration.md

@@ -85,9 +85,9 @@ Iceberg tables support table properties to configure table behavior.
 | `write.parquet.page-size-bytes`          | Size in bytes                      | 1MB                        | Set a target threshold for the approximate encoded size of data pages within a column chunk                                                          |
 | `write.parquet.page-row-limit`           | Number of rows                     | 20000                      | Set a target threshold for the maximum number of rows within a column chunk                                                                          |
 | `write.parquet.dict-size-bytes`          | Size in bytes                      | 2MB                        | Set the dictionary page size limit per row group                                                                                                     |
-| `write.parquet.content-defined-chunking.enabled` | Boolean                    | False                      | Enables content-defined chunking (CDC) for the Parquet writer, which produces stable page boundaries across appends. Requires `pyarrow>=21.0.0`, and raises at write time on older versions.     |
-| `write.parquet.content-defined-chunking.min-chunk-size` | Size in bytes       | 256KiB (262144)            | The minimum chunk size used for content-defined chunking                                                                                             |
-| `write.parquet.content-defined-chunking.max-chunk-size` | Size in bytes       | 1MiB (1048576)             | The maximum chunk size used for content-defined chunking                                                                                             |
+| `write.parquet.content-defined-chunking.enabled` | Boolean                    | False                      | Enables content-defined chunking (CDC) for the Parquet writer, which produces stable page boundaries across appends. Requires `pyarrow>=21.0.0`; raises at write time on older versions.     |
+| `write.parquet.content-defined-chunking.min-chunk-size` | Size in bytes       | 256KiB                     | The minimum chunk size used for content-defined chunking                                                                                             |
+| `write.parquet.content-defined-chunking.max-chunk-size` | Size in bytes       | 1MiB                       | The maximum chunk size used for content-defined chunking                                                                                             |
 | `write.parquet.content-defined-chunking.norm-level` | Integer                 | 0                          | The normalization level for content-defined chunking, controlling how tightly chunk sizes cluster around the average                                |
 | `write.metadata.previous-versions-max`   | Integer                            | 100                        | The max number of previous version metadata files to keep before deleting after commit.                                                              |
 | `write.metadata.delete-after-commit.enabled` | Boolean                        | False                      | Whether to automatically delete old *tracked* metadata files after each table commit. It will retain a number of the most recent metadata files, which can be set using property `write.metadata.previous-versions-max`. |

pyiceberg/io/pyarrow.py

@@ -2939,7 +2939,7 @@ def _get_parquet_writer_kwargs(table_properties: Properties) -> dict[str, Any]:
     if compression_codec == ICEBERG_UNCOMPRESSED_CODEC:
         compression_codec = PYARROW_UNCOMPRESSED_CODEC
 
-    parquet_writer_kwargs = {
+    parquet_writer_kwargs: dict[str, Any] = {
         "compression": compression_codec,
         "compression_level": compression_level,
         "data_page_size": property_as_int(
@@ -2959,17 +2959,15 @@ def _get_parquet_writer_kwargs(table_properties: Properties) -> dict[str, Any]:
         ),
     }
 
-    # Unlike the properties above, which PyArrow's writer never supports and are safe to silently
-    # drop, CDC is a version-gated feature: silently ignoring it would produce a table that no longer
-    # has the content-defined chunk boundaries the user explicitly asked for, so this raises instead.
+    # Unlike the unsupported options warned about above, a CDC request must not be dropped:
+    # writing without the requested chunk boundaries silently defeats the point, so raise instead.
     if property_as_bool(
         properties=table_properties,
         property_name=TableProperties.PARQUET_CDC_ENABLED,
         default=TableProperties.PARQUET_CDC_ENABLED_DEFAULT,
     ):
         _require_pyarrow_version("21.0.0", "Parquet content-defined chunking")
-        # PyArrow itself validates these values (e.g. max-chunk-size > min-chunk-size) and raises a
-        # clear OSError, so there's no need to duplicate that validation here.
+        # PyArrow validates these values itself (e.g. max-chunk-size > min-chunk-size).
         parquet_writer_kwargs["use_content_defined_chunking"] = {
             "min_chunk_size": property_as_int(
                 properties=table_properties,

tests/io/test_pyarrow.py

@@ -127,6 +127,11 @@
     reason="Requires pyarrow version >= 20.0.0",
 )
 
+skip_if_pyarrow_too_old_for_cdc = pytest.mark.skipif(
+    version.parse(pyarrow.__version__) < version.parse("21.0.0"),
+    reason="Requires pyarrow version >= 21.0.0",
+)
+
 
 def test_pyarrow_infer_local_fs_from_path() -> None:
     """Test path with `file` scheme and no scheme both use LocalFileSystem"""
@@ -5469,22 +5474,24 @@ def test_dictionary_columns_produces_dict_encoded_output(tmpdir: str) -> None:
     "table_properties,expected",
     [
         ({}, None),
-        (
+        pytest.param(
             {TableProperties.PARQUET_CDC_ENABLED: "true"},
             {
                 "min_chunk_size": TableProperties.PARQUET_CDC_MIN_CHUNK_SIZE_DEFAULT,
                 "max_chunk_size": TableProperties.PARQUET_CDC_MAX_CHUNK_SIZE_DEFAULT,
                 "norm_level": TableProperties.PARQUET_CDC_NORM_LEVEL_DEFAULT,
             },
+            marks=skip_if_pyarrow_too_old_for_cdc,
         ),
-        (
+        pytest.param(
             {
                 TableProperties.PARQUET_CDC_ENABLED: "true",
                 TableProperties.PARQUET_CDC_MIN_CHUNK_SIZE: "4096",
                 TableProperties.PARQUET_CDC_MAX_CHUNK_SIZE: "8192",
                 TableProperties.PARQUET_CDC_NORM_LEVEL: "2",
             },
             {"min_chunk_size": 4096, "max_chunk_size": 8192, "norm_level": 2},
+            marks=skip_if_pyarrow_too_old_for_cdc,
         ),
     ],
 )
@@ -5499,6 +5506,7 @@ def test_get_parquet_writer_kwargs_cdc_enabled_unsupported_pyarrow_version(monke
         _get_parquet_writer_kwargs({TableProperties.PARQUET_CDC_ENABLED: "true"})
 
 
+@skip_if_pyarrow_too_old_for_cdc
 def test_get_parquet_writer_kwargs_cdc_invalid_chunk_sizes_raises_from_pyarrow() -> None:
     """PyArrow validates min/max chunk sizes itself; pyiceberg doesn't duplicate that check."""
     kwargs = _get_parquet_writer_kwargs(
@@ -5514,6 +5522,7 @@ def test_get_parquet_writer_kwargs_cdc_invalid_chunk_sizes_raises_from_pyarrow()
             writer.write_table(table)
 
 
+@skip_if_pyarrow_too_old_for_cdc
 def test_write_file_with_content_defined_chunking_enabled(tmp_path: Path) -> None:
     """Writing a table with CDC enabled should forward use_content_defined_chunking to pq.ParquetWriter."""
     from pyiceberg.table import WriteTask