0
# PDF Merging
1

2
Merge multiple PDF files with control over page ranges, bookmarks, document properties, and advanced merging options. The PdfMerger class provides comprehensive PDF combination capabilities.
3

4
## Capabilities
5

6
### PdfMerger Class
7

8
Main class for merging multiple PDF files with advanced options for page selection, bookmark management, and document structure preservation.
9

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

16
        Args:
17
            strict: Whether to raise exceptions for correctable problems (default: False)
18
            fileobj: Optional output file path or object
19
        """
20

21
    def merge(
22
        self, 
23
        page_number: int, 
24
        fileobj, 
25
        outline_item: str = None, 
26
        pages = None, 
27
        import_outline: bool = True
28
    ) -> None:
29
        """
30
        Merge pages from a PDF at a specific position.
31

32
        Args:
33
            page_number (int): Position to insert pages at
34
            fileobj (str or file-like): PDF file to merge from
35
            outline_item (str, optional): Bookmark title for merged section
36
            pages (PageRange or slice, optional): Page range to merge (default: all pages)
37
            import_outline (bool): Whether to import bookmarks (default: True)
38
        """
39

40
    def append(
41
        self, 
42
        fileobj, 
43
        outline_item: str = None, 
44
        pages = None, 
45
        import_outline: bool = True
46
    ) -> None:
47
        """
48
        Append pages from a PDF to the end.
49

50
        Args:
51
            fileobj (str or file-like): PDF file to append from
52
            outline_item (str, optional): Bookmark title for appended section
53
            pages (PageRange or slice, optional): Page range to append (default: all pages)
54
            import_outline (bool): Whether to import bookmarks (default: True)
55
        """
56

57
    def write(self, fileobj) -> None:
58
        """
59
        Write the merged PDF to a file.
60

61
        Args:
62
            fileobj (str or file-like): Output file path or object
63
        """
64

65
    def close(self) -> None:
66
        """Close the merger and release resources."""
67

68
    def add_metadata(self, infos: Dict[str, Any]) -> None:
69
        """
70
        Add metadata to the merged PDF.
71

72
        Args:
73
            infos (dict): Metadata dictionary with keys like 'Title', 'Author', etc.
74
        """
75

76
    def set_page_layout(self, layout: str) -> None:
77
        """
78
        Set the page layout for the merged PDF.
79

80
        Args:
81
            layout: Page layout type
82
        """
83

84
    def set_page_mode(self, mode: PagemodeType) -> None:
85
        """
86
        Set the page mode for the merged PDF.
87

88
        Args:
89
            mode (PagemodeType): Page mode type
90
        """
91

92
    def add_outline_item(
93
        self, 
94
        title: str, 
95
        page_number: int, 
96
        parent: IndirectObject = None,
97
        color: Tuple[float, float, float] = None,
98
        bold: bool = False,
99
        italic: bool = False,
100
        fit: str = "/Fit",
101
        *args
102
    ) -> IndirectObject:
103
        """
104
        Add an outline (bookmark) item to the merged PDF.
105

106
        Args:
107
            title (str): Bookmark title
108
            page_number (int): Target page number
109
            parent (IndirectObject, optional): Parent bookmark
110
            color (tuple, optional): RGB color tuple
111
            bold (bool): Bold text (default: False)
112
            italic (bool): Italic text (default: False)
113
            fit (FitType): Fit type for destination
114

115
        Returns:
116
            IndirectObject: Created outline item
117
        """
118

119
    def add_named_destination(self, title: str, page_number: int) -> None:
120
        """
121
        Add a named destination to the merged PDF.
122

123
        Args:
124
            title (str): Destination name
125
            page_number (int): Target page number
126
        """
127
```
128

129
## Usage Examples
130

131
### Simple PDF Merging
132

133
```python
134
from PyPDF2 import PdfMerger
135

136
# Create merger instance
137
merger = PdfMerger()
138

139
# Append entire files
140
merger.append("document1.pdf")
141
merger.append("document2.pdf")
142
merger.append("document3.pdf")
143

144
# Write merged result
145
merger.write("merged_document.pdf")
146
merger.close()
147
```
148

149
### Merging Specific Page Ranges
150

151
```python
152
from PyPDF2 import PdfMerger, PageRange
153

154
merger = PdfMerger()
155

156
# Append specific pages using PageRange
157
merger.append("document1.pdf", pages=PageRange("1:5"))  # Pages 1-4
158
merger.append("document2.pdf", pages=PageRange("::2"))  # Every other page
159
merger.append("document3.pdf", pages=PageRange("10:"))  # Page 10 to end
160

161
# Using slice notation
162
merger.append("document4.pdf", pages=slice(0, 3))  # First 3 pages
163

164
merger.write("selective_merge.pdf")
165
merger.close()
166
```
167

168
## Deprecated Classes
169

170
### PdfFileMerger (Deprecated)
171

172
```python { .api }
173
class PdfFileMerger:
174
    """DEPRECATED: Use PdfMerger instead. Will be removed in PyPDF2 3.0.0."""
175
```
176

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