diff --git a/PyPDF2/_merger.py b/PyPDF2/_merger.py index 7d6269b15..57261baa0 100644 --- a/PyPDF2/_merger.py +++ b/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] diff --git a/PyPDF2/_writer.py b/PyPDF2/_writer.py index 5ba8e6f45..e5beb0ff0 100644 --- a/PyPDF2/_writer.py +++ b/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( diff --git a/docs/user/migration-1-to-2.md b/docs/user/migration-1-to-2.md index 6df87e7ff..055c29ac2 100644 --- a/docs/user/migration-1-to-2.md +++ b/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