MAINT: indirect_ref/ido ➔ indirect_reference, dest➔ page_destination

PyPDF2/_reader.py

@@ -304,7 +304,7 @@ def __init__(
         self.xref_index = 0
         self._page_id2num: Optional[
             Dict[Any, Any]
-        ] = None  # map page indirect_ref number to Page Number
+        ] = None  # map page indirect_reference number to Page Number
         if hasattr(stream, "mode") and "b" not in stream.mode:  # type: ignore
             logger_warning(
                 "PdfReader stream/file object is not in binary mode. "
@@ -815,20 +815,20 @@ def threads(self) -> Optional[ArrayObject]:
             return None
 
     def _get_page_number_by_indirect(
-        self, indirect_ref: Union[None, int, NullObject, IndirectObject]
+        self, indirect_reference: Union[None, int, NullObject, IndirectObject]
     ) -> int:
         """Generate _page_id2num"""
         if self._page_id2num is None:
             self._page_id2num = {
-                x.indirect_ref.idnum: i for i, x in enumerate(self.pages)  # type: ignore
+                x.indirect_reference.idnum: i for i, x in enumerate(self.pages)  # type: ignore
             }
 
-        if indirect_ref is None or isinstance(indirect_ref, NullObject):
+        if indirect_reference is None or isinstance(indirect_reference, NullObject):
             return -1
-        if isinstance(indirect_ref, int):
-            idnum = indirect_ref
+        if isinstance(indirect_reference, int):
+            idnum = indirect_reference
         else:
-            idnum = indirect_ref.idnum
+            idnum = indirect_reference.idnum
         assert self._page_id2num is not None, "hint for mypy"
         ret = self._page_id2num.get(idnum, -1)
         return ret
@@ -841,7 +841,7 @@ def get_page_number(self, page: PageObject) -> int:
             an instance of :class:`PageObject<PyPDF2._page.PageObject>`
         :return: the page number or -1 if page not found
         """
-        return self._get_page_number_by_indirect(page.indirect_ref)
+        return self._get_page_number_by_indirect(page.indirect_reference)
 
     def getPageNumber(self, page: PageObject) -> int:  # pragma: no cover
         """
@@ -904,10 +904,10 @@ def _build_destination(
                 if self.strict:
                     raise
                 # create a link to first Page
-                tmp = self.pages[0].indirect_ref
-                indirect_ref = NullObject() if tmp is None else tmp
+                tmp = self.pages[0].indirect_reference
+                indirect_reference = NullObject() if tmp is None else tmp
                 return Destination(
-                    title, indirect_ref, TextStringObject("/Fit")  # type: ignore
+                    title, indirect_reference, TextStringObject("/Fit")  # type: ignore
                 )
 
     def _build_outline_item(self, node: DictionaryObject) -> Optional[Destination]:
@@ -1081,7 +1081,7 @@ def _flatten(
         self,
         pages: Union[None, DictionaryObject, PageObject] = None,
         inherit: Optional[Dict[str, Any]] = None,
-        indirect_ref: Optional[IndirectObject] = None,
+        indirect_reference: Optional[IndirectObject] = None,
     ) -> None:
         inheritable_page_attributes = (
             NameObject(PG.RESOURCES),
@@ -1109,15 +1109,15 @@ def _flatten(
             for page in pages[PA.KIDS]:  # type: ignore
                 addt = {}
                 if isinstance(page, IndirectObject):
-                    addt["indirect_ref"] = page
+                    addt["indirect_reference"] = page
                 self._flatten(page.get_object(), inherit, **addt)
         elif t == "/Page":
             for attr_in, value in list(inherit.items()):
                 # if the page has it's own value, it does not inherit the
                 # parent's value:
                 if attr_in not in pages:
                     pages[attr_in] = value
-            page_obj = PageObject(self, indirect_ref)
+            page_obj = PageObject(self, indirect_reference)
             page_obj.update(pages)
 
             # TODO: Could flattened_pages be None at this point?

PyPDF2/_writer.py

@@ -201,10 +201,19 @@ def _add_object(self, obj: PdfObject) -> IndirectObject:
         self._objects.append(obj)
         return IndirectObject(len(self._objects), 0, self)
 
-    def get_object(self, ido: IndirectObject) -> PdfObject:
-        if ido.pdf != self:
+    def get_object(self, indirect_reference: Optional[IndirectObject]=None, ido: Optional[IndirectObject]=None) -> PdfObject:
+        if ido is not None:
+            if indirect_reference is not None:
+                raise ValueError("Please only set 'indirect_reference'. The 'ido' argument is deprecated.")
+            else:
+                indirect_reference = ido
+                warnings.warn(
+                    "The parameter 'ido' is depreciated and will be removed in PyPDF2 3.0.0.",
+                    DeprecationWarning,
+                )
+        if indirect_reference.pdf != self:
             raise ValueError("pdf must be self")
-        return self._objects[ido.idnum - 1]  # type: ignore
+        return self._objects[indirect_reference.idnum - 1]  # type: ignore
 
     def getObject(self, ido: IndirectObject) -> PdfObject:  # pragma: no cover
         """
@@ -456,7 +465,7 @@ def open_destination(self, dest: Union[None, str, Destination, PageObject]) -> N
         elif isinstance(dest, PageObject):
             self._root_object[NameObject("/OpenAction")] = Destination(
                 "Opening",
-                dest.indirect_ref if dest.indirect_ref is not None else NullObject(),
+                dest.indirect_reference if dest.indirect_reference is not None else NullObject(),
                 TextStringObject("/Fit"),
             ).dest_array
 
@@ -1039,15 +1048,15 @@ def _sweep_indirect_references(
 
                 # Update old hash value to new hash value
                 for old_hash in update_hashes:
-                    indirect_ref = self._idnum_hash.pop(old_hash, None)
+                    indirect_reference = self._idnum_hash.pop(old_hash, None)
 
-                    if indirect_ref is not None:
-                        indirect_ref_obj = indirect_ref.get_object()
+                    if indirect_reference is not None:
+                        indirect_reference_obj = indirect_reference.get_object()
 
-                        if indirect_ref_obj is not None:
+                        if indirect_reference_obj is not None:
                             self._idnum_hash[
-                                indirect_ref_obj.hash_value()
-                            ] = indirect_ref
+                                indirect_reference_obj.hash_value()
+                            ] = indirect_reference
 
     def _resolve_indirect_object(self, data: IndirectObject) -> IndirectObject:
         """
@@ -1196,17 +1205,17 @@ def getNamedDestRoot(self) -> ArrayObject:  # pragma: no cover
 
     def add_outline_item_destination(
         self,
-        dest: Union[PageObject, TreeObject],
+        page_destination: Union[PageObject, TreeObject],
         parent: Union[None, TreeObject, IndirectObject] = None,
     ) -> IndirectObject:
         if parent is None:
             parent = self.get_outline_root()
 
         parent = cast(TreeObject, parent.get_object())
-        dest_ref = self._add_object(dest)
-        parent.add_child(dest_ref, self)
+        page_destination_ref = self._add_object(page_destination)
+        parent.add_child(page_destination_ref, self)
 
-        return dest_ref
+        return page_destination_ref
 
     def add_bookmark_destination(
         self,
@@ -1392,12 +1401,12 @@ def add_outline(self) -> None:
             "This method is not yet implemented. Use :meth:`add_outline_item` instead."
         )
 
-    def add_named_destination_object(self, dest: PdfObject) -> IndirectObject:
-        dest_ref = self._add_object(dest)
+    def add_named_destination_object(self, page_destination: PdfObject) -> IndirectObject:
+        page_destination_ref = self._add_object(page_destination)
 
         nd = self.get_named_dest_root()
-        nd.extend([dest["/Title"], dest_ref])  # type: ignore
-        return dest_ref
+        nd.extend([page_destination["/Title"], page_destination_ref])  # type: ignore
+        return page_destination_ref
 
     def addNamedDestinationObject(
         self, dest: PdfObject
@@ -1712,7 +1721,7 @@ def addURI(
     def add_link(
         self,
         pagenum: int,  # deprecated, but method is deprecated already
-        pagedest: int,
+        page_destination: int,
         rect: RectangleObject,
         border: Optional[ArrayObject] = None,
         fit: FitType = "/Fit",
@@ -1735,7 +1744,7 @@ def add_link(
         annotation = AnnotationBuilder.link(
             rect=rect,
             border=border,
-            target_page_index=pagedest,
+            target_page_index=page_destination,
             fit=fit,
             fit_args=args,
         )
@@ -1744,7 +1753,7 @@ def add_link(
     def addLink(
         self,
         pagenum: int,  # deprecated, but method is deprecated already
-        pagedest: int,
+        page_destination: int,
         rect: RectangleObject,
         border: Optional[ArrayObject] = None,
         fit: FitType = "/Fit",
@@ -1758,7 +1767,7 @@ def addLink(
         deprecate_with_replacement(
             "addLink", "add_annotation(AnnotationBuilder.link(...))", "4.0.0"
         )
-        return self.add_link(pagenum, pagedest, rect, border, fit, *args)
+        return self.add_link(pagenum, page_destination, rect, border, fit, *args)
 
     _valid_layouts = (
         "/NoLayout",

tests/test_writer.py

@@ -830,10 +830,10 @@ def test_startup_dest():
     pdf_file_writer.open_destination = pdf_file_writer.pages[9]
     # checked also using Acrobrat to verify the good page is opened
     op = pdf_file_writer._root_object["/OpenAction"]
-    assert op[0] == pdf_file_writer.pages[9].indirect_ref
+    assert op[0] == pdf_file_writer.pages[9].indirect_reference
     assert op[1] == "/Fit"
     op = pdf_file_writer.open_destination
-    assert op.raw_get("/Page") == pdf_file_writer.pages[9].indirect_ref
+    assert op.raw_get("/Page") == pdf_file_writer.pages[9].indirect_reference
     assert op["/Type"] == "/Fit"
     pdf_file_writer.open_destination = op
     assert pdf_file_writer.open_destination == op