DEP: rotate_clockwise ➔ rotate for PageObject (#913)

MasterOdin · web-flow · commit 07bb859e91ce · 2022-05-28T12:10:43.000+02:00
Signed-off-by: Matthew Peveler &lt;matt.peveler@gmail.com&gt;
diff --git a/PyPDF2/_page.py b/PyPDF2/_page.py
@@ -309,7 +309,7 @@ def createBlankPage(
         )
         return PageObject.create_blank_page(pdf, width, height)
 
-    def rotate_clockwise(self, angle: float) -> "PageObject":
+    def rotate(self, angle: float) -> "PageObject":
         """
         Rotate a page clockwise by increments of 90 degrees.
 
@@ -318,21 +318,33 @@ def rotate_clockwise(self, angle: float) -> "PageObject":
         """
         if angle % 90 != 0:
             raise ValueError("Rotation angle must be a multiple of 90")
-        self._rotate(angle)
+        rotate_obj = self.get(PG.ROTATE, 0)
+        current_angle = (
+            rotate_obj if isinstance(rotate_obj, int) else rotate_obj.get_object()
+        )
+        self[NameObject(PG.ROTATE)] = NumberObject(current_angle + angle)
         return self
 
+    def rotate_clockwise(self, angle: float) -> "PageObject":
+        warnings.warn(
+            DEPR_MSG.format("rotate_clockwise", "rotate"),
+            PendingDeprecationWarning,
+            stacklevel=2,
+        )
+        return self.rotate(angle)
+
     def rotateClockwise(self, angle: float) -> "PageObject":
         """
         .. deprecated:: 1.28.0
 
             Use :meth:`rotate_clockwise` instead.
         """
         warnings.warn(
-            DEPR_MSG.format("rotateClockwise", "rotate_clockwise"),
+            DEPR_MSG.format("rotateClockwise", "rotate"),
             PendingDeprecationWarning,
             stacklevel=2,
         )
-        return self.rotate_clockwise(angle)
+        return self.rotate(angle)
 
     def rotateCounterClockwise(self, angle: float) -> "PageObject":
         """
@@ -341,21 +353,11 @@ def rotateCounterClockwise(self, angle: float) -> "PageObject":
             Use :meth:`rotate_clockwise` with a negative argument instead.
         """
         warnings.warn(
-            DEPR_MSG.format("rotateCounterClockwise", "rotate_clockwise"),
+            DEPR_MSG.format("rotateCounterClockwise", "rotate"),
             PendingDeprecationWarning,
             stacklevel=2,
         )
-        if angle % 90 != 0:
-            raise ValueError("Rotation angle must be a multiple of 90")
-        self._rotate(-angle)
-        return self
-
-    def _rotate(self, angle: float) -> None:
-        rotate_obj = self.get(PG.ROTATE, 0)
-        current_angle = (
-            rotate_obj if isinstance(rotate_obj, int) else rotate_obj.get_object()
-        )
-        self[NameObject(PG.ROTATE)] = NumberObject(current_angle + angle)
+        return self.rotate(-angle)
 
     @staticmethod
     def _merge_resources(
diff --git a/PyPDF2/_utils.py b/PyPDF2/_utils.py
@@ -34,6 +34,7 @@
 from codecs import getencoder
 from io import BufferedReader, BufferedWriter, BytesIO, FileIO
 from typing import Any, Dict, Optional, Tuple, Union, overload
+import warnings
 
 try:
     # Python 3.10+: https://www.python.org/dev/peps/pep-0484/
@@ -238,3 +239,19 @@ def paeth_predictor(left: int, up: int, up_left: int) -> int:
         return up
     else:
         return up_left
+
+
+def deprecate_with_replacement(old_name: str, new_name: str) -> None:
+    warnings.warn(
+        DEPR_MSG.format(old_name, new_name),
+        PendingDeprecationWarning,
+        stacklevel=2,
+    )
+
+
+def deprecate_no_replacement(name: str) -> None:
+    warnings.warn(
+        DEPR_MSG_NO_REPLACEMENT.format(name),
+        PendingDeprecationWarning,
+        stacklevel=2,
+    )
diff --git a/docs/user/cropping-and-transforming.md b/docs/user/cropping-and-transforming.md
@@ -10,7 +10,7 @@ writer = PdfWriter()
 writer.add_page(reader.pages[0])
 
 # add page 2 from reader, but rotated clockwise 90 degrees:
-writer.add_page(reader.pages[1].rotate_clockwise(90))
+writer.add_page(reader.pages[1].rotate(90))
 
 # add page 3 from reader, but crop it to half size:
 page3 = reader.pages[2]
diff --git a/tests/test_basic_features.py b/tests/test_basic_features.py
@@ -20,13 +20,13 @@ def test_basic_features():
     writer.add_page(reader.pages[0])
 
     # add page 2 from input1, but rotated clockwise 90 degrees
-    writer.add_page(reader.pages[0].rotate_clockwise(90))
+    writer.add_page(reader.pages[0].rotate(90))
 
     # add page 3 from input1, rotated the other way:
     with pytest.warns(PendingDeprecationWarning):
         rotated = reader.pages[0].rotateCounterClockwise(90)
     writer.add_page(rotated)
-    # alt: output.addPage(input1.pages[0].rotate_clockwise(270))
+    # alt: output.addPage(input1.pages[0].rotate(270))
 
     # add page 4 from input1, but first add a watermark from another PDF:
     page4 = reader.pages[0]
diff --git a/tests/test_page.py b/tests/test_page.py
@@ -188,7 +188,7 @@ def test_page_rotation_non90():
     reader = PdfReader(os.path.join(RESOURCE_ROOT, "crazyones.pdf"))
     page = reader.pages[0]
     with pytest.raises(ValueError) as exc:
-        page.rotate_clockwise(91)
+        page.rotate(91)
     assert exc.value.args[0] == "Rotation angle must be a multiple of 90"
 
 
