DEP: PEP8 renaming (#900)

PyPDF2 interface changes:

* getXmpMetadata / xmpMetadata ➔ xmp_metadata
* get_outlines ➔ _get_outlines (use outlines property instead)
* getXmpMetadata ➔ xmp_metadata
* getDestArray ➔ dest_array
* additionalActions ➔ additional_actions
* defaultValue ➔ default_value
* mappingName ➔ mapping_name
* altName ➔ alternate_name
* fieldType ➔ field_type
* ensureIsNumber ➔ _ensure_is_number
* decodedSelf : decoded_self
* addChild / removeChild  ➔ add_child / remove_child
* flateEncode  ➔ flate_encode
* getData / setData  ➔ get_data / set_data

DOC: Use the new PyPDF2 interface
STY: Use reader/writer as variable names for PdfReader / PdfWriter
MAINT: Let pytest capture many warnings

Fixes:

* add_named_destionation was a typo and thus removed
* Add missing `PendingDeprecationWarning` in warnings
* Add missing `stacklevel=2` in warnings
* merge_rotated_scaled_translated_page ➔ mergeRotatedScaledTranslatedPage: That renaming was not part of the 1.28.0 release and the complete function should be deprecated; no point in adding a renamed one first
* add_transformation: Add missing parameter type annotation

PyPDF2/_merger.py

@@ -149,7 +149,7 @@ def merge(
 
         outline = []
         if import_bookmarks:
-            outline = reader.get_outlines()
+            outline = reader.outlines
             outline = self._trim_outline(reader, outline, pages)
 
         if bookmark:
@@ -162,7 +162,7 @@ def merge(
         else:
             self.bookmarks += outline
 
-        dests = reader.namedDestinations
+        dests = reader.named_destinations
         trimmed_dests = self._trim_dests(reader, dests, pages)
         self.named_dests += trimmed_dests
 
@@ -296,7 +296,7 @@ def close(self) -> None:
         usage.
         """
         self.pages = []
-        for fo, _pdfr, mine in self.inputs:
+        for fo, _reader, mine in self.inputs:
             if mine:
                 fo.close()
 
@@ -690,7 +690,7 @@ def add_bookmark(
         dest = Destination(
             NameObject("/" + title + " bookmark"), page_ref, NameObject(fit), *zoom_args
         )
-        dest_array = dest.getDestArray()
+        dest_array = dest.dest_array
         action.update(
             {NameObject("/D"): dest_array, NameObject("/S"): NameObject("/GoTo")}
         )
@@ -726,7 +726,7 @@ def add_bookmark(
         bookmark_ref = self.output._add_object(bookmark)
         parent = cast(Bookmark, parent.get_object())
         assert parent is not None, "hint for mypy"
-        parent.addChild(bookmark_ref, self.output)
+        parent.add_child(bookmark_ref, self.output)
 
         return bookmark_ref
 
@@ -742,18 +742,6 @@ def addNamedDestination(self, title: str, pagenum: int) -> None:
         return self.add_named_destination(title, pagenum)
 
     def add_named_destination(self, title: str, pagenum: int) -> None:
-        """
-        .. deprecated:: 1.28.0
-            Use :meth:`add_named_destionation` instead.
-        """
-        warnings.warn(
-            "addNamedDestination is deprecated. Use add_named_destionation instead.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self.add_named_destionation(title, pagenum)
-
-    def add_named_destionation(self, title: str, pagenum: int) -> None:
         """
         Add a destination to the output.
 

PyPDF2/_page.py

@@ -160,7 +160,7 @@ class Transformation:
     -----
     >>> from PyPDF2 import Transformation
     >>> op = Transformation().scale(sx=2, sy=3).translate(tx=10, ty=20)
-    >>> page.mergeTransformedPage(page2, op)
+    >>> page.add_transformation(op)
     """
 
     # 9.5.4 Coordinate Systems for 3D
@@ -228,7 +228,7 @@ class PageObject(DictionaryObject):
     :meth:`get_page()<PyPDF2.PdfReader.get_page>` method of the
     :class:`PdfReader<PyPDF2.PdfReader>` class, but it is
     also possible to create an empty page with the
-    :meth:`createBlankPage()<PageObject.createBlankPage>` static method.
+    :meth:`create_blank_page()<PyPDF2._page.PageObject.create_blank_page>` static method.
 
     :param pdf: PDF file the page belongs to.
     :param indirect_ref: Stores the original indirect reference to
@@ -634,6 +634,8 @@ def mergeTransformedPage(
         warnings.warn(
             "page.mergeTransformedPage(page2, ctm) will be removed in PyPDF 2.0.0. "
             "Use page2.add_transformation(ctm); page.merge_page(page2) instead.",
+            PendingDeprecationWarning,
+            stacklevel=2,
         )
         if isinstance(ctm, Transformation):
             ctm = ctm.ctm
@@ -831,7 +833,7 @@ def mergeScaledTranslatedPage(
         op = Transformation().scale(scale, scale).translate(tx, ty)
         return self.mergeTransformedPage(page2, op, expand)
 
-    def merge_rotated_scaled_translated_page(
+    def mergeRotatedScaledTranslatedPage(
         self,
         page2: "PageObject",
         rotation: float,
@@ -870,7 +872,9 @@ def merge_rotated_scaled_translated_page(
         self.mergeTransformedPage(page2, op, expand)
 
     def add_transformation(
-        self, ctm: CompressedTransformationMatrix, expand: bool = False
+        self,
+        ctm: Union[Transformation, CompressedTransformationMatrix],
+        expand: bool = False,
     ) -> None:
         """
         Apply a transformation matrix to the page.
@@ -1033,7 +1037,7 @@ def compress_content_streams(self) -> None:
         if content is not None:
             if not isinstance(content, ContentStream):
                 content = ContentStream(content, self.pdf)
-            self[NameObject(PG.CONTENTS)] = content.flateEncode()
+            self[NameObject(PG.CONTENTS)] = content.flate_encode()
 
     def compressContentStreams(self) -> None:
         """
@@ -1112,6 +1116,8 @@ def extractText(self, Tj_sep: str = "", TJ_sep: str = "") -> str:
         """
         warnings.warn(
             DEPR_MSG.format("Page.extractText", "Page.extract_text"),
+            PendingDeprecationWarning,
+            stacklevel=2,
         )
         return self.extract_text(Tj_sep=Tj_sep, TJ_sep=TJ_sep)
 

PyPDF2/_reader.py

@@ -105,15 +105,15 @@ def convertToInt(d: bytes, size: int) -> Union[int, Tuple[Any, ...]]:
         "convertToInt will be removed with PyPDF2 2.0.0. "
         "Use convert_to_int instead.",
         PendingDeprecationWarning,
+        stacklevel=2,
     )
     return convert_to_int(d, size)
 
 
 class DocumentInformation(DictionaryObject):
     """
     A class representing the basic document metadata provided in a PDF File.
-    This class is accessible through
-    :meth:`.getDocumentInfo()`
+    This class is accessible through :py:class:`PdfReader.metadata<PyPDF2.PdfReader.metadata>`.
 
     All text properties of the document metadata have
     *two* properties, eg. author and author_raw. The non-raw property will
@@ -316,7 +316,7 @@ def xmp_metadata(self) -> Optional[XmpInformation]:
         """
         try:
             self._override_encryption = True
-            return self.trailer[TK.ROOT].getXmpMetadata()  # type: ignore
+            return self.trailer[TK.ROOT].xmp_metadata  # type: ignore
         finally:
             self._override_encryption = False
 
@@ -433,6 +433,8 @@ def namedDestinations(self) -> Dict[str, Any]:
         warnings.warn(
             "namedDestinations will be removed in PyPDF2 2.0.0. "
             "Use `named_destinations` instead.",
+            PendingDeprecationWarning,
+            stacklevel=2,
         )
         return self.named_destinations
 
@@ -668,17 +670,16 @@ def getNamedDestinations(
 
     @property
     def outlines(self) -> OutlinesType:
-        """Read-only property."""
-        return self.get_outlines()
-
-    def get_outlines(
-        self, node: Optional[DictionaryObject] = None, outlines: Optional[Any] = None
-    ) -> OutlinesType:
         """
-        Retrieve the document outline present in the document.
+        Read-only property for outlines present in the document.
 
         :return: a nested list of :class:`Destinations<PyPDF2.generic.Destination>`.
         """
+        return self._get_outlines()
+
+    def _get_outlines(
+        self, node: Optional[DictionaryObject] = None, outlines: Optional[Any] = None
+    ) -> OutlinesType:
         if outlines is None:
             outlines = []
             catalog = cast(DictionaryObject, self.trailer[TK.ROOT])
@@ -710,7 +711,7 @@ def get_outlines(
             # check for sub-outlines
             if "/First" in node:
                 sub_outlines: List[Any] = []
-                self.get_outlines(cast(DictionaryObject, node["/First"]), sub_outlines)
+                self._get_outlines(cast(DictionaryObject, node["/First"]), sub_outlines)
                 if sub_outlines:
                     outlines.append(sub_outlines)
 
@@ -726,14 +727,14 @@ def getOutlines(
         """
         .. deprecated:: 1.28.0
 
-            Use :meth:`get_outlines` instead.
+            Use :py:attr:`outlines` instead.
         """
         warnings.warn(
-            "getOutlines will be removed in PyPDF2 2.0.0. Use get_outlines instead.",
+            "getOutlines will be removed in PyPDF2 2.0.0. Use the outlines attribute instead.",
             PendingDeprecationWarning,
             stacklevel=2,
         )
-        return self.get_outlines(node, outlines)
+        return self._get_outlines(node, outlines)
 
     def _get_page_number_by_indirect(
         self, indirect_ref: Union[None, int, NullObject, IndirectObject]
@@ -814,7 +815,7 @@ def _build_destination(
         try:
             return Destination(title, page, typ, *array)  # type: ignore
         except PdfReadError:
-            warnings.warn("Unknown destination : " + title + " " + str(array))
+            warnings.warn(f"Unknown destination: {title} {array}", PdfReadWarning)
             if self.strict:
                 raise
             else:
@@ -1031,7 +1032,7 @@ def _get_object_from_stream(
         assert obj_stm["/Type"] == "/ObjStm"
         # /N is the number of indirect objects in the stream
         assert idx < obj_stm["/N"]
-        stream_data = BytesIO(b_(obj_stm.getData()))  # type: ignore
+        stream_data = BytesIO(b_(obj_stm.get_data()))  # type: ignore
         for i in range(obj_stm["/N"]):  # type: ignore
             read_non_whitespace(stream_data)
             stream_data.seek(-1, 1)
@@ -1411,7 +1412,7 @@ def _find_startxref_pos(self, stream: StreamType) -> int:
             if not line.startswith(b_("startxref")):
                 raise PdfReadError("startxref not found")
             startxref = int(line[9:].strip())
-            warnings.warn("startxref on same line as offset")
+            warnings.warn("startxref on same line as offset", PdfReadWarning)
         else:
             line = self.read_next_end_line(stream)
             if line[:9] != b_("startxref"):
@@ -1498,7 +1499,7 @@ def _read_pdf15_xref_stream(
         xrefstream = cast(ContentStream, read_object(stream, self))
         assert xrefstream["/Type"] == "/XRef"
         self.cache_indirect_object(generation, idnum, xrefstream)
-        stream_data = BytesIO(b_(xrefstream.getData()))
+        stream_data = BytesIO(b_(xrefstream.get_data()))
         # Index pairs specify the subsections in the dictionary. If
         # none create one subsection that spans everything.
         idx_pairs = xrefstream.get("/Index", [0, xrefstream.get("/Size")])
@@ -1807,7 +1808,7 @@ def is_encrypted(self) -> bool:
         """
         Read-only boolean property showing whether this PDF file is encrypted.
         Note that this property, if true, will remain true even after the
-        :meth:`decrypt()<PdfReader.decrypt>` method is called.
+        :meth:`decrypt()<PyPDF2.PdfReader.decrypt>` method is called.
         """
         return TK.ENCRYPT in self.trailer
 

PyPDF2/_writer.py

@@ -85,7 +85,7 @@
 class PdfWriter:
     """
     This class supports writing PDF files out, given pages produced by another
-    class (typically :class:`PdfReader<PdfReader>`).
+    class (typically :class:`PdfReader<PyPDF2.PdfReader>`).
     """
 
     def __init__(self) -> None:
@@ -183,7 +183,7 @@ def set_need_appearances_writer(self) -> None:
     def add_page(self, page: PageObject) -> None:
         """
         Add a page to this PDF file.  The page is usually acquired from a
-        :class:`PdfReader<PdfReader>` instance.
+        :class:`PdfReader<PyPDF2.PdfReader>` instance.
 
         :param PageObject page: The page to add to the document. Should be
             an instance of :class:`PageObject<PyPDF2._page.PageObject>`
@@ -206,7 +206,7 @@ def addPage(self, page: PageObject) -> None:
     def insert_page(self, page: PageObject, index: int = 0) -> None:
         """
         Insert a page in this PDF file. The page is usually acquired from a
-        :class:`PdfReader<PdfReader>` instance.
+        :class:`PdfReader<PyPDF2.PdfReader>` instance.
 
         :param PageObject page: The page to add to the document.  This
             argument should be an instance of :class:`PageObject<PyPDF2._page.PageObject>`.
@@ -447,7 +447,7 @@ def add_attachment(self, filename: str, data: Union[str, bytes]) -> None:
         endobj
         """
         file_entry = DecodedStreamObject()
-        file_entry.setData(data)
+        file_entry.set_data(data)
         file_entry.update({NameObject(PA.TYPE): NameObject("/EmbeddedFile")})
 
         # The Filespec entry
@@ -1040,7 +1040,7 @@ def add_bookmark_destination(
             parent = outline_ref
 
         parent = cast(TreeObject, parent.get_object())
-        parent.addChild(dest_ref, self)
+        parent.add_child(dest_ref, self)
 
         return dest_ref
 
@@ -1082,7 +1082,7 @@ def add_bookmark_dict(
 
         parent = parent.get_object()  # type: ignore
         assert parent is not None, "hint for mypy"
-        parent.addChild(bookmark_ref, self)
+        parent.add_child(bookmark_ref, self)
 
         return bookmark_ref
 
@@ -1136,7 +1136,7 @@ def add_bookmark(
         dest = Destination(
             NameObject("/" + title + " bookmark"), page_ref, NameObject(fit), *zoom_args
         )
-        dest_array = dest.getDestArray()
+        dest_array = dest.dest_array
         action.update(
             {NameObject("/D"): dest_array, NameObject("/S"): NameObject("/GoTo")}
         )
@@ -1173,7 +1173,7 @@ def add_bookmark(
 
         assert parent is not None, "hint for mypy"
         parent_obj = cast(TreeObject, parent.get_object())
-        parent_obj.addChild(bookmark_ref, self)
+        parent_obj.add_child(bookmark_ref, self)
 
         return bookmark_ref
 
@@ -1579,7 +1579,7 @@ def add_link(
         dest = Destination(
             NameObject("/LinkName"), page_dest, NameObject(fit), *zoom_args
         )  # TODO: create a better name for the link
-        dest_array = dest.getDestArray()
+        dest_array = dest.dest_array
 
         lnk = DictionaryObject()
         lnk.update(
@@ -1629,14 +1629,6 @@ def addLink(
     ]
 
     def _get_page_layout(self) -> Optional[LayoutType]:
-        """
-        Get the page layout.
-
-        See :meth:`setPageLayout()<PdfWriter.setPageLayout>` for a description of valid layouts.
-
-        :return: Page layout currently being used.
-        :rtype: str, None if not specified
-        """
         try:
             return cast(LayoutType, self._root_object["/PageLayout"])
         except KeyError:
@@ -1771,14 +1763,6 @@ def pageLayout(self, layout: LayoutType) -> None:
     ]
 
     def _get_page_mode(self) -> Optional[PagemodeType]:
-        """
-        Get the page mode.
-        See :meth:`setPageMode()<PdfWriter.setPageMode>` for a description
-        of valid modes.
-
-        :return: Page mode currently being used.
-        :rtype: str, None if not specified.
-        """
         try:
             return cast(PagemodeType, self._root_object["/PageMode"])
         except KeyError:

PyPDF2/filters.py

@@ -502,7 +502,7 @@ def _xobj_to_image(x_object_obj: Dict[str, Any]) -> Tuple[Optional[str], bytes]:
     from PIL import Image
 
     size = (x_object_obj[IA.WIDTH], x_object_obj[IA.HEIGHT])
-    data = x_object_obj.getData()  # type: ignore
+    data = x_object_obj.get_data()  # type: ignore
     if x_object_obj[IA.COLOR_SPACE] == ColorSpaces.DEVICE_RGB:
         mode: Literal["RGB", "P"] = "RGB"
     else:
@@ -513,7 +513,7 @@ def _xobj_to_image(x_object_obj: Dict[str, Any]) -> Tuple[Optional[str], bytes]:
             extension = ".png"
             img = Image.frombytes(mode, size, data)
             if G.S_MASK in x_object_obj:  # add alpha channel
-                alpha = Image.frombytes("L", size, x_object_obj[G.S_MASK].getData())
+                alpha = Image.frombytes("L", size, x_object_obj[G.S_MASK].get_data())
                 img.putalpha(alpha)
             img_byte_arr = BytesIO()
             img.save(img_byte_arr, format="PNG")