fixup! Add new standards for deprecating APIs

Author: ndrluis

Diff for: mkdocs/docs/contributing.md

@@ -186,7 +186,7 @@ Optionally, include a recommendation to guide users toward an alternative featur
 ```python
 from pyiceberg.utils._deprecations import deprecated
 
-@deprecated("1.5.0", "2.0.0", topic="Use `new_function` instead.")
+@deprecated("1.5.0", "2.0.0", addendum="Use `new_function` instead.")
 def old_function():
     pass
 ```
@@ -281,7 +281,7 @@ def some_function():
     # some logic
 
     if condition:
-        deprecated.topic("1.5.0", "2.0.0", topic="The <TOPIC>")
+        deprecated.topic("1.5.0", "2.0.0", addendum="The <TOPIC>")
 
     # more logic
 ```

Diff for: pyiceberg/catalog/__init__.py

@@ -633,7 +633,7 @@ def drop_view(self, identifier: Union[str, Identifier]) -> None:
     @deprecated(
         deprecate_in="0.8.0",
         remove_in="0.9.0",
-        topic="Please refer to the table using only its namespace and its table name.",
+        addendum="Please refer to the table using only its namespace and its table name.",
     )
     def identifier_to_tuple_without_catalog(self, identifier: Union[str, Identifier]) -> Identifier:
         """Convert an identifier to a tuple and drop this catalog's name from the first element.
@@ -664,7 +664,7 @@ def _identifier_to_tuple_without_catalog(self, identifier: Union[str, Identifier
                 deprecate_in="0.8.0",
                 remove_in="0.9.0",
                 prefix="Support for parsing catalog level identifier in Catalog identifiers",
-                topic="Please refer to the table using only its namespace and its table name.",
+                addendum="Please refer to the table using only its namespace and its table name.",
             )
             identifier_tuple = identifier_tuple[1:]
         return identifier_tuple
@@ -787,7 +787,7 @@ def __init__(self, name: str, **properties: str):
                 deprecate_in="0.8.0",
                 remove_in="0.9.0",
                 prefix=f"The property {DEPRECATED_BOTOCORE_SESSION}",
-                topic="and will be removed.",
+                addendum="and will be removed.",
             )
 
     def create_table_transaction(

Diff for: pyiceberg/catalog/rest.py

@@ -322,7 +322,7 @@ def auth_url(self) -> str:
                 deprecate_in="0.8.0",
                 remove_in="0.9.0",
                 prefix=f"The property {AUTH_URL}",
-                topic=f"Please use {OAUTH2_SERVER_URI} instead",
+                addendum=f"Please use {OAUTH2_SERVER_URI} instead",
             )
 
         self._warn_oauth_tokens_deprecation()
@@ -343,7 +343,7 @@ def _warn_oauth_tokens_deprecation(self) -> None:
                 deprecate_in="0.8.0",
                 remove_in="1.0.0",
                 prefix="Default OAuth2 endpoint",
-                topic="Iceberg REST client is missing the OAuth2 server URI "
+                addendum="Iceberg REST client is missing the OAuth2 server URI "
                 f"configuration and defaults to {self.uri}{Endpoints.get_token}. "
                 "This automatic fallback will be removed in a future Iceberg release."
                 f"It is recommended to configure the OAuth2 endpoint using the '{OAUTH2_SERVER_URI}'"

Diff for: pyiceberg/cli/console.py

@@ -40,15 +40,15 @@
 deprecated.constant(
     deprecate_in="0.8.0",
     remove_in="0.9.0",
-    topic="Use TableProperties.MAX_SNAPSHOT_AGE_MS_DEFAULT instead.",
+    addendum="Use TableProperties.MAX_SNAPSHOT_AGE_MS_DEFAULT instead.",
     constant="DEFAULT_MAX_SNAPSHOT_AGE_MS",
     value=TableProperties.MAX_SNAPSHOT_AGE_MS_DEFAULT,
 )
 
 deprecated.constant(
     deprecate_in="0.8.0",
     remove_in="0.9.0",
-    topic="Use TableProperties.MIN_SNAPSHOTS_TO_KEEP_DEFAULT instead.",
+    addendum="Use TableProperties.MIN_SNAPSHOTS_TO_KEEP_DEFAULT instead.",
     constant="DEFAULT_MIN_SNAPSHOTS_TO_KEEP",
     value=TableProperties.MIN_SNAPSHOTS_TO_KEEP_DEFAULT,
 )

Diff for: pyiceberg/expressions/parser.py

@@ -94,7 +94,7 @@ def _(result: ParseResults) -> Reference:
             deprecate_in="0.8.0",
             remove_in="0.9.0",
             prefix="Parsing expressions with table name",
-            topic="Only provide field names in the row_filter.",
+            addendum="Only provide field names in the row_filter.",
         )
     # TODO: Once this is removed, we will no longer take just the last index of parsed column result
     # And introduce support for parsing filter expressions with nested fields.

Diff for: pyiceberg/io/fsspec.py

@@ -177,7 +177,7 @@ def _gs(properties: Properties) -> AbstractFileSystem:
             deprecate_in="0.8.0",
             remove_in="0.9.0",
             prefix=f"The property {GCS_ENDPOINT}",
-            topic=f"please use {GCS_SERVICE_HOST} instead",
+            addendum=f"please use {GCS_SERVICE_HOST} instead",
         )
     return GCSFileSystem(
         project=properties.get(GCS_PROJECT_ID),
@@ -202,7 +202,7 @@ def _adls(properties: Properties) -> AbstractFileSystem:
                 deprecate_in="0.8.0",
                 remove_in="0.9.0",
                 prefix=f"The property {property_name}",
-                topic="Please use properties that start with adls.",
+                addendum="Please use properties that start with adls.",
             )
 
     return AzureBlobFileSystem(

Diff for: pyiceberg/io/pyarrow.py

@@ -411,7 +411,7 @@ def _initialize_fs(self, scheme: str, netloc: Optional[str] = None) -> FileSyste
                         deprecate_in="0.8.0",
                         remove_in="0.9.0",
                         prefix=f"The property {GCS_ENDPOINT}",
-                        topic=f"please use {GCS_SERVICE_HOST} instead",
+                        addendum=f"please use {GCS_SERVICE_HOST} instead",
                     )
                 url_parts = urlparse(endpoint)
                 gcs_kwargs["scheme"] = url_parts.scheme
@@ -1532,7 +1532,7 @@ def _record_batches_from_scan_tasks_and_deletes(
 @deprecated(
     deprecate_in="0.8.0",
     remove_in="0.9.0",
-    topic="Use ArrowScan.to_table instead.",
+    addendum="Use ArrowScan.to_table instead.",
 )
 def project_table(
     tasks: Iterable[FileScanTask],
@@ -1631,7 +1631,7 @@ def project_table(
 @deprecated(
     deprecate_in="0.8.0",
     remove_in="0.9.0",
-    topic="Use ArrowScan.to_record_batches instead.",
+    addendum="Use ArrowScan.to_record_batches instead.",
 )
 def project_batches(
     tasks: Iterable[FileScanTask],

Diff for: pyiceberg/table/__init__.py

@@ -785,7 +785,7 @@ def refresh(self) -> Table:
     @deprecated(
         deprecate_in="0.8.0",
         remove_in="0.9.0",
-        topic="Please use Table.name() function instead.",
+        addendum="Please use Table.name() function instead.",
     )
     def identifier(self) -> Identifier:
         """Return the identifier of this table.
@@ -1540,7 +1540,7 @@ def _parquet_files_to_data_files(table_metadata: TableMetadata, file_paths: List
 @deprecated(
     deprecate_in="0.8.0",
     remove_in="0.9.0",
-    topic="pyiceberg.table.Move has been changed to private class pyiceberg.table.update.schema._Move",
+    addendum="pyiceberg.table.Move has been changed to private class pyiceberg.table.update.schema._Move",
 )
 def Move(*args: Any, **kwargs: Any) -> _Move:
     return _Move(*args, **kwargs)
@@ -1549,7 +1549,7 @@ def Move(*args: Any, **kwargs: Any) -> _Move:
 @deprecated(
     deprecate_in="0.8.0",
     remove_in="0.9.0",
-    topic="pyiceberg.table.MoveOperation has been changed to private class pyiceberg.table.update.schema._MoveOperation",
+    addendum="pyiceberg.table.MoveOperation has been changed to private class pyiceberg.table.update.schema._MoveOperation",
 )
 def MoveOperation(*args: Any, **kwargs: Any) -> _MoveOperation:
     return _MoveOperation(*args, **kwargs)
@@ -1558,7 +1558,7 @@ def MoveOperation(*args: Any, **kwargs: Any) -> _MoveOperation:
 @deprecated(
     deprecate_in="0.8.0",
     remove_in="0.9.0",
-    topic="pyiceberg.table.DeleteFiles has been changed to private class pyiceberg.table.update.snapshot._DeleteFiles",
+    addendum="pyiceberg.table.DeleteFiles has been changed to private class pyiceberg.table.update.snapshot._DeleteFiles",
 )
 def DeleteFiles(*args: Any, **kwargs: Any) -> _DeleteFiles:
     return _DeleteFiles(*args, **kwargs)
@@ -1567,7 +1567,7 @@ def DeleteFiles(*args: Any, **kwargs: Any) -> _DeleteFiles:
 @deprecated(
     deprecate_in="0.8.0",
     remove_in="0.9.0",
-    topic="pyiceberg.table.FastAppendFiles has been changed to private class pyiceberg.table.update.snapshot._FastAppendFiles",
+    addendum="pyiceberg.table.FastAppendFiles has been changed to private class pyiceberg.table.update.snapshot._FastAppendFiles",
 )
 def FastAppendFiles(*args: Any, **kwargs: Any) -> _FastAppendFiles:
     return _FastAppendFiles(*args, **kwargs)
@@ -1576,7 +1576,7 @@ def FastAppendFiles(*args: Any, **kwargs: Any) -> _FastAppendFiles:
 @deprecated(
     deprecate_in="0.8.0",
     remove_in="0.9.0",
-    topic="pyiceberg.table.MergeAppendFiles has been changed to private class pyiceberg.table.update.snapshot._MergeAppendFiles",
+    addendum="pyiceberg.table.MergeAppendFiles has been changed to private class pyiceberg.table.update.snapshot._MergeAppendFiles",
 )
 def MergeAppendFiles(*args: Any, **kwargs: Any) -> _MergeAppendFiles:
     return _MergeAppendFiles(*args, **kwargs)
@@ -1585,7 +1585,7 @@ def MergeAppendFiles(*args: Any, **kwargs: Any) -> _MergeAppendFiles:
 @deprecated(
     deprecate_in="0.8.0",
     remove_in="0.9.0",
-    topic="pyiceberg.table.OverwriteFiles has been changed to private class pyiceberg.table.update.snapshot._OverwriteFiles",
+    addendum="pyiceberg.table.OverwriteFiles has been changed to private class pyiceberg.table.update.snapshot._OverwriteFiles",
 )
 def OverwriteFiles(*args: Any, **kwargs: Any) -> _OverwriteFiles:
     return _OverwriteFiles(*args, **kwargs)

Diff for: pyiceberg/table/name_mapping.py

@@ -78,7 +78,7 @@ def _field_by_name(self) -> Dict[str, MappedField]:
     @deprecated(
         deprecate_in="0.8.0",
         remove_in="0.9.0",
-        topic="Please use `apply_name_mapping` instead",
+        addendum="Please use `apply_name_mapping` instead",
     )
     def find(self, *names: str) -> MappedField:
         name = ".".join(names)

Diff for: pyiceberg/table/update/__init__.py

@@ -91,10 +91,11 @@ class AddSchemaUpdate(IcebergBaseModel):
     last_column_id: Optional[int] = Field(
         alias="last-column-id",
         default=None,
-        deprecated=deprecation_notice(
-            deprecated_in="0.9.0",
-            removed_in="0.10.0",
-            help_message="last-field-id is handled internally, and should not be part of the update.",
+        deprecated=deprecated.message(
+            deprecate_in="0.9.0",
+            remove_in="0.10.0",
+            prefix="last-column-id",
+            addendum="This property is handled internally, and should not be part of the update.",
         ),
     )
 
@@ -105,7 +106,7 @@ class AddSchemaUpdate(IcebergBaseModel):
             deprecate_in="0.8.0",
             remove_in="0.9.0",
             prefix="initial_change",
-            topic="CreateTableTransaction can work without this field",
+            addendum="CreateTableTransaction can work without this field",
         ),
     )
 
@@ -128,7 +129,7 @@ class AddPartitionSpecUpdate(IcebergBaseModel):
             deprecate_in="0.8.0",
             remove_in="0.9.0",
             prefix="initial_change",
-            topic="CreateTableTransaction can work without this field",
+            addendum="CreateTableTransaction can work without this field",
         ),
     )
 
@@ -151,7 +152,7 @@ class AddSortOrderUpdate(IcebergBaseModel):
             deprecate_in="0.8.0",
             remove_in="0.9.0",
             prefix="initial_change",
-            topic="CreateTableTransaction can work without this field",
+            addendum="CreateTableTransaction can work without this field",
         ),
     )