MAINT: position ➔ page_number in Merger.merge (#1482)

Changed method parameter name for consistency as mentioned in #1187 

- `position` ➔ `page_number` in `PdfMerger.merge`

Improved the deprecation message of:

- `dest` ➔ `page_destination` in `PdfWriter.add_outline_item_destination` and `PdfWriter.add_named_destination_object`
- `user_pwd` ➔ `user_password` and `owner_pwd` ➔ `owner_password` in `PdfWriter.encrypt`

PyPDF2/_merger.py

@@ -131,17 +131,18 @@ def __exit__(
     @deprecate_bookmark(bookmark="outline_item", import_bookmarks="import_outline")
     def merge(
         self,
-        position: int,
-        fileobj: Union[Path, StrByteType, PdfReader],
+        page_number: Optional[int] = None,
+        fileobj: Union[Path, StrByteType, PdfReader] = None,
         outline_item: Optional[str] = None,
         pages: Optional[PageRangeSpec] = None,
         import_outline: bool = True,
+        position: Optional[int] = None,  # deprecated
     ) -> None:
         """
         Merge the pages from the given file into the output file at the
         specified page number.
 
-        :param int position: The *page number* to insert this file. File will
+        :param int page_number: The *page number* to insert this file. File will
             be inserted after the given number.
 
         :param fileobj: A File Object or an object that supports the standard
@@ -162,6 +163,30 @@ def merge(
             outline (collection of outline items, previously referred to as
             'bookmarks') from being imported by specifying this as ``False``.
         """
+        if position is not None:  # deprecated
+            if page_number is None:
+                page_number = position
+                old_term = "position"
+                new_term = "page_number"
+                warnings.warn(
+                    message=(
+                        f"{old_term} is deprecated as an argument. Use {new_term} instead"
+                    )
+                )
+            else:
+                raise ValueError(
+                    "The argument position of merge is deprecated. Use page_number only."
+                )
+
+        if page_number is None:  # deprecated
+            # The paremter is only marked as Optional as long as
+            # position is not fully deprecated
+            raise ValueError("page_number may not be None")
+        if fileobj is None:  # deprecated
+            # The argument is only Optional due to the deprecated position
+            # argument
+            raise ValueError("fileobj may not be None")
+
         stream, encryption_obj = self._create_stream(fileobj)
 
         # Create a new PdfReader instance using the stream
@@ -216,8 +241,8 @@ def merge(
         self._associate_dests_to_pages(srcpages)
         self._associate_outline_items_to_pages(srcpages)
 
-        # Slice to insert the pages at the specified position
-        self.pages[position:position] = srcpages
+        # Slice to insert the pages at the specified page_number
+        self.pages[page_number:page_number] = srcpages
 
     def _create_stream(
         self, fileobj: Union[Path, StrByteType, PdfReader]

PyPDF2/_writer.py

@@ -796,7 +796,7 @@ def cloneDocumentFromReader(
 
     def encrypt(
         self,
-        user_password: str,
+        user_password: Optional[str] = None,
         owner_password: Optional[str] = None,
         use_128bit: bool = True,
         permissions_flag: UserAccessPermissions = ALL_DOCUMENT_PERMISSIONS,
@@ -835,6 +835,25 @@ def encrypt(
                     "in PyPDF2==3.0.0."
                 )
                 user_password = user_pwd
+        if user_password is None:  # deprecated
+            # user_password is only Optional for due to the deprecated user_pwd
+            raise ValueError("user_password may not be None")
+
+        if owner_pwd is not None:  # deprecated
+            if owner_password is not None:
+                raise ValueError(
+                    "The argument owner_pwd of encrypt is deprecated. Use owner_password only."
+                )
+            else:
+                old_term = "owner_pwd"
+                new_term = "owner_password"
+                warnings.warn(
+                    message=(
+                        f"{old_term} is deprecated as an argument. Use {new_term} instead"
+                    )
+                )
+                owner_password = owner_pwd
+
         if owner_password is None:
             owner_password = user_password
         if use_128bit:
@@ -1216,9 +1235,27 @@ def getNamedDestRoot(self) -> ArrayObject:  # pragma: no cover
 
     def add_outline_item_destination(
         self,
-        page_destination: Union[PageObject, TreeObject],
+        page_destination: Union[None, PageObject, TreeObject] = None,
         parent: Union[None, TreeObject, IndirectObject] = None,
+        dest: Union[None, PageObject, TreeObject] = None,   # deprecated
     ) -> IndirectObject:
+        if page_destination is not None and dest is not None:  # deprecated
+            raise ValueError(
+                "The argument dest of add_outline_item_destination is deprecated. Use page_destination only."
+            )
+        if dest is not None:  # deprecated
+            old_term = "dest"
+            new_term = "page_destination"
+            warnings.warn(
+                message=(
+                    f"{old_term} is deprecated as an argument. Use {new_term} instead"
+                )
+            )
+            page_destination = dest
+        if page_destination is None:  # deprecated
+            # argument is only Optional due to deprecated argument.
+            raise ValueError("page_destination may not be None")
+
         if parent is None:
             parent = self.get_outline_root()
 
@@ -1413,8 +1450,26 @@ def add_outline(self) -> None:
         )
 
     def add_named_destination_object(
-        self, page_destination: PdfObject
+        self,
+        page_destination: Optional[PdfObject] = None,
+        dest: Optional[PdfObject] = None,
     ) -> IndirectObject:
+        if page_destination is not None and dest is not None:
+            raise ValueError(
+                "The argument dest of add_named_destination_object is deprecated. Use page_destination only."
+            )
+        if dest is not None:  # deprecated
+            old_term = "dest"
+            new_term = "page_destination"
+            warnings.warn(
+                message=(
+                    f"{old_term} is deprecated as an argument. Use {new_term} instead"
+                )
+            )
+            page_destination = dest
+        if page_destination is None:  # deprecated
+            raise ValueError("page_destination may not be None")
+
         page_destination_ref = self._add_object(page_destination)
 
         nd = self.get_named_dest_root()
@@ -1438,7 +1493,7 @@ def add_named_destination(
         self,
         title: str,
         page_number: Optional[int] = None,
-        pagenum: Optional[int] = None,
+        pagenum: Optional[int] = None,  # deprecated
     ) -> IndirectObject:
         if page_number is not None and pagenum is not None:
             raise ValueError(

docs/user/migration-1-to-2.md

@@ -164,6 +164,11 @@ utils.py:
 * `PyPDF2.filters` (all classes): `decodeParms` ➔ `decode_parms`
 * `PyPDF2.filters` (all classes): `decodeStreamData` ➔ `decode_stream_data`
 * `pagenum` ➔ `page_number`
+* `PdfMerger.merge`: `position` ➔ `page_number`
+* `PdfWriter.add_outline_item_destination`: `dest` ➔ `page_destination`
+* `PdfWriter.add_named_destination_object`: `dest` ➔ `page_destination`
+* `PdfWriter.encrypt`: `user_pwd` ➔ `user_password`
+* `PdfWriter.encrypt`: `owner_pwd` ➔ `owner_password`
 
 ## Deprecations