The PdfWriter Class

class PyPDF2.PdfWriter(fileobj: Union[str, IO] = '')[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) → 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]) → IndirectObject[source]: Deprecated since version 1.28.0: Use add_outline_item() instead.

addBookmarkDestination(dest: PageObject, parent: Optional[TreeObject] = None) → IndirectObject[source]: Deprecated since version 1.28.0: Use add_outline_item_destination() instead.

addBookmarkDict(outline_item: Union[OutlineItem, Destination], parent: Optional[TreeObject] = None) → 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.

addLink(pagenum: int, page_destination: int, rect: ~PyPDF2.generic._rectangle.RectangleObject, border: ~typing.Optional[~PyPDF2.generic._data_structures.ArrayObject] = None, 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]) → None[source]: 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) → IndirectObject[source]: Deprecated since version 1.28.0: Use add_named_destination() instead.

addNamedDestinationObject(dest: Destination) → IndirectObject[source]: Deprecated since version 1.28.0: Use add_named_destination_object() instead.

addPage(page: PageObject, excluded_keys: Iterable[str] = ()) → PageObject[source]: Deprecated since version 1.28.0: Use add_page() instead.

addURI(pagenum: int, uri: str, rect: RectangleObject, border: Optional[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) → 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]) → IndirectObject[source]: Deprecated since version 2.9.0: Use add_outline_item() instead.

add_bookmark_destination(dest: Union[PageObject, TreeObject], parent: Union[None, TreeObject, IndirectObject] = None) → IndirectObject[source]: Deprecated since version 2.9.0: Use add_outline_item_destination() instead.

add_bookmark_dict(outline_item: Union[OutlineItem, Destination], parent: Optional[TreeObject] = None) → IndirectObject[source]: Deprecated since version 2.9.0: Use add_outline_item_dict() instead.

add_filtered_articles(fltr: Union[Pattern, str], pages: Dict[int, PageObject], reader: PdfReader) → None[source]: Add articles matching the defined criteria

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_link(pagenum: int, page_destination: int, rect: ~PyPDF2.generic._rectangle.RectangleObject, border: ~typing.Optional[~PyPDF2.generic._data_structures.ArrayObject] = None, 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]) → None[source]

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, page_number: Optional[int] = None, pagenum: Optional[int] = None) → IndirectObject[source]

add_named_destination_array(title: TextStringObject, destination: Union[IndirectObject, ArrayObject]) → None[source]

add_named_destination_object(page_destination: Optional[PdfObject] = None, dest: Optional[PdfObject] = None) → IndirectObject[source]

add_outline() → None[source]

add_outline_item(title: str, page_number: ~typing.Union[None, ~PyPDF2._page.PageObject, ~PyPDF2.generic._base.IndirectObject, int], parent: ~typing.Union[None, ~PyPDF2.generic._data_structures.TreeObject, ~PyPDF2.generic._base.IndirectObject] = None, before: ~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: ~PyPDF2.generic._fit.Fit = <PyPDF2.generic._fit.Fit object>, pagenum: ~typing.Optional[int] = None) → 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.
page_number (int) – Page number this outline item will point to.
parent – A reference to a parent outline item to create nested outline items.
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 (Fit) – The fit of the destination page.

add_outline_item_destination(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) → IndirectObject[source]

add_outline_item_dict(outline_item: Union[OutlineItem, Destination], parent: Union[None, TreeObject, IndirectObject] = None, before: Union[None, TreeObject, IndirectObject] = None) → IndirectObject[source]

add_page(page: PageObject, excluded_keys: Iterable[str] = ()) → PageObject[source]

Add a page to this PDF file. Recommended for advanced usage including the adequate excluded_keys

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(page_number: int, uri: str, rect: RectangleObject, border: Optional[ArrayObject] = None, pagenum: Optional[int] = None) → None[source]

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

Parameters

page_number (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.

append(fileobj: Union[str, IO, 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[source]

Identical to the merge() method, but assumes you want to concatenate all pages onto the end of the file instead of specifying a position.

Parameters

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.
outline_item (str) – Optionally, you may specify a string to build an outline (aka ‘bookmark’) to identify the beginning of the included file.
pages – can be a 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.
import_outline (bool) – 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.
excluded_fields (List) – 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

appendPagesFromReader(reader: PdfReader, after_page_append: Optional[Callable[[PageObject], None]] = None) → None[source]: Deprecated since version 1.28.0: Use append_pages_from_reader() instead.

append_pages_from_reader(reader: PdfReader, after_page_append: Optional[Callable[[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.

clean_page(page: Union[PageObject, IndirectObject]) → PageObject[source]: Perform some clean up in the page. Currently: convert NameObject nameddestination to TextStringObject (required for names/dests list)

cloneDocumentFromReader(reader: PdfReader, after_page_append: Optional[Callable[[PageObject], None]] = None) → None[source]: Deprecated since version 1.28.0: Use clone_document_from_reader() instead.

cloneReaderDocumentRoot(reader: PdfReader) → None[source]: Deprecated since version 1.28.0: Use clone_reader_document_root() instead.

clone_document_from_reader(reader: PdfReader, after_page_append: Optional[Callable[[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: PdfReader) → None[source]

Copy the reader document root to the writer.

Parameters: reader – PdfReader from the document root should be copied.

close() → None[source]: To match the functions from Merger

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

Encrypt this PDF file with the PDF Standard encryption handler.

Parameters

user_password (str) – The “user password”, which allows for opening and reading the PDF file with the restrictions provided.
owner_password (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.

find_bookmark(outline_item: Dict[str, Any], root: Optional[List[Union[Destination, List[Union[Destination, List[Destination]]]]]] = None) → Optional[List[int]][source]: Deprecated since version 2.9.0: Use find_outline_item() instead.

find_outline_item(outline_item: Dict[str, Any], root: Optional[List[Union[Destination, List[Union[Destination, List[Destination]]]]]] = None) → Optional[List[int]][source]

getNamedDestRoot() → 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: Union[int, IndirectObject]) → PdfObject[source]: Deprecated since version 1.28.0: Use get_object() instead.

getOutlineRoot() → TreeObject[source]: Deprecated since version 1.28.0: Use get_outline_root() instead.

getPage(pageNumber: int) → PageObject[source]: Deprecated since version 1.28.0: Use writer.pages[page_number] instead.

getPageLayout() → Literal[/NoLayout, /SinglePage, /OneColumn, /TwoColumnLeft, /TwoColumnRight, /TwoPageLeft, /TwoPageRight]][source]: Deprecated since version 1.28.0: Use page_layout instead.

getPageMode() → Literal[/UseNone, /UseOutlines, /UseThumbs, /FullScreen, /UseOC, /UseAttachments]][source]: Deprecated since version 1.28.0: Use page_mode instead.

getReference(obj: PdfObject) → IndirectObject[source]: Deprecated since version 1.28.0: Use get_reference() instead.

get_named_dest_root() → ArrayObject[source]

get_object(indirect_reference: Union[None, int, IndirectObject] = None, ido: Optional[IndirectObject] = None) → PdfObject[source]

get_outline_root() → TreeObject[source]

get_page(page_number: Optional[int] = None, pageNumber: Optional[int] = None) → 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: PdfObject) → IndirectObject[source]

get_threads_root() → ArrayObject[source]

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

insertBlankPage(width: Optional[Decimal] = None, height: Optional[Decimal] = None, index: int = 0) → PageObject[source]: Deprecated since version 1.28.0: Use insertBlankPage() instead.

insertPage(page: PageObject, index: int = 0, excluded_keys: Iterable[str] = ()) → PageObject[source]: Deprecated since version 1.28.0: Use insert_page() instead.

insert_blank_page(width: Optional[Decimal] = None, height: Optional[Decimal] = None, index: int = 0) → 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: PageObject, index: int = 0, excluded_keys: Iterable[str] = ()) → PageObject[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.

merge(position: Optional[int], fileobj: Union[Path, str, IO, PdfReader], outline_item: Optional[str] = None, pages: Optional[Union[str, PageRange, Tuple[int, int], Tuple[int, int, int], List[int]]] = None, import_outline: bool = True, excluded_fields: Optional[Union[List[str], Tuple[str, ...]]] = ()) → None[source]

Merge the pages from the given file into the output file at the specified page number.

Parameters

position (int) – The page number to insert this file. File will be inserted after the given number.
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.
outline_item (str) – Optionally, you may specify a string to build an outline (aka ‘bookmark’) to identify the beginning of the included file.
pages – can be a 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.
import_outline (bool) – 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.
excluded_fields (List) – 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

property open_destination: Union[None, Destination, TextStringObject, ByteStringObject]

Property to access the opening destination (“/OpenAction” entry in the PDF catalog). it returns None if the entry does not exist is not set.

: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)

property pageLayout: Literal[/NoLayout, /SinglePage, /OneColumn, /TwoColumnLeft, /TwoColumnRight, /TwoPageLeft, /TwoPageRight]]: Deprecated since version 1.28.0.

Use page_layout instead.

property pageMode: Literal[/UseNone, /UseOutlines, /UseThumbs, /FullScreen, /UseOC, /UseAttachments]]: Deprecated since version 1.28.0.

Use page_mode instead.

property page_layout: 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: 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[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.

removeLinks() → None[source]: 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() → None[source]: 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.

reset_translation(reader: Union[None, PdfReader, IndirectObject] = None) → None[source]

reset the translation table between reader and the writer object. late cloning will create new independent objects

Parameters: reader – PdfReader or IndirectObject refering a PdfReader object. if set to None or omitted, all tables will be reset.

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_layout(layout: typing_extensions.Literal[/NoLayout, /SinglePage, /OneColumn, /TwoColumnLeft, /TwoColumnRight, /TwoPageLeft, /TwoPageRight]) → None[source]

Set the page layout.

Parameters: layout (str) – The page layout to be used

Valid `layout` arguments
/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

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.

property threads: ArrayObject

Read-only property for the list of threads see §8.3.2 from PDF 1.7 spec

Returns: an Array (possibly empty) of Dictionaries with “/F” and “/I” properties

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[Path, str, IO]) → Tuple[bool, IO][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: IO) → None[source]