fixup! Add new standards for deprecating APIs

Author: ndrluis

mkdocs/docs/contributing.md

@@ -168,15 +168,19 @@ To deprecate functions, methods, or properties, use the `@deprecated` decorator.
 ```python
 from pyiceberg.utils._deprecations import deprecated
 
+
 @deprecated("1.5.0", "2.0.0")
 def old_function():
     pass
+
+
+old_function()
 ```
 
 This will warn:
 
 ```text
-Call to old_function, deprecated in 1.5.0, will be removed in 2.0.0.
+some_file.py:9: DeprecationWarning: __main__.old_function is deprecated and will be removed in 2.0.0.
 ```
 
 #### Adding a Recommendation
@@ -186,15 +190,19 @@ 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", addendum="Use `new_function` instead.")
 def old_function():
     pass
+
+
+old_function()
 ```
 
 This will warn:
 
 ```text
-Call to old_function, deprecated in 1.5.0, will be removed in 2.0.0. Use `new_function` instead.
+some_file.py:9: DeprecationWarning: __main__.old_function is deprecated and will be removed in 2.0.0. Use `new_function` instead.
 ```
 
 ### Keyword Arguments
@@ -206,31 +214,39 @@ To deprecate or rename keyword arguments, use the `@deprecated.argument` decorat
 ```python
 from pyiceberg.utils._deprecations import deprecated
 
+
 @deprecated.argument("1.5.0", "2.0.0", "old_arg")
 def my_function(*, old_arg=True):
     pass
+
+
+my_function(old_arg=False)
 ```
 
 This will warn:
 
 ```text
-Call to my_function(old_arg), deprecated in 1.5.0, will be removed in 2.0.0.
+some_file.py:9: DeprecationWarning: __main__.my_function(old_arg) is deprecated and will be removed in 2.0.0.
 ```
 
 #### Renaming a Keyword Argument
 
 ```python
 from pyiceberg.utils._deprecations import deprecated
 
+
 @deprecated.argument("1.5.0", "2.0.0", "old_arg", rename="new_arg")
 def my_function(*, new_arg=True):
     pass
+
+
+my_function(old_arg=False)
 ```
 
 This will warn:
 
 ```text
-Call to my_function(old_arg), deprecated in 1.5.0, will be removed in 2.0.0. Use `new_arg` instead.
+some_file.py:9: DeprecationWarning: __main__.my_function(old_arg) is deprecated and will be removed in 2.0.0. Use 'new_arg' instead.
 ```
 
 ### Constants and Enums
@@ -240,34 +256,45 @@ To deprecate constants or enums, use the `deprecated.constant` function.
 #### Deprecating a Constant
 
 ```python
+# some_file.py
 from pyiceberg.utils._deprecations import deprecated
 
 deprecated.constant("1.5.0", "2.0.0", "OLD_CONSTANT", 42)
+
+# deprecated_constant.py
+from some_file import OLD_CONSTANT
+
+OLD_CONSTANT
 ```
 
 This will warn:
 
 ```text
-OLD_CONSTANT, deprecated in 1.5.0, will be removed in 2.0.0.
+deprecated_constant.py:3: DeprecationWarning: some_file.OLD_CONSTANT is deprecated and will be removed in 2.0.0.
 ```
 
 #### Deprecating an Enum
 
 ```python
+# some_file.py
 from enum import Enum
 from pyiceberg.utils._deprecations import deprecated
 
 class MyEnum(Enum):
     OLD_VALUE = 42
 
 deprecated.constant("1.5.0", "2.0.0", "MyEnum", MyEnum)
+
 del MyEnum
+
+# deprecated_enum.py
+from some_file import MyEnum
 ```
 
 This will warn:
 
 ```text
-MyEnum, deprecated in 1.5.0, will be removed in 2.0.0.
+deprecated_constant.py:1: DeprecationWarning: some_file.MyEnum is deprecated and will be removed in 2.0.0.
 ```
 
 ### Topics
@@ -277,19 +304,20 @@ For deprecations that do not fit into the above categories, use the `deprecated.
 ```python
 from pyiceberg.utils._deprecations import deprecated
 
+
 def some_function():
     # some logic
 
     if condition:
-        deprecated.topic("1.5.0", "2.0.0", addendum="The <TOPIC>")
+        deprecated.topic("1.5.0", "2.0.0", prefix="The behaviour xyz", addendum="Do something else.")
 
     # more logic
 ```
 
 This will warn:
 
 ```text
-The <TOPIC>, deprecated in 1.5.0, will be removed in 2.0.0.
+some_file.py:8: DeprecationWarning: The behaviour xyz is deprecated and will be removed in 2.0.0. Do something else.
 ```
 
 ## Type annotations

pyiceberg/utils/_deprecations.py

@@ -40,7 +40,7 @@
 
 if TYPE_CHECKING:
     from argparse import ArgumentParser, Namespace
-    from typing import Any, Callable, ParamSpec, Self, TypeVar
+    from typing import Any, Callable, ParamSpec, TypeVar
 
     T = TypeVar("T")
     P = ParamSpec("P")
@@ -61,7 +61,7 @@ class DeprecationHandler:
     _version_tuple: tuple[int, ...] | None
     _version_object: Version | None
 
-    def __init__(self: Self, version: str) -> None:
+    def __init__(self, version: str) -> None:
         """Create a deprecation handle for the specified version.
 
         :param version: The version to compare against when checking deprecation statuses.
@@ -93,7 +93,7 @@ def _version_less_than(self, version: str) -> bool:
         return self._version < target_version
 
     def __call__(
-        self: Self,
+        self,
         deprecate_in: str,
         remove_in: str,
         *,
@@ -138,7 +138,7 @@ def inner(*args: P.args, **kwargs: P.kwargs) -> T:
         return deprecated_decorator
 
     def argument(
-        self: Self,
+        self,
         deprecate_in: str,
         remove_in: str,
         argument: str,
@@ -195,7 +195,7 @@ def inner(*args: P.args, **kwargs: P.kwargs) -> T:
         return deprecated_decorator
 
     def action(
-        self: Self,
+        self,
         deprecate_in: str,
         remove_in: str,
         action: ActionType,
@@ -210,7 +210,7 @@ class DeprecationMixin(Action):
             category: type[Warning]
             help: str  # override argparse.Action's help type annotation
 
-            def __init__(inner_self: Self, *args: Any, **kwargs: Any) -> None:
+            def __init__(inner_self, *args: Any, **kwargs: Any) -> None:
                 super().__init__(*args, **kwargs)
 
                 category, message = self._generate_message(
@@ -236,7 +236,7 @@ def __init__(inner_self: Self, *args: Any, **kwargs: Any) -> None:
                 inner_self.help = message
 
             def __call__(
-                inner_self: Self,
+                inner_self,
                 parser: ArgumentParser,
                 namespace: Namespace,
                 values: Any,
@@ -258,7 +258,7 @@ def __call__(
         return type(action.__name__, (DeprecationMixin, action), {})  # type: ignore[return-value]
 
     def module(
-        self: Self,
+        self,
         deprecate_in: str,
         remove_in: str,
         *,
@@ -281,7 +281,7 @@ def module(
         )
 
     def constant(
-        self: Self,
+        self,
         deprecate_in: str,
         remove_in: str,
         constant: str,
@@ -323,7 +323,7 @@ def __getattr__(name: str) -> Any:
                 with warnings.catch_warnings():  # temporarily override warning handling
                     warnings.simplefilter("always", category)  # turn off filter
 
-                    warnings.warn(message, category, stacklevel=3 + stack)
+                    warnings.warn(message, category, stacklevel=2 + stack)
                 return value
 
             if super_getattr:
@@ -334,7 +334,7 @@ def __getattr__(name: str) -> Any:
         module.__getattr__ = __getattr__  # type: ignore[method-assign]
 
     def topic(
-        self: Self,
+        self,
         deprecate_in: str,
         remove_in: str,
         *,
@@ -371,7 +371,7 @@ def topic(
 
             warnings.warn(message, category, stacklevel=2 + stack)
 
-    def _get_module(self: Self, stack: int) -> tuple[ModuleType, str]:
+    def _get_module(self, stack: int) -> tuple[ModuleType, str]:
         """Detect the module from which we are being called.
 
         :param stack: The stacklevel increment.
@@ -408,7 +408,7 @@ def _get_module(self: Self, stack: int) -> tuple[ModuleType, str]:
         raise DeprecatedError("unable to determine the calling module")
 
     def message(
-        self: Self,
+        self,
         deprecate_in: str,
         remove_in: str,
         prefix: str,
@@ -431,7 +431,7 @@ def message(
         return message
 
     def _generate_message(
-        self: Self,
+        self,
         deprecate_in: str,
         remove_in: str,
         prefix: str | None,