0
# PDF Writing
1

2
Create new PDF files, add and manage pages, insert content, add metadata and security features. The PdfWriter class provides comprehensive PDF creation and modification capabilities.
3

4
## Capabilities
5

6
### PdfWriter Class
7

8
Main class for creating and writing PDF files with full control over pages, metadata, security, and advanced features.
9

10
```python { .api }
11
class PdfWriter:
12
    def __init__(self, fileobj: Union[str, bytes] = ""):
13
        """
14
        Initialize a PdfWriter instance.
15

16
        Args:
17
            fileobj: Optional output file path or object
18
        """
19

20
    @property
21
    def pdf_header(self) -> bytes:
22
        """PDF version header bytes."""
23

24
    @property
25
    def pages(self) -> List[PageObject]:
26
        """List of pages in the current PDF."""
27

28
    @property
29
    def page_layout(self) -> Optional[str]:
30
        """Page layout preference for the document."""
31

32
    @property
33
    def page_mode(self) -> Optional[PagemodeType]:
34
        """Page mode preference for the document."""
35

36
    @property
37
    def open_destination(self) -> Union[None, Destination, TextStringObject, ByteStringObject]:
38
        """Destination to open when document is first displayed."""
39

40
    @property
41
    def threads(self) -> ArrayObject:
42
        """Article threads in the document."""
43

44
    def add_page(self, page: PageObject) -> None:
45
        """
46
        Add a page to the PDF.
47

48
        Args:
49
            page (PageObject): Page to add to the document
50
        """
51

52
    def insert_page(self, page: PageObject, index: int = 0) -> None:
53
        """
54
        Insert a page at a specific position.
55

56
        Args:
57
            page (PageObject): Page to insert
58
            index (int): Position to insert page (default: 0 - beginning)
59
        """
60

61
    def get_page(self, page_number: int) -> PageObject:
62
        """
63
        Get a specific page by number.
64

65
        Args:
66
            page_number (int): Zero-based page index
67

68
        Returns:
69
            PageObject: The requested page
70

71
        Raises:
72
            IndexError: If page number is out of range
73
        """
74

75
    def add_blank_page(self, width: float, height: float) -> PageObject:
76
        """
77
        Add a blank page to the PDF.
78

79
        Args:
80
            width (float): Page width in points
81
            height (float): Page height in points
82

83
        Returns:
84
            PageObject: The created blank page
85
        """
86

87
    def insert_blank_page(self, width: float, height: float, index: int = 0) -> PageObject:
88
        """
89
        Insert a blank page at a specific position.
90

91
        Args:
92
            width (float): Page width in points
93
            height (float): Page height in points
94
            index (int): Position to insert page (default: 0 - beginning)
95

96
        Returns:
97
            PageObject: The created blank page
98
        """
99

100
    def write(self, stream) -> Tuple[bool, Union[FileIO, BytesIO, BufferedReader, BufferedWriter]]:
101
        """
102
        Write the PDF to a stream.
103

104
        Args:
105
            stream (file-like object): Output stream for PDF data
106

107
        Returns:
108
            tuple: Success status and stream object
109
        """
110

111
    def add_metadata(self, infos: Dict[str, Any]) -> None:
112
        """
113
        Add metadata to the PDF.
114

115
        Args:
116
            infos (dict): Metadata dictionary with keys like 'Title', 'Author', 'Subject', etc.
117
        """
118

119
    def add_js(self, javascript: str) -> None:
120
        """
121
        Add JavaScript to the PDF.
122

123
        Args:
124
            javascript (str): JavaScript code to embed
125
        """
126

127
    def add_attachment(self, filename: str, data: bytes) -> None:
128
        """
129
        Add a file attachment to the PDF.
130

131
        Args:
132
            filename (str): Name for the attached file
133
            data (bytes): File content as bytes
134
        """
135

136
    def encrypt(
137
        self, 
138
        user_password: str, 
139
        owner_password: str = "", 
140
        use_128bit: bool = True, 
141
        permissions_flag: int = -1
142
    ) -> None:
143
        """
144
        Encrypt the PDF with password protection.
145

146
        Args:
147
            user_password (str): Password for opening the PDF
148
            owner_password (str): Password for full access (default: same as user_password)
149
            use_128bit (bool): Use 128-bit encryption (default: True)
150
            permissions_flag (int): Permission flags (-1 for full permissions)
151
        """
152

153
    def add_outline_item(
154
        self, 
155
        title: str, 
156
        page_number: int, 
157
        parent: IndirectObject = None,
158
        color: Tuple[float, float, float] = None,
159
        bold: bool = False,
160
        italic: bool = False,
161
        fit: str = "/Fit",
162
        *args
163
    ) -> IndirectObject:
164
        """
165
        Add an outline (bookmark) item.
166

167
        Args:
168
            title (str): Bookmark title
169
            page_number (int): Target page number
170
            parent (IndirectObject, optional): Parent bookmark
171
            color (tuple, optional): RGB color tuple
172
            bold (bool): Bold text (default: False)
173
            italic (bool): Italic text (default: False)
174
            fit (FitType): Fit type for destination
175

176
        Returns:
177
            IndirectObject: Created outline item
178
        """
179

180
    def add_named_destination(self, title: str, page_number: int) -> IndirectObject:
181
        """
182
        Add a named destination.
183

184
        Args:
185
            title (str): Destination name
186
            page_number (int): Target page number
187

188
        Returns:
189
            IndirectObject: Created destination
190
        """
191

192
    def remove_links(self) -> None:
193
        """Remove all links from all pages."""
194

195
    def remove_images(self, ignore_byte_string_object: bool = False) -> None:
196
        """
197
        Remove images from all pages.
198

199
        Args:
200
            ignore_byte_string_object (bool): Whether to ignore byte string objects
201
        """
202

203
    def remove_text(self, ignore_byte_string_object: bool = False) -> None:
204
        """
205
        Remove text from all pages.
206

207
        Args:
208
            ignore_byte_string_object (bool): Whether to ignore byte string objects
209
        """
210

211
    def add_annotation(self, page_number: int, annotation) -> None:
212
        """
213
        Add an annotation to a specific page.
214

215
        Args:
216
            page_number (int): Target page number
217
            annotation: Annotation object to add
218
        """
219

220
    def clone_document_from_reader(
221
        self, 
222
        reader: PdfReader, 
223
        after_page_append: Callable = None
224
    ) -> None:
225
        """
226
        Clone all pages and metadata from a reader.
227

228
        Args:
229
            reader (PdfReader): Source reader to clone from
230
            after_page_append (callable, optional): Callback after each page
231
        """
232

233
    def append_pages_from_reader(
234
        self, 
235
        reader: PdfReader, 
236
        after_page_append: Callable = None
237
    ) -> None:
238
        """
239
        Append all pages from a reader.
240

241
        Args:
242
            reader (PdfReader): Source reader
243
            after_page_append (callable, optional): Callback after each page
244
        """
245

246
    def update_page_form_field_values(
247
        self, 
248
        page: PageObject, 
249
        fields: Dict[str, Any], 
250
        flags: int = 0
251
    ) -> None:
252
        """
253
        Update form field values on a page.
254

255
        Args:
256
            page (PageObject): Target page
257
            fields (dict): Field names and new values
258
            flags (int): Update flags
259
        """
260
```
261

262
## Usage Examples
263

264
### Creating a Simple PDF
265

266
```python
267
from PyPDF2 import PdfWriter, PageObject
268
from PyPDF2.generic import RectangleObject
269

270
# Create a new PDF writer
271
writer = PdfWriter()
272

273
# Add a blank page (8.5" x 11" = 612 x 792 points)
274
page = writer.add_blank_page(612, 792)
275

276
# Write to file
277
with open("new_document.pdf", "wb") as output_file:
278
    writer.write(output_file)
279
```
280

281
### Copying Pages from Another PDF
282

283
```python
284
from PyPDF2 import PdfReader, PdfWriter
285

286
# Read source PDF
287
reader = PdfReader("source.pdf")
288
writer = PdfWriter()
289

290
# Copy specific pages
291
writer.add_page(reader.pages[0])  # First page
292
writer.add_page(reader.pages[2])  # Third page
293

294
# Or copy all pages
295
for page in reader.pages:
296
    writer.add_page(page)
297

298
# Write output
299
with open("copied_pages.pdf", "wb") as output_file:
300
    writer.write(output_file)
301
```
302

303
### Adding Metadata and Security
304

305
```python
306
from PyPDF2 import PdfWriter, PdfReader
307

308
reader = PdfReader("input.pdf")
309
writer = PdfWriter()
310

311
# Copy pages
312
for page in reader.pages:
313
    writer.add_page(page)
314

315
# Add metadata
316
writer.add_metadata({
317
    '/Title': 'My Document',
318
    '/Author': 'Jane Doe',
319
    '/Subject': 'PDF Creation Example',
320
    '/Creator': 'PyPDF2 Script',
321
    '/Producer': 'PyPDF2'
322
})
323

324
# Encrypt the PDF
325
writer.encrypt(
326
    user_password="user123",
327
    owner_password="owner456", 
328
    use_128bit=True,
329
    permissions_flag=0b11111100  # Allow printing, copying, etc.
330
)
331

332
with open("secure_document.pdf", "wb") as output_file:
333
    writer.write(output_file)
334
```
335

336
### Adding Bookmarks and Structure
337

338
```python
339
from PyPDF2 import PdfWriter, PdfReader
340

341
reader = PdfReader("chapters.pdf")
342
writer = PdfWriter()
343

344
# Copy all pages
345
for page in reader.pages:
346
    writer.add_page(page)
347

348
# Add bookmarks
349
chapter1 = writer.add_outline_item("Chapter 1: Introduction", 0)
350
chapter2 = writer.add_outline_item("Chapter 2: Methods", 5)
351
chapter3 = writer.add_outline_item("Chapter 3: Results", 10)
352

353
# Add sub-bookmarks
354
writer.add_outline_item("1.1 Background", 1, parent=chapter1)
355
writer.add_outline_item("1.2 Objectives", 3, parent=chapter1)
356

357
# Add named destinations
358
writer.add_named_destination("Introduction", 0)
359
writer.add_named_destination("Conclusion", len(reader.pages) - 1)
360

361
with open("structured_document.pdf", "wb") as output_file:
362
    writer.write(output_file)
363
```
364

365
### Adding JavaScript and Attachments
366

367
```python
368
from PyPDF2 import PdfWriter, PdfReader
369

370
reader = PdfReader("base.pdf")
371
writer = PdfWriter()
372

373
# Copy pages
374
for page in reader.pages:
375
    writer.add_page(page)
376

377
# Add JavaScript for automatic printing
378
writer.add_js("""
379
    this.print({
380
        bUI: true,
381
        bSilent: false,
382
        bShrinkToFit: true
383
    });
384
""")
385

386
# Add file attachment
387
with open("data.xlsx", "rb") as attachment_file:
388
    attachment_data = attachment_file.read()
389
    writer.add_attachment("data.xlsx", attachment_data)
390

391
with open("enhanced_document.pdf", "wb") as output_file:
392
    writer.write(output_file)
393
```
394

395
### Working with Form Fields
396

397
```python
398
from PyPDF2 import PdfReader, PdfWriter
399

400
# Read PDF with form fields
401
reader = PdfReader("form.pdf")
402
writer = PdfWriter()
403

404
# Copy pages
405
for page in reader.pages:
406
    writer.add_page(page)
407

408
# Update form field values
409
form_data = {
410
    "name": "John Smith",
411
    "email": "john@example.com",
412
    "phone": "(555) 123-4567"
413
}
414

415
# Update fields on first page
416
writer.update_page_form_field_values(writer.pages[0], form_data)
417

418
with open("filled_form.pdf", "wb") as output_file:
419
    writer.write(output_file)
420
```
421

422
## Deprecated Classes
423

424
### PdfFileWriter (Deprecated)
425

426
```python { .api }
427
class PdfFileWriter:
428
    """DEPRECATED: Use PdfWriter instead. Will be removed in PyPDF2 3.0.0."""
429
```
430

431
This class is deprecated and should not be used in new code. All functionality has been moved to `PdfWriter` with the same API.