pdfrw Documentation

Overview

pdfrw is a pure Python library and utility designed for reading and writing PDF files. It is optimized for speed and is capable of faithfully reproducing vector formats without rasterization.

Key Capabilities

• PDF Operations: Subsetting, merging, rotating, and modifying metadata.
• Vector Fidelity: Reproduces vector images without converting them to rasters (used by rst2pdf).
• Integration: Can be used standalone or in conjunction with reportlab to reuse existing PDF content in new documents.
• Compatibility: Version 0.4 is tested on Python 2.6, 2.7, 3.3, 3.4, 3.5, and 3.6.
• License: Permissively licensed.

PDF files use 'indirect objects' to allow multiple references to the same data and to handle circular references.

• Reading: pdfrw automatically handles these. When it encounters an indirect object, the resulting Python object will have an indirect attribute set to True.
• Writing: To prevent infinite loops when writing custom data structures, you must break circular references by ensuring at least one object in every cycle has an indirect attribute that evaluates to True.

While pdfrw is primarily a container library, it provides high-level support for:

• PDF Pages: Finding and extracting pages for new documents.
• Form XObjects: Converting pages or rectangles into Form XObjects, supporting scaling, rotation, and positioning.
• ReportLab Integration: Recursively creating reportlab objects from internal pdfrw formats, allowing you to reuse existing PDF content when building new documents with reportlab.

The pdfrw usage model treats most objects as strings during writing, with two primary exceptions:

1. PdfArray: A subclass of list. It supports an indirect attribute to be written as an indirect PDF object and uses lazy resolution to resolve references to other indirect objects only when needed.
2. PdfDict: A subclass of dict. It supports an indirect attribute and lazy resolution.
   • Attribute Access: Since PDF names (like /CamelCase) are used as keys, you can access dictionary elements using object attribute access (e.g., dict.Key) or standard dictionary index lookup (e.g., dict['/Key']).
   • Streams: PdfDict can have an associated stream. Assigning a value to the .stream attribute automatically sets the PDF /Length attribute for that dictionary.

The following scripts demonstrate different ways to manipulate PDF pages by converting them to XObjects and re-rendering them using reportlab:

• subset.py: Prints a specific subset of pages from a source PDF.
• 4up.py: Prints pages in a 4-up layout (four pages per sheet).
• booklet.py: Creates a booklet layout from the provided pages.

To run the library tests, you must provide the required static PDF assets which are not included in the main package.

1. Clone the full repository from GitHub.
2. Navigate to the tests directory.
3. Clone the static_pdfs repository into a subdirectory named static_pdfs within the tests folder.
4. Run tests using pytest, unittest, or nose.

Example using pytest:

$ pip install pytest reportlab
$ pwd
<...>/pdfrw/tests
$ git clone https://github.com/pmaupin/static_pdfs
$ ln -s ../pdfrw
$ pytest

To run a specific test case:

$ pytest test_roundtrip.py -k "test_compress_9f98322c243fe67726d56ccfa8e0885b.pdf"

The following features are currently not supported by pdfrw:

• Most compression/decompression filters.
• Encryption.

Workaround: You can use the pdftk command-line tool to convert PDFs to remove encryption and compression before processing them with pdfrw.

If pdfrw examples or your own implementations fail to work with a specific PDF, the file may be compressed or encrypted.

Solution: Try using pdftk to uncompress and/or unencrypt the PDF before processing it with pdfrw.