(iceberg-python) branch main updated: Add clarifying docs to transform result types (#1211)

[kevinjqliu]

This is an automated email from the ASF dual-hosted git repository.

kevinjqliu pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iceberg-python.git


The following commit(s) were added to refs/heads/main by this push:
     new 7cf0c225 Add clarifying docs to transform result types (#1211)
7cf0c225 is described below

commit 7cf0c225c3cdb32ac5e390de06b7b0e4fe7de92e
Author: Kev Wang <ke...@eventualcomputing.com>
AuthorDate: Wed Oct 9 07:09:39 2024 -0700

    Add clarifying docs to transform result types (#1211)
    
    * add clarifying docs to transform result types
    
    * add more context to docs
    
    * re-add fixed first line
    
    * fix lint
---
 pyiceberg/transforms.py | 17 +++++++++++++++--
 1 file changed, 15 insertions(+), 2 deletions(-)

diff --git a/pyiceberg/transforms.py b/pyiceberg/transforms.py
index 38cc6221..1056fa52 100644
--- a/pyiceberg/transforms.py
+++ b/pyiceberg/transforms.py
@@ -146,7 +146,15 @@ class Transform(IcebergRootModel[str], ABC, Generic[S, T]):
         return False
 
     @abstractmethod
-    def result_type(self, source: IcebergType) -> IcebergType: ...
+    def result_type(self, source: IcebergType) -> IcebergType:
+        """Return the `IcebergType` produced by this transform given a source 
type.
+
+        This method defines both the physical and display representation of 
the partition field.
+
+        The physical representation must conform to the Iceberg spec. The 
display representation
+        can deviate from the spec, such as by transforming the value into a 
more human-readable format.
+        """
+        ...
 
     @abstractmethod
     def project(self, name: str, pred: BoundPredicate[L]) -> 
Optional[UnboundPredicate[Any]]: ...
@@ -491,7 +499,7 @@ class DayTransform(TimeTransform[S]):
     """Transforms a datetime value into a day value.
 
     Example:
-        >>> transform = MonthTransform()
+        >>> transform = DayTransform()
         >>> transform.transform(DateType())(17501)
         17501
     """
@@ -518,6 +526,11 @@ class DayTransform(TimeTransform[S]):
         return isinstance(source, (DateType, TimestampType, TimestamptzType))
 
     def result_type(self, source: IcebergType) -> IcebergType:
+        """Return the result type of a day transform.
+
+        The physical representation conforms to the Iceberg spec as DateType 
is internally converted to int.
+        The DateType returned here provides a more human-readable way to 
display the partition field.
+        """
         return DateType()
 
     @property