The PdfWriter Class

class PyPDF2.PdfWriter(fileobj: Union[str, _io.BytesIO, _io.BufferedReader, _io.BufferedWriter, _io.FileIO] = '')[source]

Bases: object

This class supports writing PDF files out, given pages produced by another class (typically PdfReader).

addAttachment(fname: str, fdata: Union[str, bytes]) None[source]

Deprecated since version 1.28.0: Use add_attachment() instead.

addBlankPage(width: Optional[float] = None, height: Optional[float] = None) PyPDF2._page.PageObject[source]

Deprecated since version 1.28.0: Use add_blank_page() instead.

addBookmark(title: str, pagenum: int, parent: typing.Union[None, PyPDF2.generic._data_structures.TreeObject, PyPDF2.generic._base.IndirectObject] = None, color: typing.Optional[typing.Tuple[float, float, float]] = None, bold: bool = False, italic: bool = False, fit: typing_extensions.Literal[/Fit, /XYZ, /FitH, /FitV, /FitR, /FitB, /FitBH, /FitBV] = '/Fit', *args: typing.Union[PyPDF2.generic._base.NumberObject, PyPDF2.generic._base.NullObject, float]) PyPDF2.generic._base.IndirectObject[source]

Deprecated since version 1.28.0: Use add_outline_item() instead.

addBookmarkDestination(dest: PyPDF2._page.PageObject, parent: Optional[PyPDF2.generic._data_structures.TreeObject] = None) PyPDF2.generic._base.IndirectObject[source]

Deprecated since version 1.28.0: Use add_outline_item_destination() instead.

addBookmarkDict(outline_item: Union[PyPDF2.generic._outline.OutlineItem, PyPDF2.generic._data_structures.Destination], parent: Optional[PyPDF2.generic._data_structures.TreeObject] = None) PyPDF2.generic._base.IndirectObject[source]

Deprecated since version 1.28.0: Use add_outline_item_dict() instead.

addJS(javascript: str) None[source]

Deprecated since version 1.28.0: Use add_js() instead.

Deprecated since version 1.28.0: Use add_link() instead.

addMetadata(infos: Dict[str, Any]) None[source]

Deprecated since version 1.28.0: Use add_metadata() instead.

addNamedDestination(title: str, pagenum: int) PyPDF2.generic._base.IndirectObject[source]

Deprecated since version 1.28.0: Use add_named_destination() instead.

addNamedDestinationObject(dest: PyPDF2.generic._base.PdfObject) PyPDF2.generic._base.IndirectObject[source]

Deprecated since version 1.28.0: Use add_named_destination_object() instead.

addPage(page: PyPDF2._page.PageObject) None[source]

Deprecated since version 1.28.0: Use add_page() instead.

addURI(pagenum: int, uri: str, rect: PyPDF2.generic._rectangle.RectangleObject, border: Optional[PyPDF2.generic._data_structures.ArrayObject] = None) None[source]

Deprecated since version 1.28.0: Use add_uri() instead.

add_annotation(page_number: int, annotation: Dict[str, Any]) None[source]
add_attachment(filename: str, data: Union[str, bytes]) None[source]

Embed a file inside the PDF.

Parameters
  • filename (str) – The filename to display.

  • data (str) – The data in the file.

Reference: https://www.adobe.com/content/dam/Adobe/en/devnet/acrobat/pdfs/PDF32000_2008.pdf Section 7.11.3

add_blank_page(width: Optional[float] = None, height: Optional[float] = None) PyPDF2._page.PageObject[source]

Append a blank page to this PDF file and returns it. If no page size is specified, use the size of the last page.

Parameters
  • width (float) – The width of the new page expressed in default user space units.

  • height (float) – The height of the new page expressed in default user space units.

Returns

the newly appended page

Raises

PageSizeNotDefinedError – if width and height are not defined and previous page does not exist.

add_bookmark(title: str, pagenum: int, parent: typing.Union[None, PyPDF2.generic._data_structures.TreeObject, PyPDF2.generic._base.IndirectObject] = None, color: typing.Optional[typing.Tuple[float, float, float]] = None, bold: bool = False, italic: bool = False, fit: typing_extensions.Literal[/Fit, /XYZ, /FitH, /FitV, /FitR, /FitB, /FitBH, /FitBV] = '/Fit', *args: typing.Union[PyPDF2.generic._base.NumberObject, PyPDF2.generic._base.NullObject, float]) PyPDF2.generic._base.IndirectObject[source]

Deprecated since version 2.9.0: Use add_outline_item() instead.

add_bookmark_destination(dest: Union[PyPDF2._page.PageObject, PyPDF2.generic._data_structures.TreeObject], parent: Union[None, PyPDF2.generic._data_structures.TreeObject, PyPDF2.generic._base.IndirectObject] = None) PyPDF2.generic._base.IndirectObject[source]

Deprecated since version 2.9.0: Use add_outline_item_destination() instead.

add_bookmark_dict(outline_item: Union[PyPDF2.generic._outline.OutlineItem, PyPDF2.generic._data_structures.Destination], parent: Optional[PyPDF2.generic._data_structures.TreeObject] = None) PyPDF2.generic._base.IndirectObject[source]

Deprecated since version 2.9.0: Use add_outline_item_dict() instead.

add_js(javascript: str) None[source]

Add Javascript which will launch upon opening this PDF.

Parameters

javascript (str) – 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.
add_metadata(infos: Dict[str, Any]) None[source]

Add custom metadata to the output.

Parameters

infos (dict) – a Python dictionary where each key is a field and each value is your new metadata.

add_named_destination(title: str, pagenum: int) PyPDF2.generic._base.IndirectObject[source]
add_named_destination_object(dest: PyPDF2.generic._base.PdfObject) PyPDF2.generic._base.IndirectObject[source]
add_outline() None[source]
add_outline_item(title: str, pagenum: int, parent: typing.Union[None, PyPDF2.generic._data_structures.TreeObject, PyPDF2.generic._base.IndirectObject] = None, color: typing.Optional[typing.Union[typing.Tuple[float, float, float], str]] = None, bold: bool = False, italic: bool = False, fit: typing_extensions.Literal[/Fit, /XYZ, /FitH, /FitV, /FitR, /FitB, /FitBH, /FitBV] = '/Fit', *args: typing.Union[PyPDF2.generic._base.NumberObject, PyPDF2.generic._base.NullObject, float]) PyPDF2.generic._base.IndirectObject[source]

Add an outline item (commonly referred to as a “Bookmark”) to this PDF file.

Parameters
  • title (str) – Title to use for this outline item.

  • pagenum (int) – Page number this outline item will point to.

  • parent – A reference to a parent outline item to create nested outline items.

  • color (tuple) – 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)

  • bold (bool) – Outline item font is bold

  • italic (bool) – Outline item font is italic

  • fit (str) – The fit of the destination page. See add_link() for details.

add_outline_item_destination(dest: Union[PyPDF2._page.PageObject, PyPDF2.generic._data_structures.TreeObject], parent: Union[None, PyPDF2.generic._data_structures.TreeObject, PyPDF2.generic._base.IndirectObject] = None) PyPDF2.generic._base.IndirectObject[source]
add_outline_item_dict(outline_item: Union[PyPDF2.generic._outline.OutlineItem, PyPDF2.generic._data_structures.Destination], parent: Optional[PyPDF2.generic._data_structures.TreeObject] = None) PyPDF2.generic._base.IndirectObject[source]
add_page(page: PyPDF2._page.PageObject) None[source]

Add a page to this PDF file.

The page is usually acquired from a PdfReader instance.

Parameters

page (PageObject) – The page to add to the document. Should be an instance of PageObject

add_uri(pagenum: int, uri: str, rect: PyPDF2.generic._rectangle.RectangleObject, border: Optional[PyPDF2.generic._data_structures.ArrayObject] = None) None[source]

Add an URI from a rectangular area to the specified page. This uses the basic structure of add_link()

Parameters
  • pagenum (int) – index of the page on which to place the URI action.

  • uri (str) – URI of resource to link to.

  • rect (Tuple[int, int, int, int]) – RectangleObject or array of four integers specifying the clickable rectangular area [xLL, yLL, xUR, yUR], or string in the form "[ xLL yLL xUR yUR ]".

  • border (ArrayObject) – if provided, an array describing border-drawing properties. See the PDF spec for details. No border will be drawn if this argument is omitted.

appendPagesFromReader(reader: PyPDF2._reader.PdfReader, after_page_append: Optional[Callable[[PyPDF2._page.PageObject], None]] = None) None[source]

Deprecated since version 1.28.0: Use append_pages_from_reader() instead.

append_pages_from_reader(reader: PyPDF2._reader.PdfReader, after_page_append: Optional[Callable[[PyPDF2._page.PageObject], None]] = None) None[source]

Copy pages from reader to writer. Includes an optional callback parameter which is invoked after pages are appended to the writer.

Parameters
  • reader (PdfReader) – a PdfReader object from which to copy page annotations to this writer object. The writer’s annots will then be updated

  • after_page_append (Callable[[PageObject], None]) – 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.

cloneDocumentFromReader(reader: PyPDF2._reader.PdfReader, after_page_append: Optional[Callable[[PyPDF2._page.PageObject], None]] = None) None[source]

Deprecated since version 1.28.0: Use clone_document_from_reader() instead.

cloneReaderDocumentRoot(reader: PyPDF2._reader.PdfReader) None[source]

Deprecated since version 1.28.0: Use clone_reader_document_root() instead.

clone_document_from_reader(reader: PyPDF2._reader.PdfReader, after_page_append: Optional[Callable[[PyPDF2._page.PageObject], None]] = None) None[source]

Create a copy (clone) of a document from a PDF file reader

Parameters
  • reader – PDF file reader instance from which the clone should be created.

  • after_page_append (Callable[[PageObject], None]) – 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.

clone_reader_document_root(reader: PyPDF2._reader.PdfReader) None[source]

Copy the reader document root to the writer.

Parameters

reader – PdfReader from the document root should be copied.

encrypt(user_pwd: str, owner_pwd: typing.Optional[str] = None, use_128bit: bool = True, permissions_flag: PyPDF2.constants.UserAccessPermissions = UserAccessPermissions.None) None[source]

Encrypt this PDF file with the PDF Standard encryption handler.

Parameters
  • user_pwd (str) – The “user password”, which allows for opening and reading the PDF file with the restrictions provided.

  • owner_pwd (str) – 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.

  • use_128bit (bool) – flag as to whether to use 128bit encryption. When false, 40bit encryption will be used. By default, this flag is on.

  • permissions_flag (unsigned int) – 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.

getNamedDestRoot() PyPDF2.generic._data_structures.ArrayObject[source]

Deprecated since version 1.28.0: Use get_named_dest_root() instead.

getNumPages() int[source]

Deprecated since version 1.28.0: Use len(writer.pages) instead.

getObject(ido: PyPDF2.generic._base.IndirectObject) PyPDF2.generic._base.PdfObject[source]

Deprecated since version 1.28.0: Use get_object() instead.

getOutlineRoot() PyPDF2.generic._data_structures.TreeObject[source]

Deprecated since version 1.28.0: Use get_outline_root() instead.

getPage(pageNumber: int) PyPDF2._page.PageObject[source]

Deprecated since version 1.28.0: Use writer.pages[page_number] instead.

getPageLayout() Optional[typing_extensions.Literal[/NoLayout, /SinglePage, /OneColumn, /TwoColumnLeft, /TwoColumnRight, /TwoPageLeft, /TwoPageRight]][source]

Deprecated since version 1.28.0: Use page_layout instead.

getPageMode() Optional[typing_extensions.Literal[/UseNone, /UseOutlines, /UseThumbs, /FullScreen, /UseOC, /UseAttachments]][source]

Deprecated since version 1.28.0: Use page_mode instead.

getReference(obj: PyPDF2.generic._base.PdfObject) PyPDF2.generic._base.IndirectObject[source]

Deprecated since version 1.28.0: Use get_reference() instead.

get_named_dest_root() PyPDF2.generic._data_structures.ArrayObject[source]
get_object(ido: PyPDF2.generic._base.IndirectObject) PyPDF2.generic._base.PdfObject[source]
get_outline_root() PyPDF2.generic._data_structures.TreeObject[source]
get_page(page_number: Optional[int] = None, pageNumber: Optional[int] = None) PyPDF2._page.PageObject[source]

Retrieve a page by number from this PDF file.

Parameters

page_number (int) – The page number to retrieve (pages begin at zero)

Returns

the page at the index given by page_number

get_reference(obj: PyPDF2.generic._base.PdfObject) PyPDF2.generic._base.IndirectObject[source]
insertBlankPage(width: Optional[decimal.Decimal] = None, height: Optional[decimal.Decimal] = None, index: int = 0) PyPDF2._page.PageObject[source]

Deprecated since version 1.28.0: Use insertBlankPage() instead.

insertPage(page: PyPDF2._page.PageObject, index: int = 0) None[source]

Deprecated since version 1.28.0: Use insert_page() instead.

insert_blank_page(width: Optional[decimal.Decimal] = None, height: Optional[decimal.Decimal] = None, index: int = 0) PyPDF2._page.PageObject[source]

Insert a blank page to this PDF file and returns it. If no page size is specified, use the size of the last page.

Parameters
  • width (float) – The width of the new page expressed in default user space units.

  • height (float) – The height of the new page expressed in default user space units.

  • index (int) – Position to add the page.

Returns

the newly appended page

Raises

PageSizeNotDefinedError – if width and height are not defined and previous page does not exist.

insert_page(page: PyPDF2._page.PageObject, index: int = 0) None[source]

Insert a page in this PDF file. The page is usually acquired from a PdfReader instance.

Parameters
  • page (PageObject) – The page to add to the document.

  • index (int) – Position at which the page will be inserted.

property pageLayout: Optional[typing_extensions.Literal[/NoLayout, /SinglePage, /OneColumn, /TwoColumnLeft, /TwoColumnRight, /TwoPageLeft, /TwoPageRight]]

Deprecated since version 1.28.0.

Use page_layout instead.

property pageMode: Optional[typing_extensions.Literal[/UseNone, /UseOutlines, /UseThumbs, /FullScreen, /UseOC, /UseAttachments]]

Deprecated since version 1.28.0.

Use page_mode instead.

property page_layout: Optional[typing_extensions.Literal[/NoLayout, /SinglePage, /OneColumn, /TwoColumnLeft, /TwoColumnRight, /TwoPageLeft, /TwoPageRight]]

Page layout property.

Valid layout values

/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

property page_mode: Optional[typing_extensions.Literal[/UseNone, /UseOutlines, /UseThumbs, /FullScreen, /UseOC, /UseAttachments]]

Page mode property.

Valid mode values

/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

property pages: List[PyPDF2._page.PageObject]

Property that emulates a list of PageObject.

property pdf_header: 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.

removeImages(ignoreByteStringObject: bool = False) None[source]

Deprecated since version 1.28.0: Use remove_images() instead.

Deprecated since version 1.28.0: Use remove_links() instead.

removeText(ignoreByteStringObject: bool = False) None[source]

Deprecated since version 1.28.0: Use remove_text() instead.

remove_images(ignore_byte_string_object: bool = False) None[source]

Remove images from this output.

Parameters

ignore_byte_string_object (bool) – optional parameter to ignore ByteString Objects.

Remove links and annotations from this output.

remove_text(ignore_byte_string_object: bool = False) None[source]

Remove text from this output.

Parameters

ignore_byte_string_object (bool) – optional parameter to ignore ByteString Objects.

setPageLayout(layout: typing_extensions.Literal[/NoLayout, /SinglePage, /OneColumn, /TwoColumnLeft, /TwoColumnRight, /TwoPageLeft, /TwoPageRight]) None[source]

Deprecated since version 1.28.0: Use page_layout instead.

setPageMode(mode: typing_extensions.Literal[/UseNone, /UseOutlines, /UseThumbs, /FullScreen, /UseOC, /UseAttachments]) None[source]

Deprecated since version 1.28.0: Use page_mode instead.

set_need_appearances_writer() None[source]
set_page_mode(mode: typing_extensions.Literal[/UseNone, /UseOutlines, /UseThumbs, /FullScreen, /UseOC, /UseAttachments]) None[source]

Deprecated since version 1.28.0: Use page_mode instead.

updatePageFormFieldValues(page: PyPDF2._page.PageObject, fields: typing.Dict[str, typing.Any], flags: PyPDF2.constants.FieldFlag = FieldFlag.None) None[source]

Deprecated since version 1.28.0: Use update_page_form_field_values() instead.

update_page_form_field_values(page: PyPDF2._page.PageObject, fields: typing.Dict[str, typing.Any], flags: PyPDF2.constants.FieldFlag = FieldFlag.None) None[source]

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.

Parameters
  • page (PageObject) – Page reference from PDF writer where the annotations and field data will be updated.

  • fields (dict) – a Python dictionary of field names (/T) and text values (/V)

  • flags (int) – 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.

write(stream: Union[pathlib.Path, str, _io.BytesIO, _io.BufferedReader, _io.BufferedWriter, _io.FileIO]) Tuple[bool, Union[_io.FileIO, _io.BytesIO, _io.BufferedReader, _io.BufferedWriter]][source]

Write the collection of pages added to this object out as a PDF file.

Parameters

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.

write_stream(stream: Union[_io.BytesIO, _io.BufferedReader, _io.BufferedWriter, _io.FileIO]) None[source]