From aea08ec262eff0218231215c1dd1d8129761832b Mon Sep 17 00:00:00 2001
From: BharatDeva <278575558+BharatDeva@users.noreply.github.com>
Date: Fri, 8 May 2026 19:25:13 -0500
Subject: [PATCH] docs: clarify table write API docstrings

---
 pyiceberg/table/__init__.py | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/pyiceberg/table/__init__.py b/pyiceberg/table/__init__.py
index b8d87143c9..61ccedd313 100644
--- a/pyiceberg/table/__init__.py
+++ b/pyiceberg/table/__init__.py
@@ -1378,7 +1378,7 @@ def append(self, df: pa.Table, snapshot_properties: dict[str, str] = EMPTY_DICT,
         Shorthand API for appending a PyArrow table to the table.
 
         Args:
-            df: The Arrow dataframe that will be appended to overwrite the table
+            df: The Arrow dataframe that will be appended to the table
             snapshot_properties: Custom properties to be added to the snapshot summary
             branch: Branch Reference to run the append operation
         """
@@ -1466,6 +1466,9 @@ def add_files(
 
         Args:
             file_paths: The list of full file paths to be added as data files to the table
+            snapshot_properties: Custom properties to be added to the snapshot summary
+            check_duplicate_files: Whether to check if the files are already present in the table
+            branch: Branch Reference to run the add-files operation
 
         Raises:
             FileNotFoundError: If the file does not exist.
@@ -1479,6 +1482,11 @@ def add_files(
             )
 
     def update_spec(self, case_sensitive: bool = True) -> UpdateSpec:
+        """Create a new UpdateSpec to update the partitioning of the table.
+
+        Args:
+            case_sensitive: Whether column name matching should be case-sensitive.
+        """
         return UpdateSpec(Transaction(self, autocommit=True), case_sensitive=case_sensitive)
 
     def refs(self) -> dict[str, SnapshotRef]: