TST: Deprecation warnings/errors (#1794)

pypdf/_utils.py

@@ -72,7 +72,7 @@
 
 DEPR_MSG_NO_REPLACEMENT = "{} is deprecated and will be removed in pypdf {}."
 DEPR_MSG_NO_REPLACEMENT_HAPPENED = "{} is deprecated and was removed in pypdf {}."
-DEPR_MSG = "{} is deprecated and will be removed in pypdf 3.0.0. Use {} instead."
+DEPR_MSG = "{} is deprecated and will be removed in pypdf {}. Use {} instead."
 DEPR_MSG_HAPPENED = "{} is deprecated and was removed in pypdf {}. Use {} instead."
 
 
@@ -387,7 +387,7 @@ def deprecate_with_replacement(
     old_name: str, new_name: str, removed_in: str = "3.0.0"
 ) -> None:
     """Raise an exception that a feature will be removed, but has a replacement."""
-    deprecate(DEPR_MSG.format(old_name, new_name, removed_in), 4)
+    deprecate(DEPR_MSG.format(old_name, removed_in, new_name), 4)
 
 
 def deprecation_with_replacement(

tests/test_utils.py

@@ -10,13 +10,16 @@
     File,
     _get_max_pdf_version_header,
     _human_readable_bytes,
+    deprecate_with_replacement,
     deprecation_bookmark,
+    deprecation_no_replacement,
     mark_location,
     matrix_multiply,
     read_block_backwards,
     read_previous_line,
     read_until_regex,
     read_until_whitespace,
+    rename_kwargs,
     skip_over_comment,
     skip_over_whitespace,
 )
@@ -230,6 +233,65 @@ def foo(old_param: int = 1, baz: int = 2) -> None:
     assert exc.value.args[0] == expected_msg
 
 
+def test_deprecate_with_replacement():
+    def foo() -> None:
+        deprecate_with_replacement("foo", "bar", removed_in="4.3.2")
+        pass
+
+    with pytest.warns(
+        DeprecationWarning,
+        match="foo is deprecated and will be removed in pypdf 4.3.2. Use bar instead.",
+    ):
+        foo()
+
+
+def test_deprecation_no_replacement():
+    def foo() -> None:
+        deprecation_no_replacement("foo", removed_in="4.3.2")
+        pass
+
+    with pytest.raises(
+        DeprecationError,
+        match="foo is deprecated and was removed in pypdf 4.3.2.",
+    ):
+        foo()
+
+
+def test_rename_kwargs():
+    import functools
+    from typing import Any, Callable
+
+    def deprecation_bookmark_nofail(**aliases: str) -> Callable:
+        """
+        Decorator for deprecated term "bookmark".
+
+        To be used for methods and function arguments
+            outline_item = a bookmark
+            outline = a collection of outline items.
+        """
+
+        def decoration(func: Callable) -> Any:  # type: ignore
+            @functools.wraps(func)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:  # type: ignore
+                rename_kwargs(func.__name__, kwargs, aliases, fail=False)
+                return func(*args, **kwargs)
+
+            return wrapper
+
+        return decoration
+
+    @deprecation_bookmark_nofail(old_param="new_param")
+    def foo(old_param: int = 1, baz: int = 2) -> None:
+        pass
+
+    expected_msg = (
+        "foo received both old_param and new_param as an argument. "
+        "old_param is deprecated. Use new_param instead."
+    )
+    with pytest.raises(TypeError, match=expected_msg):
+        foo(old_param=12, new_param=13)
+
+
 @pytest.mark.enable_socket()
 def test_escapedcode_followed_by_int():
     # iss #1294