MAINT: Add deprecate_with_replacement to PdfWriter.find_bookmark

pypdf/_doc_common.py

@@ -762,8 +762,8 @@ def open_destination(
  ) -> Union[None, Destination, TextStringObject, ByteStringObject]:
  """
  Property to access the opening destination (``/OpenAction`` entry in
- the PDF catalog). It returns ``None`` if the entry does not exist is not
- set.
+ the PDF catalog). It returns ``None`` if the entry does not exist
+ or is not set.
 
  Raises:
  Exception: If a destination is invalid.
@@ -795,7 +795,7 @@ def outline(self) -> OutlineType:
  """
  Read-only property for the outline present in the document
  (i.e., a collection of 'outline items' which are also known as
- 'bookmarks')
+ 'bookmarks').
  """
  return self._get_outline()
 
@@ -1002,7 +1002,7 @@ def pages(self) -> List[PageObject]:
 
  For PdfWriter Only:
  Provides the capability to remove a page/range of page from the list
- (using the del operator)
+ (using the del operator).
  Note: only the page entry is removed. As the objects beneath can be used
  elsewhere.
  A solution to completely remove them - if they are not used anywhere -
@@ -1138,16 +1138,14 @@ def remove_page(
  Remove page from pages list.
 
  Args:
- page: int / PageObject / IndirectObject
- PageObject : page to be removed. If the page appears many times
- only the first one will be removed
-
- IndirectObject: Reference to page to be removed
-
- int: Page number to be removed
-
- clean: replace PageObject with NullObject to prevent destination,
- annotation to reference a detached page
+ page:
+ * :class:`int`: Page number to be removed.
+ * :class:`~pypdf._page.PageObject`: page to be removed. If the page appears many times
+ only the first one will be removed.
+ * :class:`~pypdf.generic.IndirectObject`: Reference to page to be removed.
+
+ clean: replace PageObject with NullObject to prevent annotations
+ or destinations to reference a detached page.
  """
  if self.flattened_pages is None:
  self._flatten()

pypdf/_writer.py

@@ -64,6 +64,7 @@
  StreamType,
  _get_max_pdf_version_header,
  b_,
+ deprecate_with_replacement,
  logger_warning,
 )
 from .constants import AnnotationDictionaryAttributes as AA
@@ -883,7 +884,7 @@ def _update_field_annotation(
  ap_stream = f"q\n/Tx BMC \nq\n1 1 {rct.width - 1} {rct.height - 1} re\nW\nBT\n{da}\n".encode()
  for line_number, line in enumerate(txt.replace("\n", "\r").split("\r")):
  if line in sel:
- # may be improved but can not find how get fill working => replaced with lined box
+ # may be improved but cannot find how to get fill working => replaced with lined box
  ap_stream += (
  f"1 {y_offset - (line_number * font_height * 1.4) - 1} {rct.width - 2} {font_height + 2} re\n"
  f"0.5 0.5 0.5 rg s\n{da}\n"
@@ -2199,7 +2200,7 @@ def add_annotation(
  """
  Add a single annotation to the page.
  The added annotation must be a new annotation.
- It can not be recycled.
+ It cannot be recycled.
 
  Args:
  page_number: PageObject or page index.
@@ -2847,6 +2848,7 @@ def find_bookmark(
  .. deprecated:: 2.9.0
  Use :meth:`find_outline_item` instead.
  """
+ deprecate_with_replacement("find_bookmark", "find_outline_item", "5.0.0")
  return self.find_outline_item(outline_item, root)
 
  def reset_translation(