From 7cf0c225c3cdb32ac5e390de06b7b0e4fe7de92e Mon Sep 17 00:00:00 2001 From: Kev Wang Date: Wed, 9 Oct 2024 07:09:39 -0700 Subject: [PATCH] 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 38cc6221a2..1056fa525b 100644 --- a/pyiceberg/transforms.py +++ b/pyiceberg/transforms.py @@ -146,7 +146,15 @@ def can_transform(self, source: IcebergType) -> bool: 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 @@ def can_transform(self, source: IcebergType) -> bool: 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