PDFDocument (arcpy.mapping)
Summary
Allows manipulation of PDF documents, including facilities for merging pages, deleting pages, setting document open behavior, adding file attachments, and creating or changing document security settings.
Discussion
PDFDocumentOpen and PDFDocumentCreate are two functions that provide a reference to a PDFDocument object.
When using the appendPages, insertPages, or attachFile methods, it is important to pass a string that represents the path to an existing PDF file. If a PDFDocument object is passed, the method will fail. It is also required that PDF security be the same for all documents that are being appended, inserted, or attached. For example, if you want to append three documents into one multipage PDF and only the first document is protected with a password, the other two documents must also first be given the same password before appendPages is used.
The deletePages method is useful for swapping out only the pages that have been modified. It may take a long time to process dozens of pages. If only a relative few have been modified, it is faster to delete only those pages, then insert the newly updated pages using the insertPages method.
For more discussion on how to create map books, see the Building Map Books with ArcGIS help topic.
Syntax
| Parameter | Explanation | Data Type |
pdf_path |
A string that specifies the path and file name for the resulting PDF file when the saveAndClose method is called. | String |
The PDFDocumentCreate function receives a path to determine the save location and file name where a new PDF file will be created. However, no PDF file will be created until subsequent steps are performed to insert or append pages and save the PDF file. PDFDocumentCreate will return a PDFDocument object that your script should then manipulate and save. A common scenario for using this function is the creation of a PDF map book. The steps typically involve exporting a number of separate PDF files from map documents, creating a new PDFDocument object, appending content from the exported PDF files and other documents, and saving the final PDF map book.
Please note that it is not possible to create blank PDF files, nor does the PDFDocumentCreate function add any blank pages to the document contents. For the saveAndClose method to successfully create a file, content must be added to the PDFDocument object using the appendPages or insertPages methods.
For more discussion on how to create map books, see the Building Map Books with ArcGIS help topic.
This script will create a new PDF document, append the contents of three separate PDF documents, and save the resulting PDF file.
import arcpy, os
#Set file name and remove if it already exists
pdfPath = r"C:\Project\ParcelAtlasMapBook.pdf"
if os.path.exists(pdfPath):
os.remove(pdfPath)
#Create the file and append pages
pdfDoc = arcpy.mapping.PDFDocumentCreate(pdfPath)
pdfDoc.appendPages(r"C:\Project\Title.pdf")
pdfDoc.appendPages(r"C:\Project\ParcelAtlas.pdf")
pdfDoc.appendPages(r"C:\Project\ContactInfo.pdf")
#Commit changes and delete variable reference
pdfDoc.saveAndClose()
del pdfDoc
Properties
| Property | Explanation | Data Type |
| pageCount (Read Only) |
Returns an integer that represents the total number of pages in the PDF document | Long |
Method Overview
| Method | Explanation |
| appendPages (pdf_path, {input_pdf_password}) |
Appends one PDF document to the end of another |
| attachFile (file_path, {description}) |
Attaches files to existing PDF documents (Attachments are then accessible to users when the PDF file is opened in a PDF viewer application.) |
| deletePages (page_range) |
Provides the ability to delete one or multiple pages within an existing PDF document. |
| insertPages (pdf_path, {before_page_number}, {input_pdf_password}) |
Allows inserting the contents of one PDF document at the beginning or in between the pages of another PDFDocument |
| saveAndClose () |
Saves any changes made to the currently referenced PDFDocument |
| updateDocProperties ({pdf_title}, {pdf_author}, {pdf_subject}, {pdf_keywords}, {pdf_open_view}, {pdf_layout}) |
Allows updating of the PDF document metadata and can also set the certain behaviors that will trigger when the document is opened in Adobe Reader or Adobe Acrobat, such as the initial view mode and the page thumbnails view |
| updateDocSecurity (new_master_password, {new_user_password}, {encryption}, {permissions}) |
Provides the mechanism that sets password, encryption, and security restrictions on PDF files. |
Methods
| Parameter | Explanation | Data Type |
pdf_path |
A string that includes the location and name of the input PDF document to be appended | String |
input_pdf_password |
A string that defines the master password to a protected file (The default value is None) | String |
When appending secured PDF documents that each have different security settings, the output settings will be based on the primary document that pages are being appended to. For example, if the document that is being appended to does not have password information saved, but the appended pages do, the resulting document will not have password information saved.
| Parameter | Explanation | Data Type |
file_path |
A string that includes the location and name of the file to be attached to the PDF document. | String |
description |
An optional string to be used as a description for the attachment. The user will see this string when viewing the attachment in a PDF viewer application. | String |
Use the attachFile method to attach any type of file to a PDF document.
| Parameter | Explanation | Data Type |
page_range |
A string that defines the page or pages to be deleted. Delete a single page by passing in a single value as a string (for example, "3"). Multiple pages can be deleted using a comma between each value (for example, "3, 5, 7"). Ranges can also be applied (for example, "1, 3, 5-12" ). | String |
It is important to keep track of the pages that are being deleted, because each time pages are deleted, the internal PDF page numbers are automatically adjusted. For example, page 3 becomes page 2 immediately after page 1 or page 2 are deleted. If page 1 and page 2 are deleted, page 3 becomes page 1. You need to consider this if you are using deletePages and then immediately using appendPages or insertPages.
| Parameter | Explanation | Data Type |
pdf_path |
A string that includes the location and name of the input PDF document to be inserted. | String |
before_page_number |
An integer that defines a page number in the currently referenced PDFDocument before which the new page(s) will be inserted. For example, if the before_page_value is 1, the inserted page will be inserted before all pages. (The default value is 1) | String |
input_pdf_password |
A string that defines the master password to a protected file. (The default value is None) | String |
To add pages to the end of the current PDFDocument, use appendPages instead.
When inserting secured PDF documents that have different security settings, the output settings will be based on the primary document that pages are being inserted into. For example, if the document that is being inserted into does not have password information saved, but the inserted pages do, the resulting document will not have password information saved.
The saveAndClose method must be used for changes to be maintained. If a script exits before saveAndClose is executed, changes will not be saved.
| Parameter | Explanation | Data Type |
pdf_title |
A string defining the document title, a PDF metadata property. (The default value is None) | String |
pdf_author |
A string defining the document author, a PDF metadata property. (The default value is None) | String |
pdf_subject |
A string defining the document subject, a PDF metadata property. (The default value is None) | String |
pdf_keywords |
A string defining the document keywords, a PDF metadata property. (The default value is None) | String |
pdf_open_view |
A string or number that will define the behavior to trigger when the PDF file is viewed. The default value is USETHUMBS, which will show the Adobe Reader Pages panel automatically when the PDF is opened.
(The default value is USE_THUMBS) | String |
pdf_layout |
A string or number that will define the initial view mode to trigger when the PDF file is viewed.
(The default value is SINGLE_PAGE) | String |
A pdf_open setting of FULL_SCREEN will prompt a warning about full-screen mode when the PDF is opened. Setting pdf_open to a different option will not clear this setting unless pdf_open is set to USE_NONE.
| Parameter | Explanation | Data Type |
new_master_password |
A string that defines the master document password. This password is required for appending and inserting pages into a secured PDF. | String |
new_user_password |
A string that defines the user password needed to open the PDF document for viewing. (The default value is None) | String |
encryption |
A string that defines the encryption technique used on the PDF.
(The default value is RC4) | String |
permissions |
A string that defines the capabilities restricted by the document security settings. The permissions argument can accept a list of strings describing all the options to be restricted. The document restrictions can be viewed in Adobe Acrobat in the Document Properties Document Restrictions Summary page.
(The default value is ALL) | String |
A password on a secured PDF document can be removed simply by setting the new_master_password and new_user_password properties to empty strings.
Code Sample
This script will create a new PDF document, append the contents of two separate PDF documents, and save the resulting PDF file.
import arcpy, os
#Set file name and remove if it already exists
pdfPath = r"C:\Project\ParcelAtlasMapBook.pdf"
if os.path.exists(pdfPath):
os.remove(pdfPath)
#Create the file and append pages
pdfDoc = arcpy.mapping.PDFDocumentCreate(pdfPath)
pdfDoc.appendPages(r"C:\Project\Title.pdf")
pdfDoc.appendPages(r"C:\Project\ParcelAtlas.pdf")
#Commit changes and delete variable reference
pdfDoc.saveAndClose()
del pdfDoc
The following script modifies the PDF document metadata properties for the document created in example 1 above and sets the style in which the document will open.
import arcpy
pdfDoc = arcpy.mapping.PDFDocumentOpen(r"C:\Project\ParcelAtlasMapBook.pdf")
pdfDoc.updateDocProperties(pdf_title="Atlas Map",
pdf_author="Author",
pdf_subject="Map Book",
pdf_keywords="Atlas; Map Books",
pdf_open_view="USE_THUMBS",
pdf_layout="SINGLE_PAGE")
pdfDoc.saveAndClose()
del pdfDoc
The following script will set the user password to esri, encrypt the PDF using RC4 compression, and require a password when the document is opened.
import arcpy
pdfDoc = arcpy.mapping.PDFDocumentOpen(r"C:\Project\ParcelAtlasMapBook.pdf")
pdfDoc.updateDocSecurity("master", "user", "RC4", "OPEN")
pdfDoc.saveAndClose()
del pdfDoc
The following pages will append a final page to the end of the already existing multipage document. The master password is required to make this change to a secured PDF document.
import arcpy
pdfDoc = arcpy.mapping.PDFDocumentOpen(r"C:\Project\ParcelAtlasMapBook.pdf", "master")
pdfDoc.appendPages(r"C:\Project\ContactInfo.pdf")
pdfDoc.saveAndClose()
del pdfDoc
The following script will replace a total of four pages in an existing PDF using deletePages followed by insertPages. Note how we insert the new page 3 before the current page 3 which was really page 4 before the original page 3 was removed. The same applies to the range of pages 5–7.
import arcpy
pdfDoc = arcpy.mapping.PDFDocumentOpen(r"C:\Project\ParcelAtlasMapBook.pdf", "master")
pdfDoc.deletePages("3, 5-7")
pdfDoc.insertPages(r"C:\Project\NewPage3.pdf", 3, "master")
pdfDoc.insertPages(r"C:\Project\NewPages5-7.pdf", 5, "master")
pdfDoc.saveAndClose()
del pdfDoc