two version of R2R are here HEAD master

1 files changed, 2822 insertions, 0 deletions

diff --git a/.venv/lib/python3.12/site-packages/PyPDF2/_writer.py b/.venv/lib/python3.12/site-packages/PyPDF2/_writer.py
new file mode 100644
index 00000000..b2e92cdb
--- /dev/null
+++ b/.venv/lib/python3.12/site-packages/PyPDF2/_writer.py
@@ -0,0 +1,2822 @@
+# Copyright (c) 2006, Mathieu Fenniak
+# Copyright (c) 2007, Ashish Kulkarni <kulkarni.ashish@gmail.com>
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright notice,
+# this list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright notice,
+# this list of conditions and the following disclaimer in the documentation
+# and/or other materials provided with the distribution.
+# * The name of the author may not be used to endorse or promote products
+# derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+import codecs
+import collections
+import decimal
+import logging
+import random
+import re
+import struct
+import time
+import uuid
+import warnings
+from hashlib import md5
+from io import BytesIO, FileIO, IOBase
+from pathlib import Path
+from types import TracebackType
+from typing import (
+    IO,
+    Any,
+    Callable,
+    Deque,
+    Dict,
+    Iterable,
+    List,
+    Optional,
+    Pattern,
+    Tuple,
+    Type,
+    Union,
+    cast,
+)
+
+from ._encryption import Encryption
+from ._page import PageObject, _VirtualList
+from ._reader import PdfReader
+from ._security import _alg33, _alg34, _alg35
+from ._utils import (
+    StrByteType,
+    StreamType,
+    _get_max_pdf_version_header,
+    b_,
+    deprecate_with_replacement,
+    deprecation_bookmark,
+    deprecation_with_replacement,
+    logger_warning,
+)
+from .constants import AnnotationDictionaryAttributes
+from .constants import CatalogAttributes as CA
+from .constants import CatalogDictionary
+from .constants import Core as CO
+from .constants import EncryptionDictAttributes as ED
+from .constants import (
+    FieldDictionaryAttributes,
+    FieldFlag,
+    FileSpecificationDictionaryEntries,
+    GoToActionArguments,
+    InteractiveFormDictEntries,
+)
+from .constants import PageAttributes as PG
+from .constants import PagesAttributes as PA
+from .constants import StreamAttributes as SA
+from .constants import TrailerKeys as TK
+from .constants import TypFitArguments, UserAccessPermissions
+from .generic import (
+    PAGE_FIT,
+    AnnotationBuilder,
+    ArrayObject,
+    BooleanObject,
+    ByteStringObject,
+    ContentStream,
+    DecodedStreamObject,
+    Destination,
+    DictionaryObject,
+    Fit,
+    FloatObject,
+    IndirectObject,
+    NameObject,
+    NullObject,
+    NumberObject,
+    PdfObject,
+    RectangleObject,
+    StreamObject,
+    TextStringObject,
+    TreeObject,
+    create_string_object,
+    hex_to_rgb,
+)
+from .pagerange import PageRange, PageRangeSpec
+from .types import (
+    BorderArrayType,
+    FitType,
+    LayoutType,
+    OutlineItemType,
+    OutlineType,
+    PagemodeType,
+    ZoomArgType,
+)
+
+logger = logging.getLogger(__name__)
+
+
+OPTIONAL_READ_WRITE_FIELD = FieldFlag(0)
+ALL_DOCUMENT_PERMISSIONS = UserAccessPermissions((2**31 - 1) - 3)
+
+
+class PdfWriter:
+    """
+    This class supports writing PDF files out, given pages produced by another
+    class (typically :class:`PdfReader<PyPDF2.PdfReader>`).
+    """
+
+    def __init__(self, fileobj: StrByteType = "") -> None:
+        self._header = b"%PDF-1.3"
+        self._objects: List[PdfObject] = []  # array of indirect objects
+        self._idnum_hash: Dict[bytes, IndirectObject] = {}
+        self._id_translated: Dict[int, Dict[int, int]] = {}
+
+        # The root of our page tree node.
+        pages = DictionaryObject()
+        pages.update(
+            {
+                NameObject(PA.TYPE): NameObject("/Pages"),
+                NameObject(PA.COUNT): NumberObject(0),
+                NameObject(PA.KIDS): ArrayObject(),
+            }
+        )
+        self._pages = self._add_object(pages)
+
+        # info object
+        info = DictionaryObject()
+        info.update(
+            {
+                NameObject("/Producer"): create_string_object(
+                    codecs.BOM_UTF16_BE + "PyPDF2".encode("utf-16be")
+                )
+            }
+        )
+        self._info = self._add_object(info)
+
+        # root object
+        self._root_object = DictionaryObject()
+        self._root_object.update(
+            {
+                NameObject(PA.TYPE): NameObject(CO.CATALOG),
+                NameObject(CO.PAGES): self._pages,
+            }
+        )
+        self._root = self._add_object(self._root_object)
+        self.fileobj = fileobj
+        self.with_as_usage = False
+
+    def __enter__(self) -> "PdfWriter":
+        """Store that writer is initialized by 'with'."""
+        self.with_as_usage = True
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc: Optional[BaseException],
+        traceback: Optional[TracebackType],
+    ) -> None:
+        """Write data to the fileobj."""
+        if self.fileobj:
+            self.write(self.fileobj)
+
+    @property
+    def pdf_header(self) -> bytes:
+        """
+        Header of the PDF document that is written.
+
+        This should be something like b'%PDF-1.5'. It is recommended to set the
+        lowest version that supports all features which are used within the
+        PDF file.
+        """
+        return self._header
+
+    @pdf_header.setter
+    def pdf_header(self, new_header: bytes) -> None:
+        self._header = new_header
+
+    def _add_object(self, obj: PdfObject) -> IndirectObject:
+        if hasattr(obj, "indirect_reference") and obj.indirect_reference.pdf == self:  # type: ignore
+            return obj.indirect_reference  # type: ignore
+        self._objects.append(obj)
+        obj.indirect_reference = IndirectObject(len(self._objects), 0, self)
+        return obj.indirect_reference
+
+    def get_object(
+        self,
+        indirect_reference: Union[None, int, IndirectObject] = None,
+        ido: Optional[IndirectObject] = None,
+    ) -> PdfObject:
+        if ido is not None:  # deprecated
+            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 4.0.0.",
+                    DeprecationWarning,
+                )
+        assert (
+            indirect_reference is not None
+        )  # the None value is only there to keep the deprecated name
+        if isinstance(indirect_reference, int):
+            return self._objects[indirect_reference - 1]
+        if indirect_reference.pdf != self:
+            raise ValueError("pdf must be self")
+        return self._objects[indirect_reference.idnum - 1]  # type: ignore
+
+    def getObject(
+        self, ido: Union[int, IndirectObject]
+    ) -> PdfObject:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :meth:`get_object` instead.
+        """
+        deprecation_with_replacement("getObject", "get_object", "3.0.0")
+        return self.get_object(ido)
+
+    def _add_page(
+        self,
+        page: PageObject,
+        action: Callable[[Any, IndirectObject], None],
+        excluded_keys: Iterable[str] = (),
+    ) -> PageObject:
+        assert cast(str, page[PA.TYPE]) == CO.PAGE
+        page_org = page
+        excluded_keys = list(excluded_keys)
+        excluded_keys += [PA.PARENT, "/StructParents"]
+        # acrobat does not accept to have two indirect ref pointing on the same page;
+        # therefore in order to add easily multiple copies of the same page, we need to create a new
+        # dictionary for the page, however the objects below (including content) is not duplicated
+        try:  # delete an already existing page
+            del self._id_translated[id(page_org.indirect_reference.pdf)][  # type: ignore
+                page_org.indirect_reference.idnum  # type: ignore
+            ]
+        except Exception:
+            pass
+        page = cast("PageObject", page_org.clone(self, False, excluded_keys))
+        # page_ind = self._add_object(page)
+        if page_org.pdf is not None:
+            other = page_org.pdf.pdf_header
+            if isinstance(other, str):
+                other = other.encode()  # type: ignore
+            self.pdf_header = _get_max_pdf_version_header(self.pdf_header, other)  # type: ignore
+        page[NameObject(PA.PARENT)] = self._pages
+        pages = cast(DictionaryObject, self.get_object(self._pages))
+        assert page.indirect_reference is not None
+        action(pages[PA.KIDS], page.indirect_reference)
+        page_count = cast(int, pages[PA.COUNT])
+        pages[NameObject(PA.COUNT)] = NumberObject(page_count + 1)
+        return page
+
+    def set_need_appearances_writer(self) -> None:
+        # See 12.7.2 and 7.7.2 for more information:
+        # http://www.adobe.com/content/dam/acom/en/devnet/acrobat/pdfs/PDF32000_2008.pdf
+        try:
+            catalog = self._root_object
+            # get the AcroForm tree
+            if CatalogDictionary.ACRO_FORM not in catalog:
+                self._root_object.update(
+                    {
+                        NameObject(CatalogDictionary.ACRO_FORM): IndirectObject(
+                            len(self._objects), 0, self
+                        )
+                    }
+                )
+
+            need_appearances = NameObject(InteractiveFormDictEntries.NeedAppearances)
+            self._root_object[CatalogDictionary.ACRO_FORM][need_appearances] = BooleanObject(True)  # type: ignore
+        except Exception as exc:
+            logger.error("set_need_appearances_writer() catch : ", repr(exc))
+
+    def add_page(
+        self,
+        page: PageObject,
+        excluded_keys: Iterable[str] = (),
+    ) -> PageObject:
+        """
+        Add a page to this PDF file.
+        Recommended for advanced usage including the adequate excluded_keys
+
+        The page is usually acquired from a :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>`
+        """
+        return self._add_page(page, list.append, excluded_keys)
+
+    def addPage(
+        self,
+        page: PageObject,
+        excluded_keys: Iterable[str] = (),
+    ) -> PageObject:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :meth:`add_page` instead.
+        """
+        deprecation_with_replacement("addPage", "add_page", "3.0.0")
+        return self.add_page(page, excluded_keys)
+
+    def insert_page(
+        self,
+        page: PageObject,
+        index: int = 0,
+        excluded_keys: Iterable[str] = (),
+    ) -> PageObject:
+        """
+        Insert a page in this PDF file. The page is usually acquired from a
+        :class:`PdfReader<PyPDF2.PdfReader>` instance.
+
+        :param PageObject page: The page to add to the document.
+        :param int index: Position at which the page will be inserted.
+        """
+        return self._add_page(page, lambda l, p: l.insert(index, p))
+
+    def insertPage(
+        self,
+        page: PageObject,
+        index: int = 0,
+        excluded_keys: Iterable[str] = (),
+    ) -> PageObject:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :meth:`insert_page` instead.
+        """
+        deprecation_with_replacement("insertPage", "insert_page", "3.0.0")
+        return self.insert_page(page, index, excluded_keys)
+
+    def get_page(
+        self, page_number: Optional[int] = None, pageNumber: Optional[int] = None
+    ) -> PageObject:
+        """
+        Retrieve a page by number from this PDF file.
+
+        :param int page_number: The page number to retrieve
+            (pages begin at zero)
+        :return: the page at the index given by *page_number*
+        """
+        if pageNumber is not None:  # pragma: no cover
+            if page_number is not None:
+                raise ValueError("Please only use the page_number parameter")
+            deprecate_with_replacement(
+                "get_page(pageNumber)", "get_page(page_number)", "4.0.0"
+            )
+            page_number = pageNumber
+        if page_number is None and pageNumber is None:  # pragma: no cover
+            raise ValueError("Please specify the page_number")
+        pages = cast(Dict[str, Any], self.get_object(self._pages))
+        # TODO: crude hack
+        return cast(PageObject, pages[PA.KIDS][page_number].get_object())
+
+    def getPage(self, pageNumber: int) -> PageObject:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :code:`writer.pages[page_number]` instead.
+        """
+        deprecation_with_replacement("getPage", "writer.pages[page_number]", "3.0.0")
+        return self.get_page(pageNumber)
+
+    def _get_num_pages(self) -> int:
+        pages = cast(Dict[str, Any], self.get_object(self._pages))
+        return int(pages[NameObject("/Count")])
+
+    def getNumPages(self) -> int:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :code:`len(writer.pages)` instead.
+        """
+        deprecation_with_replacement("getNumPages", "len(writer.pages)", "3.0.0")
+        return self._get_num_pages()
+
+    @property
+    def pages(self) -> List[PageObject]:
+        """Property that emulates a list of :class:`PageObject<PyPDF2._page.PageObject>`."""
+        return _VirtualList(self._get_num_pages, self.get_page)  # type: ignore
+
+    def add_blank_page(
+        self, width: Optional[float] = None, height: Optional[float] = None
+    ) -> PageObject:
+        """
+        Append a blank page to this PDF file and returns it. If no page size
+        is specified, use the size of the last page.
+
+        :param float width: The width of the new page expressed in default user
+            space units.
+        :param float height: The height of the new page expressed in default
+            user space units.
+        :return: the newly appended page
+        :raises PageSizeNotDefinedError: if width and height are not defined
+            and previous page does not exist.
+        """
+        page = PageObject.create_blank_page(self, width, height)
+        self.add_page(page)
+        return page
+
+    def addBlankPage(
+        self, width: Optional[float] = None, height: Optional[float] = None
+    ) -> PageObject:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :meth:`add_blank_page` instead.
+        """
+        deprecation_with_replacement("addBlankPage", "add_blank_page", "3.0.0")
+        return self.add_blank_page(width, height)
+
+    def insert_blank_page(
+        self,
+        width: Optional[decimal.Decimal] = None,
+        height: Optional[decimal.Decimal] = None,
+        index: int = 0,
+    ) -> PageObject:
+        """
+        Insert a blank page to this PDF file and returns it. If no page size
+        is specified, use the size of the last page.
+
+        :param float width: The width of the new page expressed in default user
+            space units.
+        :param float height: The height of the new page expressed in default
+            user space units.
+        :param int index: Position to add the page.
+        :return: the newly appended page
+        :raises PageSizeNotDefinedError: if width and height are not defined
+            and previous page does not exist.
+        """
+        if width is None or height is None and (self._get_num_pages() - 1) >= index:
+            oldpage = self.pages[index]
+            width = oldpage.mediabox.width
+            height = oldpage.mediabox.height
+        page = PageObject.create_blank_page(self, width, height)
+        self.insert_page(page, index)
+        return page
+
+    def insertBlankPage(
+        self,
+        width: Optional[decimal.Decimal] = None,
+        height: Optional[decimal.Decimal] = None,
+        index: int = 0,
+    ) -> PageObject:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :meth:`insertBlankPage` instead.
+        """
+        deprecation_with_replacement("insertBlankPage", "insert_blank_page", "3.0.0")
+        return self.insert_blank_page(width, height, index)
+
+    @property
+    def open_destination(
+        self,
+    ) -> 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.
+
+        :param destination:.
+        the property can be set to a Destination, a Page or an string(NamedDest) or
+            None (to remove "/OpenAction")
+
+        (value stored in "/OpenAction" entry in the Pdf Catalog)
+        """
+        if "/OpenAction" not in self._root_object:
+            return None
+        oa = self._root_object["/OpenAction"]
+        if isinstance(oa, (str, bytes)):
+            return create_string_object(str(oa))
+        elif isinstance(oa, ArrayObject):
+            try:
+                page, typ = oa[0:2]  # type: ignore
+                array = oa[2:]
+                fit = Fit(typ, tuple(array))
+                return Destination("OpenAction", page, fit)
+            except Exception as exc:
+                raise Exception(f"Invalid Destination {oa}: {exc}")
+        else:
+            return None
+
+    @open_destination.setter
+    def open_destination(self, dest: Union[None, str, Destination, PageObject]) -> None:
+        if dest is None:
+            try:
+                del self._root_object["/OpenAction"]
+            except KeyError:
+                pass
+        elif isinstance(dest, str):
+            self._root_object[NameObject("/OpenAction")] = TextStringObject(dest)
+        elif isinstance(dest, Destination):
+            self._root_object[NameObject("/OpenAction")] = dest.dest_array
+        elif isinstance(dest, PageObject):
+            self._root_object[NameObject("/OpenAction")] = Destination(
+                "Opening",
+                dest.indirect_reference
+                if dest.indirect_reference is not None
+                else NullObject(),
+                PAGE_FIT,
+            ).dest_array
+
+    def add_js(self, javascript: str) -> None:
+        """
+        Add Javascript which will launch upon opening this PDF.
+
+        :param str javascript: Your Javascript.
+
+        >>> output.add_js("this.print({bUI:true,bSilent:false,bShrinkToFit:true});")
+        # Example: This will launch the print window when the PDF is opened.
+        """
+        # Names / JavaScript prefered to be able to add multiple scripts
+        if "/Names" not in self._root_object:
+            self._root_object[NameObject(CA.NAMES)] = DictionaryObject()
+        names = cast(DictionaryObject, self._root_object[CA.NAMES])
+        if "/JavaScript" not in names:
+            names[NameObject("/JavaScript")] = DictionaryObject(
+                {NameObject("/Names"): ArrayObject()}
+            )
+            # cast(DictionaryObject, names[NameObject("/JavaScript")])[NameObject("/Names")] = ArrayObject()
+        js_list = cast(
+            ArrayObject, cast(DictionaryObject, names["/JavaScript"])["/Names"]
+        )
+
+        js = DictionaryObject()
+        js.update(
+            {
+                NameObject(PA.TYPE): NameObject("/Action"),
+                NameObject("/S"): NameObject("/JavaScript"),
+                NameObject("/JS"): TextStringObject(f"{javascript}"),
+            }
+        )
+        # We need a name for parameterized javascript in the pdf file, but it can be anything.
+        js_list.append(create_string_object(str(uuid.uuid4())))
+        js_list.append(self._add_object(js))
+
+    def addJS(self, javascript: str) -> None:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :meth:`add_js` instead.
+        """
+        deprecation_with_replacement("addJS", "add_js", "3.0.0")
+        return self.add_js(javascript)
+
+    def add_attachment(self, filename: str, data: Union[str, bytes]) -> None:
+        """
+        Embed a file inside the PDF.
+
+        :param str filename: The filename to display.
+        :param str data: The data in the file.
+
+        Reference:
+        https://www.adobe.com/content/dam/Adobe/en/devnet/acrobat/pdfs/PDF32000_2008.pdf
+        Section 7.11.3
+        """
+        # We need three entries:
+        # * The file's data
+        # * The /Filespec entry
+        # * The file's name, which goes in the Catalog
+
+        # The entry for the file
+        # Sample:
+        # 8 0 obj
+        # <<
+        #  /Length 12
+        #  /Type /EmbeddedFile
+        # >>
+        # stream
+        # Hello world!
+        # endstream
+        # endobj
+
+        file_entry = DecodedStreamObject()
+        file_entry.set_data(data)
+        file_entry.update({NameObject(PA.TYPE): NameObject("/EmbeddedFile")})
+
+        # The Filespec entry
+        # Sample:
+        # 7 0 obj
+        # <<
+        #  /Type /Filespec
+        #  /F (hello.txt)
+        #  /EF << /F 8 0 R >>
+        # >>
+
+        ef_entry = DictionaryObject()
+        ef_entry.update({NameObject("/F"): file_entry})
+
+        filespec = DictionaryObject()
+        filespec.update(
+            {
+                NameObject(PA.TYPE): NameObject("/Filespec"),
+                NameObject(FileSpecificationDictionaryEntries.F): create_string_object(
+                    filename
+                ),  # Perhaps also try TextStringObject
+                NameObject(FileSpecificationDictionaryEntries.EF): ef_entry,
+            }
+        )
+
+        # Then create the entry for the root, as it needs a reference to the Filespec
+        # Sample:
+        # 1 0 obj
+        # <<
+        #  /Type /Catalog
+        #  /Outlines 2 0 R
+        #  /Pages 3 0 R
+        #  /Names << /EmbeddedFiles << /Names [(hello.txt) 7 0 R] >> >>
+        # >>
+        # endobj
+
+        embedded_files_names_dictionary = DictionaryObject()
+        embedded_files_names_dictionary.update(
+            {
+                NameObject(CA.NAMES): ArrayObject(
+                    [create_string_object(filename), filespec]
+                )
+            }
+        )
+
+        embedded_files_dictionary = DictionaryObject()
+        embedded_files_dictionary.update(
+            {NameObject("/EmbeddedFiles"): embedded_files_names_dictionary}
+        )
+        # Update the root
+        self._root_object.update({NameObject(CA.NAMES): embedded_files_dictionary})
+
+    def addAttachment(
+        self, fname: str, fdata: Union[str, bytes]
+    ) -> None:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :meth:`add_attachment` instead.
+        """
+        deprecation_with_replacement("addAttachment", "add_attachment", "3.0.0")
+        return self.add_attachment(fname, fdata)
+
+    def append_pages_from_reader(
+        self,
+        reader: PdfReader,
+        after_page_append: Optional[Callable[[PageObject], None]] = None,
+    ) -> None:
+        """
+        Copy pages from reader to writer. Includes an optional callback parameter
+        which is invoked after pages are appended to the writer.
+
+        :param PdfReader reader: a PdfReader object from which to copy page
+            annotations to this writer object.  The writer's annots
+            will then be updated
+        :param Callable[[PageObject], None] after_page_append:
+            Callback function that is invoked after each page is appended to
+            the writer. Signature includes a reference to the appended page
+            (delegates to append_pages_from_reader). The single parameter of the
+            callback is a reference to the page just appended to the document.
+        """
+        # Get page count from writer and reader
+        reader_num_pages = len(reader.pages)
+        # Copy pages from reader to writer
+        for reader_page_number in range(reader_num_pages):
+            reader_page = reader.pages[reader_page_number]
+            writer_page = self.add_page(reader_page)
+            # Trigger callback, pass writer page as parameter
+            if callable(after_page_append):
+                after_page_append(writer_page)
+
+    def appendPagesFromReader(
+        self,
+        reader: PdfReader,
+        after_page_append: Optional[Callable[[PageObject], None]] = None,
+    ) -> None:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :meth:`append_pages_from_reader` instead.
+        """
+        deprecation_with_replacement(
+            "appendPagesFromReader", "append_pages_from_reader", "3.0.0"
+        )
+        self.append_pages_from_reader(reader, after_page_append)
+
+    def update_page_form_field_values(
+        self,
+        page: PageObject,
+        fields: Dict[str, Any],
+        flags: FieldFlag = OPTIONAL_READ_WRITE_FIELD,
+    ) -> None:
+        """
+        Update the form field values for a given page from a fields dictionary.
+
+        Copy field texts and values from fields to page.
+        If the field links to a parent object, add the information to the parent.
+
+        :param PageObject page: Page reference from PDF writer where the
+            annotations and field data will be updated.
+        :param dict fields: a Python dictionary of field names (/T) and text
+            values (/V)
+        :param int flags: An integer (0 to 7). The first bit sets ReadOnly, the
+            second bit sets Required, the third bit sets NoExport. See
+            PDF Reference Table 8.70 for details.
+        """
+        self.set_need_appearances_writer()
+        # Iterate through pages, update field values
+        if PG.ANNOTS not in page:
+            logger_warning("No fields to update on this page", __name__)
+            return
+        for j in range(len(page[PG.ANNOTS])):  # type: ignore
+            writer_annot = page[PG.ANNOTS][j].get_object()  # type: ignore
+            # retrieve parent field values, if present
+            writer_parent_annot = {}  # fallback if it's not there
+            if PG.PARENT in writer_annot:
+                writer_parent_annot = writer_annot[PG.PARENT]
+            for field in fields:
+                if writer_annot.get(FieldDictionaryAttributes.T) == field:
+                    if writer_annot.get(FieldDictionaryAttributes.FT) == "/Btn":
+                        writer_annot.update(
+                            {
+                                NameObject(
+                                    AnnotationDictionaryAttributes.AS
+                                ): NameObject(fields[field])
+                            }
+                        )
+                    writer_annot.update(
+                        {
+                            NameObject(FieldDictionaryAttributes.V): TextStringObject(
+                                fields[field]
+                            )
+                        }
+                    )
+                    if flags:
+                        writer_annot.update(
+                            {
+                                NameObject(FieldDictionaryAttributes.Ff): NumberObject(
+                                    flags
+                                )
+                            }
+                        )
+                elif writer_parent_annot.get(FieldDictionaryAttributes.T) == field:
+                    writer_parent_annot.update(
+                        {
+                            NameObject(FieldDictionaryAttributes.V): TextStringObject(
+                                fields[field]
+                            )
+                        }
+                    )
+
+    def updatePageFormFieldValues(
+        self,
+        page: PageObject,
+        fields: Dict[str, Any],
+        flags: FieldFlag = OPTIONAL_READ_WRITE_FIELD,
+    ) -> None:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :meth:`update_page_form_field_values` instead.
+        """
+        deprecation_with_replacement(
+            "updatePageFormFieldValues", "update_page_form_field_values", "3.0.0"
+        )
+        return self.update_page_form_field_values(page, fields, flags)
+
+    def clone_reader_document_root(self, reader: PdfReader) -> None:
+        """
+        Copy the reader document root to the writer.
+
+        :param reader:  PdfReader from the document root should be copied.
+        """
+        self._root_object = cast(DictionaryObject, reader.trailer[TK.ROOT])
+
+    def cloneReaderDocumentRoot(self, reader: PdfReader) -> None:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :meth:`clone_reader_document_root` instead.
+        """
+        deprecation_with_replacement(
+            "cloneReaderDocumentRoot", "clone_reader_document_root", "3.0.0"
+        )
+        self.clone_reader_document_root(reader)
+
+    def clone_document_from_reader(
+        self,
+        reader: PdfReader,
+        after_page_append: Optional[Callable[[PageObject], None]] = None,
+    ) -> None:
+        """
+        Create a copy (clone) of a document from a PDF file reader
+
+        :param reader: PDF file reader instance from which the clone
+            should be created.
+        :param Callable[[PageObject], None] after_page_append:
+            Callback function that is invoked after each page is appended to
+            the writer. Signature includes a reference to the appended page
+            (delegates to append_pages_from_reader). The single parameter of the
+            callback is a reference to the page just appended to the document.
+        """
+        # TODO : ppZZ may be limited because we do not copy all info...
+        self.clone_reader_document_root(reader)
+        self.append_pages_from_reader(reader, after_page_append)
+
+    def cloneDocumentFromReader(
+        self,
+        reader: PdfReader,
+        after_page_append: Optional[Callable[[PageObject], None]] = None,
+    ) -> None:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :meth:`clone_document_from_reader` instead.
+        """
+        deprecation_with_replacement(
+            "cloneDocumentFromReader", "clone_document_from_reader", "3.0.0"
+        )
+        self.clone_document_from_reader(reader, after_page_append)
+
+    def encrypt(
+        self,
+        user_password: Optional[str] = None,
+        owner_password: Optional[str] = None,
+        use_128bit: bool = True,
+        permissions_flag: UserAccessPermissions = ALL_DOCUMENT_PERMISSIONS,
+        user_pwd: Optional[str] = None,  # deprecated
+        owner_pwd: Optional[str] = None,  # deprecated
+    ) -> None:
+        """
+        Encrypt this PDF file with the PDF Standard encryption handler.
+
+        :param str user_password: The "user password", which allows for opening
+            and reading the PDF file with the restrictions provided.
+        :param str owner_password: The "owner password", which allows for
+            opening the PDF files without any restrictions.  By default,
+            the owner password is the same as the user password.
+        :param bool use_128bit: flag as to whether to use 128bit
+            encryption.  When false, 40bit encryption will be used.  By default,
+            this flag is on.
+        :param unsigned int permissions_flag: permissions as described in
+            TABLE 3.20 of the PDF 1.7 specification. A bit value of 1 means the
+            permission is grantend. Hence an integer value of -1 will set all
+            flags.
+            Bit position 3 is for printing, 4 is for modifying content, 5 and 6
+            control annotations, 9 for form fields, 10 for extraction of
+            text and graphics.
+        """
+        if user_pwd is not None:
+            if user_password is not None:
+                raise ValueError(
+                    "Please only set 'user_password'. "
+                    "The 'user_pwd' argument is deprecated."
+                )
+            else:
+                warnings.warn(
+                    "Please use 'user_password' instead of 'user_pwd'. "
+                    "The 'user_pwd' argument is deprecated and "
+                    "will be removed in PyPDF2 4.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 and will be "
+                        f"removed in PyPDF2 4.0.0. Use {new_term} instead"
+                    ),
+                    category=DeprecationWarning,
+                )
+                owner_password = owner_pwd
+
+        if owner_password is None:
+            owner_password = user_password
+        if use_128bit:
+            V = 2
+            rev = 3
+            keylen = int(128 / 8)
+        else:
+            V = 1
+            rev = 2
+            keylen = int(40 / 8)
+        P = permissions_flag
+        O = ByteStringObject(_alg33(owner_password, user_password, rev, keylen))  # type: ignore[arg-type]
+        ID_1 = ByteStringObject(md5((repr(time.time())).encode("utf8")).digest())
+        ID_2 = ByteStringObject(md5((repr(random.random())).encode("utf8")).digest())
+        self._ID = ArrayObject((ID_1, ID_2))
+        if rev == 2:
+            U, key = _alg34(user_password, O, P, ID_1)
+        else:
+            assert rev == 3
+            U, key = _alg35(user_password, rev, keylen, O, P, ID_1, False)  # type: ignore[arg-type]
+        encrypt = DictionaryObject()
+        encrypt[NameObject(SA.FILTER)] = NameObject("/Standard")
+        encrypt[NameObject("/V")] = NumberObject(V)
+        if V == 2:
+            encrypt[NameObject(SA.LENGTH)] = NumberObject(keylen * 8)
+        encrypt[NameObject(ED.R)] = NumberObject(rev)
+        encrypt[NameObject(ED.O)] = ByteStringObject(O)
+        encrypt[NameObject(ED.U)] = ByteStringObject(U)
+        encrypt[NameObject(ED.P)] = NumberObject(P)
+        self._encrypt = self._add_object(encrypt)
+        self._encrypt_key = key
+
+    def write_stream(self, stream: StreamType) -> None:
+        if hasattr(stream, "mode") and "b" not in stream.mode:
+            logger_warning(
+                f"File <{stream.name}> to write to is not in binary mode. "  # type: ignore
+                "It may not be written to correctly.",
+                __name__,
+            )
+
+        if not self._root:
+            self._root = self._add_object(self._root_object)
+
+        # PDF objects sometimes have circular references to their /Page objects
+        # inside their object tree (for example, annotations).  Those will be
+        # indirect references to objects that we've recreated in this PDF.  To
+        # address this problem, PageObject's store their original object
+        # reference number, and we add it to the external reference map before
+        # we sweep for indirect references.  This forces self-page-referencing
+        # trees to reference the correct new object location, rather than
+        # copying in a new copy of the page object.
+        self._sweep_indirect_references(self._root)
+
+        object_positions = self._write_header(stream)
+        xref_location = self._write_xref_table(stream, object_positions)
+        self._write_trailer(stream)
+        stream.write(b_(f"\nstartxref\n{xref_location}\n%%EOF\n"))  # eof
+
+    def write(self, stream: Union[Path, StrByteType]) -> Tuple[bool, IO]:
+        """
+        Write the collection of pages added to this object out as a PDF file.
+
+        :param stream: An object to write the file to.  The object can support
+            the write method and the tell method, similar to a file object, or
+            be a file path, just like the fileobj, just named it stream to keep
+            existing workflow.
+        """
+        my_file = False
+
+        if stream == "":
+            raise ValueError(f"Output(stream={stream}) is empty.")
+
+        if isinstance(stream, (str, Path)):
+            stream = FileIO(stream, "wb")
+            self.with_as_usage = True  #
+            my_file = True
+
+        self.write_stream(stream)
+
+        if self.with_as_usage:
+            stream.close()
+
+        return my_file, stream
+
+    def _write_header(self, stream: StreamType) -> List[int]:
+        object_positions = []
+        stream.write(self.pdf_header + b"\n")
+        stream.write(b"%\xE2\xE3\xCF\xD3\n")
+        for i, obj in enumerate(self._objects):
+            obj = self._objects[i]
+            # If the obj is None we can't write anything
+            if obj is not None:
+                idnum = i + 1
+                object_positions.append(stream.tell())
+                stream.write(b_(str(idnum)) + b" 0 obj\n")
+                key = None
+                if hasattr(self, "_encrypt") and idnum != self._encrypt.idnum:
+                    pack1 = struct.pack("<i", i + 1)[:3]
+                    pack2 = struct.pack("<i", 0)[:2]
+                    key = self._encrypt_key + pack1 + pack2
+                    assert len(key) == (len(self._encrypt_key) + 5)
+                    md5_hash = md5(key).digest()
+                    key = md5_hash[: min(16, len(self._encrypt_key) + 5)]
+                obj.write_to_stream(stream, key)
+                stream.write(b"\nendobj\n")
+        return object_positions
+
+    def _write_xref_table(self, stream: StreamType, object_positions: List[int]) -> int:
+        xref_location = stream.tell()
+        stream.write(b"xref\n")
+        stream.write(b_(f"0 {len(self._objects) + 1}\n"))
+        stream.write(b_(f"{0:0>10} {65535:0>5} f \n"))
+        for offset in object_positions:
+            stream.write(b_(f"{offset:0>10} {0:0>5} n \n"))
+        return xref_location
+
+    def _write_trailer(self, stream: StreamType) -> None:
+        stream.write(b"trailer\n")
+        trailer = DictionaryObject()
+        trailer.update(
+            {
+                NameObject(TK.SIZE): NumberObject(len(self._objects) + 1),
+                NameObject(TK.ROOT): self._root,
+                NameObject(TK.INFO): self._info,
+            }
+        )
+        if hasattr(self, "_ID"):
+            trailer[NameObject(TK.ID)] = self._ID
+        if hasattr(self, "_encrypt"):
+            trailer[NameObject(TK.ENCRYPT)] = self._encrypt
+        trailer.write_to_stream(stream, None)
+
+    def add_metadata(self, infos: Dict[str, Any]) -> None:
+        """
+        Add custom metadata to the output.
+
+        :param dict infos: a Python dictionary where each key is a field
+            and each value is your new metadata.
+        """
+        args = {}
+        for key, value in list(infos.items()):
+            args[NameObject(key)] = create_string_object(value)
+        self.get_object(self._info).update(args)  # type: ignore
+
+    def addMetadata(self, infos: Dict[str, Any]) -> None:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :meth:`add_metadata` instead.
+        """
+        deprecation_with_replacement("addMetadata", "add_metadata", "3.0.0")
+        self.add_metadata(infos)
+
+    def _sweep_indirect_references(
+        self,
+        root: Union[
+            ArrayObject,
+            BooleanObject,
+            DictionaryObject,
+            FloatObject,
+            IndirectObject,
+            NameObject,
+            PdfObject,
+            NumberObject,
+            TextStringObject,
+            NullObject,
+        ],
+    ) -> None:
+        stack: Deque[
+            Tuple[
+                Any,
+                Optional[Any],
+                Any,
+                List[PdfObject],
+            ]
+        ] = collections.deque()
+        discovered = []
+        parent = None
+        grant_parents: List[PdfObject] = []
+        key_or_id = None
+
+        # Start from root
+        stack.append((root, parent, key_or_id, grant_parents))
+
+        while len(stack):
+            data, parent, key_or_id, grant_parents = stack.pop()
+
+            # Build stack for a processing depth-first
+            if isinstance(data, (ArrayObject, DictionaryObject)):
+                for key, value in data.items():
+                    stack.append(
+                        (
+                            value,
+                            data,
+                            key,
+                            grant_parents + [parent] if parent is not None else [],
+                        )
+                    )
+            elif isinstance(data, IndirectObject):
+                if data.pdf != self:
+                    data = self._resolve_indirect_object(data)
+
+                    if str(data) not in discovered:
+                        discovered.append(str(data))
+                        stack.append((data.get_object(), None, None, []))
+
+            # Check if data has a parent and if it is a dict or an array update the value
+            if isinstance(parent, (DictionaryObject, ArrayObject)):
+                if isinstance(data, StreamObject):
+                    # a dictionary value is a stream.  streams must be indirect
+                    # objects, so we need to change this value.
+                    data = self._resolve_indirect_object(self._add_object(data))
+
+                update_hashes = []
+
+                # Data changed and thus the hash value changed
+                if parent[key_or_id] != data:
+                    update_hashes = [parent.hash_value()] + [
+                        grant_parent.hash_value() for grant_parent in grant_parents
+                    ]
+                    parent[key_or_id] = data
+
+                # Update old hash value to new hash value
+                for old_hash in update_hashes:
+                    indirect_reference = self._idnum_hash.pop(old_hash, None)
+
+                    if indirect_reference is not None:
+                        indirect_reference_obj = indirect_reference.get_object()
+
+                        if indirect_reference_obj is not None:
+                            self._idnum_hash[
+                                indirect_reference_obj.hash_value()
+                            ] = indirect_reference
+
+    def _resolve_indirect_object(self, data: IndirectObject) -> IndirectObject:
+        """
+        Resolves indirect object to this pdf indirect objects.
+
+        If it is a new object then it is added to self._objects
+        and new idnum is given and generation is always 0.
+        """
+        if hasattr(data.pdf, "stream") and data.pdf.stream.closed:
+            raise ValueError(f"I/O operation on closed file: {data.pdf.stream.name}")
+
+        if data.pdf == self:
+            return data
+
+        # Get real object indirect object
+        real_obj = data.pdf.get_object(data)
+
+        if real_obj is None:
+            logger_warning(
+                f"Unable to resolve [{data.__class__.__name__}: {data}], "
+                "returning NullObject instead",
+                __name__,
+            )
+            real_obj = NullObject()
+
+        hash_value = real_obj.hash_value()
+
+        # Check if object is handled
+        if hash_value in self._idnum_hash:
+            return self._idnum_hash[hash_value]
+
+        if data.pdf == self:
+            self._idnum_hash[hash_value] = IndirectObject(data.idnum, 0, self)
+        # This is new object in this pdf
+        else:
+            self._idnum_hash[hash_value] = self._add_object(real_obj)
+
+        return self._idnum_hash[hash_value]
+
+    def get_reference(self, obj: PdfObject) -> IndirectObject:
+        idnum = self._objects.index(obj) + 1
+        ref = IndirectObject(idnum, 0, self)
+        assert ref.get_object() == obj
+        return ref
+
+    def getReference(self, obj: PdfObject) -> IndirectObject:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :meth:`get_reference` instead.
+        """
+        deprecation_with_replacement("getReference", "get_reference", "3.0.0")
+        return self.get_reference(obj)
+
+    def get_outline_root(self) -> TreeObject:
+        if CO.OUTLINES in self._root_object:
+            # TABLE 3.25 Entries in the catalog dictionary
+            outline = cast(TreeObject, self._root_object[CO.OUTLINES])
+            idnum = self._objects.index(outline) + 1
+            outline_ref = IndirectObject(idnum, 0, self)
+            assert outline_ref.get_object() == outline
+        else:
+            outline = TreeObject()
+            outline.update({})
+            outline_ref = self._add_object(outline)
+            self._root_object[NameObject(CO.OUTLINES)] = outline_ref
+
+        return outline
+
+    def get_threads_root(self) -> ArrayObject:
+        """
+        the list of threads see §8.3.2 from PDF 1.7 spec
+
+                :return: an Array (possibly empty) of Dictionaries with "/F" and "/I" properties
+        """
+        if CO.THREADS in self._root_object:
+            # TABLE 3.25 Entries in the catalog dictionary
+            threads = cast(ArrayObject, self._root_object[CO.THREADS])
+        else:
+            threads = ArrayObject()
+            self._root_object[NameObject(CO.THREADS)] = threads
+        return threads
+
+    @property
+    def threads(self) -> ArrayObject:
+        """
+        Read-only property for the list of threads see §8.3.2 from PDF 1.7 spec
+
+        :return: an Array (possibly empty) of Dictionaries with "/F" and "/I" properties
+        """
+        return self.get_threads_root()
+
+    def getOutlineRoot(self) -> TreeObject:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :meth:`get_outline_root` instead.
+        """
+        deprecation_with_replacement("getOutlineRoot", "get_outline_root", "3.0.0")
+        return self.get_outline_root()
+
+    def get_named_dest_root(self) -> ArrayObject:
+        if CA.NAMES in self._root_object and isinstance(
+            self._root_object[CA.NAMES], DictionaryObject
+        ):
+            names = cast(DictionaryObject, self._root_object[CA.NAMES])
+            names_ref = names.indirect_reference
+            if CA.DESTS in names and isinstance(names[CA.DESTS], DictionaryObject):
+                # 3.6.3 Name Dictionary (PDF spec 1.7)
+                dests = cast(DictionaryObject, names[CA.DESTS])
+                dests_ref = dests.indirect_reference
+                if CA.NAMES in dests:
+                    # TABLE 3.33 Entries in a name tree node dictionary
+                    nd = cast(ArrayObject, dests[CA.NAMES])
+                else:
+                    nd = ArrayObject()
+                    dests[NameObject(CA.NAMES)] = nd
+            else:
+                dests = DictionaryObject()
+                dests_ref = self._add_object(dests)
+                names[NameObject(CA.DESTS)] = dests_ref
+                nd = ArrayObject()
+                dests[NameObject(CA.NAMES)] = nd
+
+        else:
+            names = DictionaryObject()
+            names_ref = self._add_object(names)
+            self._root_object[NameObject(CA.NAMES)] = names_ref
+            dests = DictionaryObject()
+            dests_ref = self._add_object(dests)
+            names[NameObject(CA.DESTS)] = dests_ref
+            nd = ArrayObject()
+            dests[NameObject(CA.NAMES)] = nd
+
+        return nd
+
+    def getNamedDestRoot(self) -> ArrayObject:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :meth:`get_named_dest_root` instead.
+        """
+        deprecation_with_replacement("getNamedDestRoot", "get_named_dest_root", "3.0.0")
+        return self.get_named_dest_root()
+
+    def add_outline_item_destination(
+        self,
+        page_destination: Union[None, PageObject, TreeObject] = None,
+        parent: Union[None, TreeObject, IndirectObject] = None,
+        before: 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 and will be "
+                    f"removed in PyPDF2 4.0.0. Use {new_term} instead"
+                ),
+                category=DeprecationWarning,
+            )
+            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()
+
+        parent = cast(TreeObject, parent.get_object())
+        page_destination_ref = self._add_object(page_destination)
+        if before is not None:
+            before = before.indirect_reference
+        parent.insert_child(page_destination_ref, before, self)
+
+        return page_destination_ref
+
+    def add_bookmark_destination(
+        self,
+        dest: Union[PageObject, TreeObject],
+        parent: Union[None, TreeObject, IndirectObject] = None,
+    ) -> IndirectObject:  # pragma: no cover
+        """
+        .. deprecated:: 2.9.0
+
+            Use :meth:`add_outline_item_destination` instead.
+        """
+        deprecation_with_replacement(
+            "add_bookmark_destination", "add_outline_item_destination", "3.0.0"
+        )
+        return self.add_outline_item_destination(dest, parent)
+
+    def addBookmarkDestination(
+        self, dest: PageObject, parent: Optional[TreeObject] = None
+    ) -> IndirectObject:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :meth:`add_outline_item_destination` instead.
+        """
+        deprecation_with_replacement(
+            "addBookmarkDestination", "add_outline_item_destination", "3.0.0"
+        )
+        return self.add_outline_item_destination(dest, parent)
+
+    @deprecation_bookmark(bookmark="outline_item")
+    def add_outline_item_dict(
+        self,
+        outline_item: OutlineItemType,
+        parent: Union[None, TreeObject, IndirectObject] = None,
+        before: Union[None, TreeObject, IndirectObject] = None,
+    ) -> IndirectObject:
+        outline_item_object = TreeObject()
+        for k, v in list(outline_item.items()):
+            outline_item_object[NameObject(str(k))] = v
+        outline_item_object.update(outline_item)
+
+        if "/A" in outline_item:
+            action = DictionaryObject()
+            a_dict = cast(DictionaryObject, outline_item["/A"])
+            for k, v in list(a_dict.items()):
+                action[NameObject(str(k))] = v
+            action_ref = self._add_object(action)
+            outline_item_object[NameObject("/A")] = action_ref
+
+        return self.add_outline_item_destination(outline_item_object, parent, before)
+
+    @deprecation_bookmark(bookmark="outline_item")
+    def add_bookmark_dict(
+        self, outline_item: OutlineItemType, parent: Optional[TreeObject] = None
+    ) -> IndirectObject:  # pragma: no cover
+        """
+        .. deprecated:: 2.9.0
+
+            Use :meth:`add_outline_item_dict` instead.
+        """
+        deprecation_with_replacement(
+            "add_bookmark_dict", "add_outline_item_dict", "3.0.0"
+        )
+        return self.add_outline_item_dict(outline_item, parent)
+
+    @deprecation_bookmark(bookmark="outline_item")
+    def addBookmarkDict(
+        self, outline_item: OutlineItemType, parent: Optional[TreeObject] = None
+    ) -> IndirectObject:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :meth:`add_outline_item_dict` instead.
+        """
+        deprecation_with_replacement(
+            "addBookmarkDict", "add_outline_item_dict", "3.0.0"
+        )
+        return self.add_outline_item_dict(outline_item, parent)
+
+    def add_outline_item(
+        self,
+        title: str,
+        page_number: Union[None, PageObject, IndirectObject, int],
+        parent: Union[None, TreeObject, IndirectObject] = None,
+        before: Union[None, TreeObject, IndirectObject] = None,
+        color: Optional[Union[Tuple[float, float, float], str]] = None,
+        bold: bool = False,
+        italic: bool = False,
+        fit: Fit = PAGE_FIT,
+        pagenum: Optional[int] = None,  # deprecated
+    ) -> IndirectObject:
+        """
+        Add an outline item (commonly referred to as a "Bookmark") to this PDF file.
+
+        :param str title: Title to use for this outline item.
+        :param int page_number: Page number this outline item will point to.
+        :param parent: A reference to a parent outline item to create nested
+            outline items.
+        :param parent: A reference to a parent outline item to create nested
+            outline items.
+        :param tuple color: Color of the outline item's font as a red, green, blue tuple
+            from 0.0 to 1.0 or as a Hex String (#RRGGBB)
+        :param bool bold: Outline item font is bold
+        :param bool italic: Outline item font is italic
+        :param Fit fit: The fit of the destination page.
+        """
+        page_ref: Union[None, NullObject, IndirectObject, NumberObject]
+        if isinstance(italic, Fit):  # it means that we are on the old params
+            if fit is not None and page_number is None:
+                page_number = fit  # type: ignore
+            return self.add_outline_item(
+                title, page_number, parent, None, before, color, bold, italic  # type: ignore
+            )
+        if page_number is not None and pagenum is not None:
+            raise ValueError(
+                "The argument pagenum of add_outline_item is deprecated. Use page_number only."
+            )
+        if page_number is None:
+            action_ref = None
+        else:
+            if isinstance(page_number, IndirectObject):
+                page_ref = page_number
+            elif isinstance(page_number, PageObject):
+                page_ref = page_number.indirect_reference
+            elif isinstance(page_number, int):
+                try:
+                    page_ref = self.pages[page_number].indirect_reference
+                except IndexError:
+                    page_ref = NumberObject(page_number)
+            if page_ref is None:
+                logger_warning(
+                    f"can not find reference of page {page_number}",
+                    __name__,
+                )
+                page_ref = NullObject()
+            dest = Destination(
+                NameObject("/" + title + " outline item"),
+                page_ref,
+                fit,
+            )
+
+            action_ref = self._add_object(
+                DictionaryObject(
+                    {
+                        NameObject(GoToActionArguments.D): dest.dest_array,
+                        NameObject(GoToActionArguments.S): NameObject("/GoTo"),
+                    }
+                )
+            )
+        outline_item = _create_outline_item(action_ref, title, color, italic, bold)
+
+        if parent is None:
+            parent = self.get_outline_root()
+        return self.add_outline_item_destination(outline_item, parent, before)
+
+    def add_bookmark(
+        self,
+        title: str,
+        pagenum: int,  # deprecated, but the whole method is deprecated
+        parent: Union[None, TreeObject, IndirectObject] = None,
+        color: Optional[Tuple[float, float, float]] = None,
+        bold: bool = False,
+        italic: bool = False,
+        fit: FitType = "/Fit",
+        *args: ZoomArgType,
+    ) -> IndirectObject:  # pragma: no cover
+        """
+        .. deprecated:: 2.9.0
+
+            Use :meth:`add_outline_item` instead.
+        """
+        deprecation_with_replacement("add_bookmark", "add_outline_item", "3.0.0")
+        return self.add_outline_item(
+            title,
+            pagenum,
+            parent,
+            color,  # type: ignore
+            bold,  # type: ignore
+            italic,
+            Fit(fit_type=fit, fit_args=args),  # type: ignore
+        )
+
+    def addBookmark(
+        self,
+        title: str,
+        pagenum: int,
+        parent: Union[None, TreeObject, IndirectObject] = None,
+        color: Optional[Tuple[float, float, float]] = None,
+        bold: bool = False,
+        italic: bool = False,
+        fit: FitType = "/Fit",
+        *args: ZoomArgType,
+    ) -> IndirectObject:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :meth:`add_outline_item` instead.
+        """
+        deprecation_with_replacement("addBookmark", "add_outline_item", "3.0.0")
+        return self.add_outline_item(
+            title,
+            pagenum,
+            parent,
+            None,
+            color,
+            bold,
+            italic,
+            Fit(fit_type=fit, fit_args=args),
+        )
+
+    def add_outline(self) -> None:
+        raise NotImplementedError(
+            "This method is not yet implemented. Use :meth:`add_outline_item` instead."
+        )
+
+    def add_named_destination_array(
+        self, title: TextStringObject, destination: Union[IndirectObject, ArrayObject]
+    ) -> None:
+        nd = self.get_named_dest_root()
+        i = 0
+        while i < len(nd):
+            if title < nd[i]:
+                nd.insert(i, destination)
+                nd.insert(i, TextStringObject(title))
+                return
+            else:
+                i += 2
+        nd.extend([TextStringObject(title), destination])
+        return
+
+    def add_named_destination_object(
+        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 and will be "
+                    f"removed in PyPDF2 4.0.0. Use {new_term} instead"
+                ),
+                category=DeprecationWarning,
+            )
+            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.dest_array)  # type: ignore
+        self.add_named_destination_array(
+            cast("TextStringObject", page_destination["/Title"]), page_destination_ref  # type: ignore
+        )
+
+        return page_destination_ref
+
+    def addNamedDestinationObject(
+        self, dest: Destination
+    ) -> IndirectObject:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :meth:`add_named_destination_object` instead.
+        """
+        deprecation_with_replacement(
+            "addNamedDestinationObject", "add_named_destination_object", "3.0.0"
+        )
+        return self.add_named_destination_object(dest)
+
+    def add_named_destination(
+        self,
+        title: str,
+        page_number: Optional[int] = None,
+        pagenum: Optional[int] = None,  # deprecated
+    ) -> IndirectObject:
+        if page_number is not None and pagenum is not None:
+            raise ValueError(
+                "The argument pagenum of add_outline_item is deprecated. Use page_number only."
+            )
+        if pagenum is not None:
+            old_term = "pagenum"
+            new_term = "page_number"
+            warnings.warn(
+                message=(
+                    f"{old_term} is deprecated as an argument and will be "
+                    f"removed in PyPDF2 4.0.0. Use {new_term} instead"
+                ),
+                category=DeprecationWarning,
+            )
+            page_number = pagenum
+        if page_number is None:
+            raise ValueError("page_number may not be None")
+        page_ref = self.get_object(self._pages)[PA.KIDS][page_number]  # type: ignore
+        dest = DictionaryObject()
+        dest.update(
+            {
+                NameObject(GoToActionArguments.D): ArrayObject(
+                    [page_ref, NameObject(TypFitArguments.FIT_H), NumberObject(826)]
+                ),
+                NameObject(GoToActionArguments.S): NameObject("/GoTo"),
+            }
+        )
+
+        dest_ref = self._add_object(dest)
+        nd = self.get_named_dest_root()
+        if not isinstance(title, TextStringObject):
+            title = TextStringObject(str(title))
+        nd.extend([title, dest_ref])
+        return dest_ref
+
+    def addNamedDestination(
+        self, title: str, pagenum: int
+    ) -> IndirectObject:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :meth:`add_named_destination` instead.
+        """
+        deprecation_with_replacement(
+            "addNamedDestination", "add_named_destination", "3.0.0"
+        )
+        return self.add_named_destination(title, pagenum)
+
+    def remove_links(self) -> None:
+        """Remove links and annotations from this output."""
+        pg_dict = cast(DictionaryObject, self.get_object(self._pages))
+        pages = cast(ArrayObject, pg_dict[PA.KIDS])
+        for page in pages:
+            page_ref = cast(DictionaryObject, self.get_object(page))
+            if PG.ANNOTS in page_ref:
+                del page_ref[PG.ANNOTS]
+
+    def removeLinks(self) -> None:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :meth:`remove_links` instead.
+        """
+        deprecation_with_replacement("removeLinks", "remove_links", "3.0.0")
+        return self.remove_links()
+
+    def remove_images(self, ignore_byte_string_object: bool = False) -> None:
+        """
+        Remove images from this output.
+
+        :param bool ignore_byte_string_object: optional parameter
+            to ignore ByteString Objects.
+        """
+        pg_dict = cast(DictionaryObject, self.get_object(self._pages))
+        pages = cast(ArrayObject, pg_dict[PA.KIDS])
+        jump_operators = (
+            b"cm",
+            b"w",
+            b"J",
+            b"j",
+            b"M",
+            b"d",
+            b"ri",
+            b"i",
+            b"gs",
+            b"W",
+            b"b",
+            b"s",
+            b"S",
+            b"f",
+            b"F",
+            b"n",
+            b"m",
+            b"l",
+            b"c",
+            b"v",
+            b"y",
+            b"h",
+            b"B",
+            b"Do",
+            b"sh",
+        )
+        for page in pages:
+            page_ref = cast(DictionaryObject, self.get_object(page))
+            content = page_ref["/Contents"].get_object()
+            if not isinstance(content, ContentStream):
+                content = ContentStream(content, page_ref)
+
+            _operations = []
+            seq_graphics = False
+            for operands, operator in content.operations:
+                if operator in [b"Tj", b"'"]:
+                    text = operands[0]
+                    if ignore_byte_string_object and not isinstance(
+                        text, TextStringObject
+                    ):
+                        operands[0] = TextStringObject()
+                elif operator == b'"':
+                    text = operands[2]
+                    if ignore_byte_string_object and not isinstance(
+                        text, TextStringObject
+                    ):
+                        operands[2] = TextStringObject()
+                elif operator == b"TJ":
+                    for i in range(len(operands[0])):
+                        if ignore_byte_string_object and not isinstance(
+                            operands[0][i], TextStringObject
+                        ):
+                            operands[0][i] = TextStringObject()
+
+                if operator == b"q":
+                    seq_graphics = True
+                if operator == b"Q":
+                    seq_graphics = False
+                if seq_graphics and operator in jump_operators:
+                    continue
+                if operator == b"re":
+                    continue
+                _operations.append((operands, operator))
+
+            content.operations = _operations
+            page_ref.__setitem__(NameObject("/Contents"), content)
+
+    def removeImages(
+        self, ignoreByteStringObject: bool = False
+    ) -> None:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :meth:`remove_images` instead.
+        """
+        deprecation_with_replacement("removeImages", "remove_images", "3.0.0")
+        return self.remove_images(ignoreByteStringObject)
+
+    def remove_text(self, ignore_byte_string_object: bool = False) -> None:
+        """
+        Remove text from this output.
+
+        :param bool ignore_byte_string_object: optional parameter
+            to ignore ByteString Objects.
+        """
+        pg_dict = cast(DictionaryObject, self.get_object(self._pages))
+        pages = cast(List[IndirectObject], pg_dict[PA.KIDS])
+        for page in pages:
+            page_ref = cast(PageObject, self.get_object(page))
+            content = page_ref["/Contents"].get_object()
+            if not isinstance(content, ContentStream):
+                content = ContentStream(content, page_ref)
+            for operands, operator in content.operations:
+                if operator in [b"Tj", b"'"]:
+                    text = operands[0]
+                    if not ignore_byte_string_object:
+                        if isinstance(text, TextStringObject):
+                            operands[0] = TextStringObject()
+                    else:
+                        if isinstance(text, (TextStringObject, ByteStringObject)):
+                            operands[0] = TextStringObject()
+                elif operator == b'"':
+                    text = operands[2]
+                    if not ignore_byte_string_object:
+                        if isinstance(text, TextStringObject):
+                            operands[2] = TextStringObject()
+                    else:
+                        if isinstance(text, (TextStringObject, ByteStringObject)):
+                            operands[2] = TextStringObject()
+                elif operator == b"TJ":
+                    for i in range(len(operands[0])):
+                        if not ignore_byte_string_object:
+                            if isinstance(operands[0][i], TextStringObject):
+                                operands[0][i] = TextStringObject()
+                        else:
+                            if isinstance(
+                                operands[0][i], (TextStringObject, ByteStringObject)
+                            ):
+                                operands[0][i] = TextStringObject()
+
+            page_ref.__setitem__(NameObject("/Contents"), content)
+
+    def removeText(
+        self, ignoreByteStringObject: bool = False
+    ) -> None:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :meth:`remove_text` instead.
+        """
+        deprecation_with_replacement("removeText", "remove_text", "3.0.0")
+        return self.remove_text(ignoreByteStringObject)
+
+    def add_uri(
+        self,
+        page_number: int,
+        uri: str,
+        rect: RectangleObject,
+        border: Optional[ArrayObject] = None,
+        pagenum: Optional[int] = None,
+    ) -> None:
+        """
+        Add an URI from a rectangular area to the specified page.
+        This uses the basic structure of :meth:`add_link`
+
+        :param int page_number: index of the page on which to place the URI action.
+        :param str uri: URI of resource to link to.
+        :param Tuple[int, int, int, int] rect: :class:`RectangleObject<PyPDF2.generic.RectangleObject>` or array of four
+            integers specifying the clickable rectangular area
+            ``[xLL, yLL, xUR, yUR]``, or string in the form ``"[ xLL yLL xUR yUR ]"``.
+        :param ArrayObject border: if provided, an array describing border-drawing
+            properties. See the PDF spec for details. No border will be
+            drawn if this argument is omitted.
+        """
+        if pagenum is not None:
+            warnings.warn(
+                "The 'pagenum' argument of add_uri is deprecated and will be "
+                "removed in PyPDF2 4.0.0. Use 'page_number' instead.",
+                category=DeprecationWarning,
+            )
+            page_number = pagenum
+        page_link = self.get_object(self._pages)[PA.KIDS][page_number]  # type: ignore
+        page_ref = cast(Dict[str, Any], self.get_object(page_link))
+
+        border_arr: BorderArrayType
+        if border is not None:
+            border_arr = [NameObject(n) for n in border[:3]]
+            if len(border) == 4:
+                dash_pattern = ArrayObject([NameObject(n) for n in border[3]])
+                border_arr.append(dash_pattern)
+        else:
+            border_arr = [NumberObject(2)] * 3
+
+        if isinstance(rect, str):
+            rect = NameObject(rect)
+        elif isinstance(rect, RectangleObject):
+            pass
+        else:
+            rect = RectangleObject(rect)
+
+        lnk2 = DictionaryObject()
+        lnk2.update(
+            {
+                NameObject("/S"): NameObject("/URI"),
+                NameObject("/URI"): TextStringObject(uri),
+            }
+        )
+        lnk = DictionaryObject()
+        lnk.update(
+            {
+                NameObject(AnnotationDictionaryAttributes.Type): NameObject(PG.ANNOTS),
+                NameObject(AnnotationDictionaryAttributes.Subtype): NameObject("/Link"),
+                NameObject(AnnotationDictionaryAttributes.P): page_link,
+                NameObject(AnnotationDictionaryAttributes.Rect): rect,
+                NameObject("/H"): NameObject("/I"),
+                NameObject(AnnotationDictionaryAttributes.Border): ArrayObject(
+                    border_arr
+                ),
+                NameObject("/A"): lnk2,
+            }
+        )
+        lnk_ref = self._add_object(lnk)
+
+        if PG.ANNOTS in page_ref:
+            page_ref[PG.ANNOTS].append(lnk_ref)
+        else:
+            page_ref[NameObject(PG.ANNOTS)] = ArrayObject([lnk_ref])
+
+    def addURI(
+        self,
+        pagenum: int,  # deprecated, but method is deprecated already
+        uri: str,
+        rect: RectangleObject,
+        border: Optional[ArrayObject] = None,
+    ) -> None:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :meth:`add_uri` instead.
+        """
+        deprecation_with_replacement("addURI", "add_uri", "3.0.0")
+        return self.add_uri(pagenum, uri, rect, border)
+
+    def add_link(
+        self,
+        pagenum: int,  # deprecated, but method is deprecated already
+        page_destination: int,
+        rect: RectangleObject,
+        border: Optional[ArrayObject] = None,
+        fit: FitType = "/Fit",
+        *args: ZoomArgType,
+    ) -> None:
+        deprecation_with_replacement(
+            "add_link", "add_annotation(AnnotationBuilder.link(...))"
+        )
+
+        if isinstance(rect, str):
+            rect = rect.strip()[1:-1]
+            rect = RectangleObject(
+                [float(num) for num in rect.split(" ") if len(num) > 0]
+            )
+        elif isinstance(rect, RectangleObject):
+            pass
+        else:
+            rect = RectangleObject(rect)
+
+        annotation = AnnotationBuilder.link(
+            rect=rect,
+            border=border,
+            target_page_index=page_destination,
+            fit=Fit(fit_type=fit, fit_args=args),
+        )
+        return self.add_annotation(page_number=pagenum, annotation=annotation)
+
+    def addLink(
+        self,
+        pagenum: int,  # deprecated, but method is deprecated already
+        page_destination: int,
+        rect: RectangleObject,
+        border: Optional[ArrayObject] = None,
+        fit: FitType = "/Fit",
+        *args: ZoomArgType,
+    ) -> None:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :meth:`add_link` instead.
+        """
+        deprecate_with_replacement(
+            "addLink", "add_annotation(AnnotationBuilder.link(...))", "4.0.0"
+        )
+        return self.add_link(pagenum, page_destination, rect, border, fit, *args)
+
+    _valid_layouts = (
+        "/NoLayout",
+        "/SinglePage",
+        "/OneColumn",
+        "/TwoColumnLeft",
+        "/TwoColumnRight",
+        "/TwoPageLeft",
+        "/TwoPageRight",
+    )
+
+    def _get_page_layout(self) -> Optional[LayoutType]:
+        try:
+            return cast(LayoutType, self._root_object["/PageLayout"])
+        except KeyError:
+            return None
+
+    def getPageLayout(self) -> Optional[LayoutType]:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :py:attr:`page_layout` instead.
+        """
+        deprecation_with_replacement("getPageLayout", "page_layout", "3.0.0")
+        return self._get_page_layout()
+
+    def _set_page_layout(self, layout: Union[NameObject, LayoutType]) -> None:
+        """
+        Set the page layout.
+
+        :param str layout: The page layout to be used.
+
+        .. list-table:: Valid ``layout`` arguments
+           :widths: 50 200
+
+           * - /NoLayout
+             - Layout explicitly not specified
+           * - /SinglePage
+             - Show one page at a time
+           * - /OneColumn
+             - Show one column at a time
+           * - /TwoColumnLeft
+             - Show pages in two columns, odd-numbered pages on the left
+           * - /TwoColumnRight
+             - Show pages in two columns, odd-numbered pages on the right
+           * - /TwoPageLeft
+             - Show two pages at a time, odd-numbered pages on the left
+           * - /TwoPageRight
+             - Show two pages at a time, odd-numbered pages on the right
+        """
+        if not isinstance(layout, NameObject):
+            if layout not in self._valid_layouts:
+                logger_warning(
+                    f"Layout should be one of: {'', ''.join(self._valid_layouts)}",
+                    __name__,
+                )
+            layout = NameObject(layout)
+        self._root_object.update({NameObject("/PageLayout"): layout})
+
+    def set_page_layout(self, layout: LayoutType) -> None:
+        """
+        Set the page layout.
+
+        :param str layout: The page layout to be used
+
+        .. list-table:: Valid ``layout`` arguments
+           :widths: 50 200
+
+           * - /NoLayout
+             - Layout explicitly not specified
+           * - /SinglePage
+             - Show one page at a time
+           * - /OneColumn
+             - Show one column at a time
+           * - /TwoColumnLeft
+             - Show pages in two columns, odd-numbered pages on the left
+           * - /TwoColumnRight
+             - Show pages in two columns, odd-numbered pages on the right
+           * - /TwoPageLeft
+             - Show two pages at a time, odd-numbered pages on the left
+           * - /TwoPageRight
+             - Show two pages at a time, odd-numbered pages on the right
+        """
+        self._set_page_layout(layout)
+
+    def setPageLayout(self, layout: LayoutType) -> None:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :py:attr:`page_layout` instead.
+        """
+        deprecation_with_replacement(
+            "writer.setPageLayout(val)", "writer.page_layout = val", "3.0.0"
+        )
+        return self._set_page_layout(layout)
+
+    @property
+    def page_layout(self) -> Optional[LayoutType]:
+        """
+        Page layout property.
+
+        .. list-table:: Valid ``layout`` values
+           :widths: 50 200
+
+           * - /NoLayout
+             - Layout explicitly not specified
+           * - /SinglePage
+             - Show one page at a time
+           * - /OneColumn
+             - Show one column at a time
+           * - /TwoColumnLeft
+             - Show pages in two columns, odd-numbered pages on the left
+           * - /TwoColumnRight
+             - Show pages in two columns, odd-numbered pages on the right
+           * - /TwoPageLeft
+             - Show two pages at a time, odd-numbered pages on the left
+           * - /TwoPageRight
+             - Show two pages at a time, odd-numbered pages on the right
+        """
+        return self._get_page_layout()
+
+    @page_layout.setter
+    def page_layout(self, layout: LayoutType) -> None:
+        self._set_page_layout(layout)
+
+    @property
+    def pageLayout(self) -> Optional[LayoutType]:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :py:attr:`page_layout` instead.
+        """
+        deprecation_with_replacement("pageLayout", "page_layout", "3.0.0")
+        return self.page_layout
+
+    @pageLayout.setter
+    def pageLayout(self, layout: LayoutType) -> None:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :py:attr:`page_layout` instead.
+        """
+        deprecation_with_replacement("pageLayout", "page_layout", "3.0.0")
+        self.page_layout = layout
+
+    _valid_modes = (
+        "/UseNone",
+        "/UseOutlines",
+        "/UseThumbs",
+        "/FullScreen",
+        "/UseOC",
+        "/UseAttachments",
+    )
+
+    def _get_page_mode(self) -> Optional[PagemodeType]:
+        try:
+            return cast(PagemodeType, self._root_object["/PageMode"])
+        except KeyError:
+            return None
+
+    def getPageMode(self) -> Optional[PagemodeType]:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :py:attr:`page_mode` instead.
+        """
+        deprecation_with_replacement("getPageMode", "page_mode", "3.0.0")
+        return self._get_page_mode()
+
+    def set_page_mode(self, mode: PagemodeType) -> None:
+        """
+        .. deprecated:: 1.28.0
+
+            Use :py:attr:`page_mode` instead.
+        """
+        if isinstance(mode, NameObject):
+            mode_name: NameObject = mode
+        else:
+            if mode not in self._valid_modes:
+                logger_warning(
+                    f"Mode should be one of: {', '.join(self._valid_modes)}", __name__
+                )
+            mode_name = NameObject(mode)
+        self._root_object.update({NameObject("/PageMode"): mode_name})
+
+    def setPageMode(self, mode: PagemodeType) -> None:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :py:attr:`page_mode` instead.
+        """
+        deprecation_with_replacement(
+            "writer.setPageMode(val)", "writer.page_mode = val", "3.0.0"
+        )
+        self.set_page_mode(mode)
+
+    @property
+    def page_mode(self) -> Optional[PagemodeType]:
+        """
+        Page mode property.
+
+        .. list-table:: Valid ``mode`` values
+           :widths: 50 200
+
+           * - /UseNone
+             - Do not show outline or thumbnails panels
+           * - /UseOutlines
+             - Show outline (aka bookmarks) panel
+           * - /UseThumbs
+             - Show page thumbnails panel
+           * - /FullScreen
+             - Fullscreen view
+           * - /UseOC
+             - Show Optional Content Group (OCG) panel
+           * - /UseAttachments
+             - Show attachments panel
+        """
+        return self._get_page_mode()
+
+    @page_mode.setter
+    def page_mode(self, mode: PagemodeType) -> None:
+        self.set_page_mode(mode)
+
+    @property
+    def pageMode(self) -> Optional[PagemodeType]:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :py:attr:`page_mode` instead.
+        """
+        deprecation_with_replacement("pageMode", "page_mode", "3.0.0")
+        return self.page_mode
+
+    @pageMode.setter
+    def pageMode(self, mode: PagemodeType) -> None:  # pragma: no cover
+        """
+        .. deprecated:: 1.28.0
+
+            Use :py:attr:`page_mode` instead.
+        """
+        deprecation_with_replacement("pageMode", "page_mode", "3.0.0")
+        self.page_mode = mode
+
+    def add_annotation(self, page_number: int, annotation: Dict[str, Any]) -> None:
+        to_add = cast(DictionaryObject, _pdf_objectify(annotation))
+        to_add[NameObject("/P")] = self.get_object(self._pages)["/Kids"][page_number]  # type: ignore
+        page = self.pages[page_number]
+        if page.annotations is None:
+            page[NameObject("/Annots")] = ArrayObject()
+        assert page.annotations is not None
+
+        # Internal link annotations need the correct object type for the
+        # destination
+        if to_add.get("/Subtype") == "/Link" and NameObject("/Dest") in to_add:
+            tmp = cast(dict, to_add[NameObject("/Dest")])
+            dest = Destination(
+                NameObject("/LinkName"),
+                tmp["target_page_index"],
+                Fit(
+                    fit_type=tmp["fit"], fit_args=dict(tmp)["fit_args"]
+                ),  # I have no clue why this dict-hack is necessary
+            )
+            to_add[NameObject("/Dest")] = dest.dest_array
+
+        ind_obj = self._add_object(to_add)
+
+        page.annotations.append(ind_obj)
+
+    def clean_page(self, page: Union[PageObject, IndirectObject]) -> PageObject:
+        """
+        Perform some clean up in the page.
+        Currently: convert NameObject nameddestination to TextStringObject (required for names/dests list)
+        """
+        page = cast("PageObject", page.get_object())
+        for a in page.get("/Annots", []):
+            a_obj = a.get_object()
+            d = a_obj.get("/Dest", None)
+            act = a_obj.get("/A", None)
+            if isinstance(d, NameObject):
+                a_obj[NameObject("/Dest")] = TextStringObject(d)
+            elif act is not None:
+                act = act.get_object()
+                d = act.get("/D", None)
+                if isinstance(d, NameObject):
+                    act[NameObject("/D")] = TextStringObject(d)
+        return page
+
+    def _create_stream(
+        self, fileobj: Union[Path, StrByteType, PdfReader]
+    ) -> Tuple[IOBase, Optional[Encryption]]:
+        # If the fileobj parameter is a string, assume it is a path
+        # and create a file object at that location. If it is a file,
+        # copy the file's contents into a BytesIO stream object; if
+        # it is a PdfReader, copy that reader's stream into a
+        # BytesIO stream.
+        # If fileobj is none of the above types, it is not modified
+        encryption_obj = None
+        stream: IOBase
+        if isinstance(fileobj, (str, Path)):
+            with FileIO(fileobj, "rb") as f:
+                stream = BytesIO(f.read())
+        elif isinstance(fileobj, PdfReader):
+            if fileobj._encryption:
+                encryption_obj = fileobj._encryption
+            orig_tell = fileobj.stream.tell()
+            fileobj.stream.seek(0)
+            stream = BytesIO(fileobj.stream.read())
+
+            # reset the stream to its original location
+            fileobj.stream.seek(orig_tell)
+        elif hasattr(fileobj, "seek") and hasattr(fileobj, "read"):
+            fileobj.seek(0)
+            filecontent = fileobj.read()
+            stream = BytesIO(filecontent)
+        else:
+            raise NotImplementedError(
+                "PdfMerger.merge requires an object that PdfReader can parse. "
+                "Typically, that is a Path or a string representing a Path, "
+                "a file object, or an object implementing .seek and .read. "
+                "Passing a PdfReader directly works as well."
+            )
+        return stream, encryption_obj
+
+    def append(
+        self,
+        fileobj: Union[StrByteType, PdfReader, Path],
+        outline_item: Union[
+            str, None, PageRange, Tuple[int, int], Tuple[int, int, int], List[int]
+        ] = None,
+        pages: Union[
+            None, PageRange, Tuple[int, int], Tuple[int, int, int], List[int]
+        ] = None,
+        import_outline: bool = True,
+        excluded_fields: Optional[Union[List[str], Tuple[str, ...]]] = None,
+    ) -> None:
+        """
+        Identical to the :meth:`merge()<merge>` method, but assumes you want to
+        concatenate all pages onto the end of the file instead of specifying a
+        position.
+
+        :param fileobj: A File Object or an object that supports the standard
+            read and seek methods similar to a File Object. Could also be a
+            string representing a path to a PDF file.
+
+        :param str outline_item: Optionally, you may specify a string to build an outline
+            (aka 'bookmark') to identify the
+            beginning of the included file.
+
+        :param pages: can be a :class:`PageRange<PyPDF2.pagerange.PageRange>`
+            or a ``(start, stop[, step])`` tuple
+            or a list of pages to be processed
+            to merge only the specified range of pages from the source
+            document into the output document.
+
+        :param bool import_outline: You may prevent the source document's
+            outline (collection of outline items, previously referred to as
+            'bookmarks') from being imported by specifying this as ``False``.
+
+        :param List excluded_fields: provide the list of fields/keys to be ignored
+            if "/Annots" is part of the list, the annotation will be ignored
+            if "/B" is part of the list, the articles will be ignored
+        """
+        if excluded_fields is None:
+            excluded_fields = ()
+        if isinstance(outline_item, (tuple, list, PageRange)):
+            if isinstance(pages, bool):
+                if not isinstance(import_outline, bool):
+                    excluded_fields = import_outline
+                import_outline = pages
+            pages = outline_item
+            self.merge(None, fileobj, None, pages, import_outline, excluded_fields)
+        else:  # if isinstance(outline_item,str):
+            self.merge(
+                None, fileobj, outline_item, pages, import_outline, excluded_fields
+            )
+
+    @deprecation_bookmark(bookmark="outline_item", import_bookmarks="import_outline")
+    def merge(
+        self,
+        position: Optional[int],
+        fileobj: Union[Path, StrByteType, PdfReader],
+        outline_item: Optional[str] = None,
+        pages: Optional[PageRangeSpec] = None,
+        import_outline: bool = True,
+        excluded_fields: Optional[Union[List[str], Tuple[str, ...]]] = (),
+    ) -> 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
+            be inserted after the given number.
+
+        :param fileobj: A File Object or an object that supports the standard
+            read and seek methods similar to a File Object. Could also be a
+            string representing a path to a PDF file.
+
+        :param str outline_item: Optionally, you may specify a string to build an outline
+            (aka 'bookmark') to identify the
+            beginning of the included file.
+
+        :param pages: can be a :class:`PageRange<PyPDF2.pagerange.PageRange>`
+            or a ``(start, stop[, step])`` tuple
+            or a list of pages to be processed
+            to merge only the specified range of pages from the source
+            document into the output document.
+
+        :param bool import_outline: You may prevent the source document's
+            outline (collection of outline items, previously referred to as
+            'bookmarks') from being imported by specifying this as ``False``.
+
+        :param List excluded_fields: provide the list of fields/keys to be ignored
+            if "/Annots" is part of the list, the annotation will be ignored
+            if "/B" is part of the list, the articles will be ignored
+        """
+        if isinstance(fileobj, PdfReader):
+            reader = fileobj
+        else:
+            stream, encryption_obj = self._create_stream(fileobj)
+            # Create a new PdfReader instance using the stream
+            # (either file or BytesIO or StringIO) created above
+            reader = PdfReader(stream, strict=False)  # type: ignore[arg-type]
+
+        if excluded_fields is None:
+            excluded_fields = ()
+        # Find the range of pages to merge.
+        if pages is None:
+            pages = list(range(0, len(reader.pages)))
+        elif isinstance(pages, PageRange):
+            pages = list(range(*pages.indices(len(reader.pages))))
+        elif isinstance(pages, list):
+            pass  # keep unchanged
+        elif isinstance(pages, tuple) and len(pages) <= 3:
+            pages = list(range(*pages))
+        elif not isinstance(pages, tuple):
+            raise TypeError(
+                '"pages" must be a tuple of (start, stop[, step]) or a list'
+            )
+
+        srcpages = {}
+        for i in pages:
+            pg = reader.pages[i]
+            assert pg.indirect_reference is not None
+            if position is None:
+                srcpages[pg.indirect_reference.idnum] = self.add_page(
+                    pg, list(excluded_fields) + ["/B", "/Annots"]  # type: ignore
+                )
+            else:
+                srcpages[pg.indirect_reference.idnum] = self.insert_page(
+                    pg, position, list(excluded_fields) + ["/B", "/Annots"]  # type: ignore
+                )
+                position += 1
+            srcpages[pg.indirect_reference.idnum].original_page = pg
+
+        reader._namedDests = (
+            reader.named_destinations
+        )  # need for the outline processing below
+        for dest in reader._namedDests.values():
+            arr = dest.dest_array
+            # try:
+            if isinstance(dest["/Page"], NullObject):
+                pass  # self.add_named_destination_array(dest["/Title"],arr)
+            elif dest["/Page"].indirect_reference.idnum in srcpages:
+                arr[NumberObject(0)] = srcpages[
+                    dest["/Page"].indirect_reference.idnum
+                ].indirect_reference
+                self.add_named_destination_array(dest["/Title"], arr)
+            # except Exception as e:
+            #    logger_warning(f"can not insert {dest} : {e.msg}",__name__)
+
+        outline_item_typ: TreeObject
+        if outline_item is not None:
+            outline_item_typ = cast(
+                "TreeObject",
+                self.add_outline_item(
+                    TextStringObject(outline_item),
+                    list(srcpages.values())[0].indirect_reference,
+                    fit=PAGE_FIT,
+                ).get_object(),
+            )
+        else:
+            outline_item_typ = self.get_outline_root()
+
+        _ro = cast("DictionaryObject", reader.trailer[TK.ROOT])
+        if import_outline and CO.OUTLINES in _ro:
+            outline = self._get_filtered_outline(
+                _ro.get(CO.OUTLINES, None), srcpages, reader
+            )
+            self._insert_filtered_outline(
+                outline, outline_item_typ, None
+            )  # TODO : use before parameter
+
+        if "/Annots" not in excluded_fields:
+            for pag in srcpages.values():
+                lst = self._insert_filtered_annotations(
+                    pag.original_page.get("/Annots", ()), pag, srcpages, reader
+                )
+                if len(lst) > 0:
+                    pag[NameObject("/Annots")] = lst
+                self.clean_page(pag)
+
+        if "/B" not in excluded_fields:
+            self.add_filtered_articles("", srcpages, reader)
+
+        return
+
+    def _add_articles_thread(
+        self,
+        thread: DictionaryObject,  # thread entry from the reader's array of threads
+        pages: Dict[int, PageObject],
+        reader: PdfReader,
+    ) -> IndirectObject:
+        """
+        clone the thread with only the applicable articles
+
+        """
+        nthread = thread.clone(
+            self, force_duplicate=True, ignore_fields=("/F",)
+        )  # use of clone to keep link between reader and writer
+        self.threads.append(nthread.indirect_reference)
+        first_article = cast("DictionaryObject", thread["/F"])
+        current_article: Optional[DictionaryObject] = first_article
+        new_article: Optional[DictionaryObject] = None
+        while current_article is not None:
+            pag = self._get_cloned_page(
+                cast("PageObject", current_article["/P"]), pages, reader
+            )
+            if pag is not None:
+                if new_article is None:
+                    new_article = cast(
+                        "DictionaryObject",
+                        self._add_object(DictionaryObject()).get_object(),
+                    )
+                    new_first = new_article
+                    nthread[NameObject("/F")] = new_article.indirect_reference
+                else:
+                    new_article2 = cast(
+                        "DictionaryObject",
+                        self._add_object(
+                            DictionaryObject(
+                                {NameObject("/V"): new_article.indirect_reference}
+                            )
+                        ).get_object(),
+                    )
+                    new_article[NameObject("/N")] = new_article2.indirect_reference
+                    new_article = new_article2
+                new_article[NameObject("/P")] = pag
+                new_article[NameObject("/T")] = nthread.indirect_reference
+                new_article[NameObject("/R")] = current_article["/R"]
+                pag_obj = cast("PageObject", pag.get_object())
+                if "/B" not in pag_obj:
+                    pag_obj[NameObject("/B")] = ArrayObject()
+                cast("ArrayObject", pag_obj["/B"]).append(
+                    new_article.indirect_reference
+                )
+            current_article = cast("DictionaryObject", current_article["/N"])
+            if current_article == first_article:
+                new_article[NameObject("/N")] = new_first.indirect_reference  # type: ignore
+                new_first[NameObject("/V")] = new_article.indirect_reference  # type: ignore
+                current_article = None
+        assert nthread.indirect_reference is not None
+        return nthread.indirect_reference
+
+    def add_filtered_articles(
+        self,
+        fltr: Union[Pattern, str],  # thread entry from the reader's array of threads
+        pages: Dict[int, PageObject],
+        reader: PdfReader,
+    ) -> None:
+        """
+        Add articles matching the defined criteria
+        """
+        if isinstance(fltr, str):
+            fltr = re.compile(fltr)
+        elif not isinstance(fltr, Pattern):
+            fltr = re.compile("")
+        for p in pages.values():
+            pp = p.original_page
+            for a in pp.get("/B", ()):
+                thr = a.get_object()["/T"]
+                if thr.indirect_reference.idnum not in self._id_translated[
+                    id(reader)
+                ] and fltr.search(thr["/I"]["/Title"]):
+                    self._add_articles_thread(thr, pages, reader)
+
+    def _get_cloned_page(
+        self,
+        page: Union[None, int, IndirectObject, PageObject, NullObject],
+        pages: Dict[int, PageObject],
+        reader: PdfReader,
+    ) -> Optional[IndirectObject]:
+        if isinstance(page, NullObject):
+            return None
+        if isinstance(page, int):
+            _i = reader.pages[page].indirect_reference
+        # elif isinstance(page, PageObject):
+        #    _i = page.indirect_reference
+        elif isinstance(page, DictionaryObject) and page.get("/Type", "") == "/Page":
+            _i = page.indirect_reference
+        elif isinstance(page, IndirectObject):
+            _i = page
+        try:
+            return pages[_i.idnum].indirect_reference  # type: ignore
+        except Exception:
+            return None
+
+    def _insert_filtered_annotations(
+        self,
+        annots: Union[IndirectObject, List[DictionaryObject]],
+        page: PageObject,
+        pages: Dict[int, PageObject],
+        reader: PdfReader,
+    ) -> List[Destination]:
+        outlist = ArrayObject()
+        if isinstance(annots, IndirectObject):
+            annots = cast("List", annots.get_object())
+        for an in annots:
+            ano = cast("DictionaryObject", an.get_object())
+            if (
+                ano["/Subtype"] != "/Link"
+                or "/A" not in ano
+                or cast("DictionaryObject", ano["/A"])["/S"] != "/GoTo"
+                or "/Dest" in ano
+            ):
+                if "/Dest" not in ano:
+                    outlist.append(ano.clone(self).indirect_reference)
+                else:
+                    d = ano["/Dest"]
+                    if isinstance(d, str):
+                        # it is a named dest
+                        if str(d) in self.get_named_dest_root():
+                            outlist.append(ano.clone(self).indirect_reference)
+                    else:
+                        d = cast("ArrayObject", d)
+                        p = self._get_cloned_page(d[0], pages, reader)
+                        if p is not None:
+                            anc = ano.clone(self, ignore_fields=("/Dest",))
+                            anc[NameObject("/Dest")] = ArrayObject([p] + d[1:])
+                            outlist.append(anc.indirect_reference)
+            else:
+                d = cast("DictionaryObject", ano["/A"])["/D"]
+                if isinstance(d, str):
+                    # it is a named dest
+                    if str(d) in self.get_named_dest_root():
+                        outlist.append(ano.clone(self).indirect_reference)
+                else:
+                    d = cast("ArrayObject", d)
+                    p = self._get_cloned_page(d[0], pages, reader)
+                    if p is not None:
+                        anc = ano.clone(self, ignore_fields=("/D",))
+                        anc = cast("DictionaryObject", anc)
+                        cast("DictionaryObject", anc["/A"])[
+                            NameObject("/D")
+                        ] = ArrayObject([p] + d[1:])
+                        outlist.append(anc.indirect_reference)
+        return outlist
+
+    def _get_filtered_outline(
+        self,
+        node: Any,
+        pages: Dict[int, PageObject],
+        reader: PdfReader,
+    ) -> List[Destination]:
+        """Extract outline item entries that are part of the specified page set."""
+        new_outline = []
+        node = node.get_object()
+        if node.get("/Type", "") == "/Outlines" or "/Title" not in node:
+            node = node.get("/First", None)
+            if node is not None:
+                node = node.get_object()
+                new_outline += self._get_filtered_outline(node, pages, reader)
+        else:
+            v: Union[None, IndirectObject, NullObject]
+            while node is not None:
+                node = node.get_object()
+                o = cast("Destination", reader._build_outline_item(node))
+                v = self._get_cloned_page(cast("PageObject", o["/Page"]), pages, reader)
+                if v is None:
+                    v = NullObject()
+                o[NameObject("/Page")] = v
+                if "/First" in node:
+                    o.childs = self._get_filtered_outline(node["/First"], pages, reader)
+                else:
+                    o.childs = []
+                if not isinstance(o["/Page"], NullObject) or len(o.childs) > 0:
+                    new_outline.append(o)
+                node = node.get("/Next", None)
+        return new_outline
+
+    def _clone_outline(self, dest: Destination) -> TreeObject:
+        n_ol = TreeObject()
+        self._add_object(n_ol)
+        n_ol[NameObject("/Title")] = TextStringObject(dest["/Title"])
+        if not isinstance(dest["/Page"], NullObject):
+            if dest.node is not None and "/A" in dest.node:
+                n_ol[NameObject("/A")] = dest.node["/A"].clone(self)
+            # elif "/D" in dest.node:
+            #    n_ol[NameObject("/Dest")] = dest.node["/D"].clone(self)
+            # elif "/Dest" in dest.node:
+            #    n_ol[NameObject("/Dest")] = dest.node["/Dest"].clone(self)
+            else:
+                n_ol[NameObject("/Dest")] = dest.dest_array
+        # TODO: /SE
+        if dest.node is not None:
+            n_ol[NameObject("/F")] = NumberObject(dest.node.get("/F", 0))
+            n_ol[NameObject("/C")] = ArrayObject(
+                dest.node.get(
+                    "/C", [FloatObject(0.0), FloatObject(0.0), FloatObject(0.0)]
+                )
+            )
+        return n_ol
+
+    def _insert_filtered_outline(
+        self,
+        outlines: List[Destination],
+        parent: Union[TreeObject, IndirectObject],
+        before: Union[None, TreeObject, IndirectObject] = None,
+    ) -> None:
+        for dest in outlines:
+            # TODO  : can be improved to keep A and SE entries (ignored for the moment)
+            # np=self.add_outline_item_destination(dest,parent,before)
+            if dest.get("/Type", "") == "/Outlines" or "/Title" not in dest:
+                np = parent
+            else:
+                np = self._clone_outline(dest)
+                cast(TreeObject, parent.get_object()).insert_child(np, before, self)
+            self._insert_filtered_outline(dest.childs, np, None)
+
+    def close(self) -> None:
+        """To match the functions from Merger"""
+        return
+
+    # @deprecation_bookmark(bookmark="outline_item")
+    def find_outline_item(
+        self,
+        outline_item: Dict[str, Any],
+        root: Optional[OutlineType] = None,
+    ) -> Optional[List[int]]:
+        if root is None:
+            o = self.get_outline_root()
+        else:
+            o = cast("TreeObject", root)
+
+        i = 0
+        while o is not None:
+            if (
+                o.indirect_reference == outline_item
+                or o.get("/Title", None) == outline_item
+            ):
+                return [i]
+            else:
+                if "/First" in o:
+                    res = self.find_outline_item(
+                        outline_item, cast(OutlineType, o["/First"])
+                    )
+                    if res:
+                        return ([i] if "/Title" in o else []) + res
+            if "/Next" in o:
+                i += 1
+                o = cast(TreeObject, o["/Next"])
+            else:
+                return None
+
+    @deprecation_bookmark(bookmark="outline_item")
+    def find_bookmark(
+        self,
+        outline_item: Dict[str, Any],
+        root: Optional[OutlineType] = None,
+    ) -> Optional[List[int]]:  # pragma: no cover
+        """
+        .. deprecated:: 2.9.0
+            Use :meth:`find_outline_item` instead.
+        """
+        return self.find_outline_item(outline_item, root)
+
+    def reset_translation(
+        self, reader: Union[None, PdfReader, IndirectObject] = None
+    ) -> None:
+        """
+        reset the translation table between reader and the writer object.
+        late cloning will create new independent objects
+
+        :param reader: PdfReader or IndirectObject refering a PdfReader object.
+                       if set to None or omitted, all tables will be reset.
+        """
+        if reader is None:
+            self._id_translated = {}
+        elif isinstance(reader, PdfReader):
+            try:
+                del self._id_translated[id(reader)]
+            except Exception:
+                pass
+        elif isinstance(reader, IndirectObject):
+            try:
+                del self._id_translated[id(reader.pdf)]
+            except Exception:
+                pass
+        else:
+            raise Exception("invalid parameter {reader}")
+
+
+def _pdf_objectify(obj: Union[Dict[str, Any], str, int, List[Any]]) -> PdfObject:
+    if isinstance(obj, PdfObject):
+        return obj
+    if isinstance(obj, dict):
+        to_add = DictionaryObject()
+        for key, value in obj.items():
+            name_key = NameObject(key)
+            casted_value = _pdf_objectify(value)
+            to_add[name_key] = casted_value
+        return to_add
+    elif isinstance(obj, list):
+        arr = ArrayObject()
+        for el in obj:
+            arr.append(_pdf_objectify(el))
+        return arr
+    elif isinstance(obj, str):
+        if obj.startswith("/"):
+            return NameObject(obj)
+        else:
+            return TextStringObject(obj)
+    elif isinstance(obj, (int, float)):
+        return FloatObject(obj)
+    else:
+        raise NotImplementedError(
+            f"type(obj)={type(obj)} could not be casted to PdfObject"
+        )
+
+
+def _create_outline_item(
+    action_ref: Union[None, IndirectObject],
+    title: str,
+    color: Union[Tuple[float, float, float], str, None],
+    italic: bool,
+    bold: bool,
+) -> TreeObject:
+    outline_item = TreeObject()
+    if action_ref is not None:
+        outline_item[NameObject("/A")] = action_ref
+    outline_item.update(
+        {
+            NameObject("/Title"): create_string_object(title),
+        }
+    )
+    if color:
+        if isinstance(color, str):
+            color = hex_to_rgb(color)
+        prec = decimal.Decimal("1.00000")
+        outline_item.update(
+            {
+                NameObject("/C"): ArrayObject(
+                    [FloatObject(decimal.Decimal(c).quantize(prec)) for c in color]
+                )
+            }
+        )
+    if italic or bold:
+        format_flag = 0
+        if italic:
+            format_flag += 1
+        if bold:
+            format_flag += 2
+        outline_item.update({NameObject("/F"): NumberObject(format_flag)})
+    return outline_item
+
+
+class PdfFileWriter(PdfWriter):  # pragma: no cover
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        deprecation_with_replacement("PdfFileWriter", "PdfWriter", "3.0.0")
+        super().__init__(*args, **kwargs)