pypdf

https://pypdf.readthedocs.io/en/stable/
Admin
pypdf is a free and open source pure-Python PDF library capable of splitting, merging, cropping,...
Tokens:311,594
Snippets:2,562
Trust Score:9.6
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install jbig2dec for JBIG2 support

Source: https://pypdf.readthedocs.io/en/stable/_sources/user/installation.md.txt

Installs the global OS-level package jbig2dec, required for JBIG2 support. Example for Ubuntu.

```bash
sudo apt-get install jbig2dec
```

--------------------------------

### Install a PR version from git with pip

Source: https://pypdf.readthedocs.io/en/stable/_sources/dev/testing.md.txt

Install a version of pypdf from a specific branch of a repository, as shown in the example with repository pubpub-zz and branch iss2200.

```bash
pip install git+https://github.com/pubpub-zz/pypdf.git@iss2200
```

--------------------------------

### Install development requirements

Source: https://pypdf.readthedocs.io/en/stable/_sources/dev/intro.md.txt

Installs the development dependencies listed in requirements/dev.txt. Run this in your local pypdf copy before contributing.

```bash
pip install -r requirements/dev.txt
```

--------------------------------

### Install pypdf with all optional dependencies

Source: https://pypdf.readthedocs.io/en/stable/_sources/user/installation.md.txt

Installs pypdf along with all optional dependencies, including cryptography and image support.

```bash
pip install pypdf[full]
```

--------------------------------

### Install development version of pypdf

Source: https://pypdf.readthedocs.io/en/stable/_sources/user/installation.md.txt

Installs the current development version of pypdf directly from the GitHub repository.

```bash
pip install git+https://github.com/py-pdf/pypdf.git
```

--------------------------------

### Install pypdf with image dependencies

Source: https://pypdf.readthedocs.io/en/stable/_sources/user/installation.md.txt

Installs pypdf with Pillow for image extraction support.

```bash
pip install pypdf[image]
```

--------------------------------

### Install CI requirements for testing

Source: https://pypdf.readthedocs.io/en/stable/_sources/dev/testing.md.txt

Install the CI requirements needed to run the tests. Use ci-3.11.txt for Python 3.11 or higher.

```bash
pip install -r requirements/ci.txt
```

```bash
pip install -r requirements/ci-3.11.txt
```

--------------------------------

### Google-Style docstring example

Source: https://pypdf.readthedocs.io/en/stable/_sources/dev/documentation.md.txt

Google-Style docstring template for functions with PEP 484 type annotations. Section order is Args, Returns, Raises, Examples; remove the Returns block if there is no return value, and properties should not have any sections.

```python
def example(param1: int, param2: str) -> bool:
    """
    Example function with PEP 484 type annotations.

    Args:
      param1: The first parameter.
      param2: The second parameter.

    Returns:
      The return value. True for success, False otherwise.

    Raises:
      AttributeError: The ``Raises`` section is a list of all exceptions
        that are relevant to the interface.
      ValueError: If `param2` is equal to `param1`.

    Examples:
        Examples should be written in doctest format, and should illustrate how
        to use the function.

        >>> print([i for i in example_generator(4)])
        [0, 1, 2, 3]
    """
```

--------------------------------

### Example indirect objects from test_reader.py::test_get_images_raw

Source: https://pypdf.readthedocs.io/en/stable/_sources/dev/pdf-format.md.txt

A concrete example of indirect objects in the PDF body, showing the syntax for objects, references, and dictionaries. This example is referenced from the test file test_reader.py::test_get_images_raw.

```text
1 0 obj << /Count 1 /Kids [4 0 R] /Type /Pages >> endobj
2 0 obj << >> endobj
3 0 obj << >> endobj
4 0 obj << /Contents 3 0 R /CropBox [0.0 0.0 2550.0 3508.0]
 /MediaBox [0.0 0.0 2550.0 3508.0] /Parent 1 0 R
 /Resources << /Font << >> >>
 /Rotate 0 /Type /Page >> endobj
5 0 obj << /Pages 1 0 R /Type /Catalog >> endobj
```

--------------------------------

### pypdf._writer imports and module setup

Source: https://pypdf.readthedocs.io/en/stable/_modules/pypdf/_writer.html

Imports and module-level setup for pypdf._writer, including conditional typing imports for Python 3.11+ and the ALL_DOCUMENT_PERMISSIONS constant.

```python
# Copyright (c) 2006, Mathieu Fenniak
# Copyright (c) 2007, Ashish Kulkarni <kulkarni.ashish@gmail.com>
#
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are
# met:
#
# * Redistributions of source code must retain the above copyright notice,
# this list of conditions and the following disclaimer.
# * Redistributions in binary form must reproduce the above copyright notice,
# this list of conditions and the following disclaimer in the documentation
# and/or other materials provided with the distribution.
# * The name of the author may not be used to endorse or promote products
# derived from this software without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.

import decimal
import enum
import hashlib
import re
import struct
import sys
from collections.abc import Iterable, Mapping, Sequence
from io import BytesIO, FileIO, IOBase
from itertools import compress
from pathlib import Path
from re import Pattern
from types import TracebackType
from typing import (
    IO,
    Any,
    Callable,
    Literal,
    Optional,
    Union,
    cast,
)

if sys.version_info >= (3, 11):
    from typing import Self
else:
    from typing_extensions import Self

from ._doc_common import DocumentInformation, PdfDocCommon
from ._encryption import EncryptAlgorithm, Encryption
from ._page import PageObject, Transformation
from ._page_labels import nums_clear_range, nums_insert, nums_next
from ._reader import PdfReader
from ._utils import (
    StrByteType,
    StreamType,
    _get_max_pdf_version_header,
    deprecate_with_replacement,
    deprecation_no_replacement,
    logger_warning,
)
from .actions import Action, JavaScript
from .constants import AnnotationDictionaryAttributes as AA
from .constants import (
    CatalogAttributes,
    Core,
    GoToActionArguments,
    ImageType,
    InteractiveFormDictEntries,
    OutlineFontFlag,
    PageLabelStyle,
    PagesAttributes,
    TypFitArguments,
    UserAccessPermissions,
)
from .constants import FieldDictionaryAttributes as FA
from .constants import PageAttributes as PG
from .constants import TrailerKeys as TK
from .errors import LimitReachedError, PdfReadError, PyPdfError
from .generic import (
    PAGE_FIT,
    ArrayObject,
    BooleanObject,
    ByteStringObject,
    ContentStream,
    Destination,
    DictionaryObject,
    EmbeddedFile,
    Fit,
    FloatObject,
    IndirectObject,
    NameObject,
    NullObject,
    NumberObject,
    PdfObject,
    RectangleObject,
    ReferenceLink,
    StreamObject,
    TextStringObject,
    TreeObject,
    ViewerPreferences,
    create_string_object,
    extract_links,
    hex_to_rgb,
    is_null_or_none,
)
from .generic._appearance_stream import TextStreamAppearance
from .pagerange import PageRange, PageRangeSpec
from .types import (
    AnnotationSubtype,
    BorderArrayType,
    LayoutType,
    OutlineItemType,
    OutlineType,
    PagemodeType,
)
from .xmp import XmpInformation

ALL_DOCUMENT_PERMISSIONS = UserAccessPermissions.all()
```

--------------------------------

### Install pypdf for current user with pip

Source: https://pypdf.readthedocs.io/en/stable/_sources/user/installation.md.txt

Installs pypdf for the current user without requiring superuser privileges.

```bash
pip install --user pypdf
```

--------------------------------

### Expected Output for Nested Outline Example

Source: https://pypdf.readthedocs.io/en/stable/_sources/user/handling-outlines.md.txt

Shows the expected console output when running the recursive outline printing example on 'nested-example.pdf'. The output displays the nested hierarchy with indentation and page numbers.

```text
Nested Outline Hierarchy:
-------------------------
- Chapter 1 (Page 1)
  - Section 1.1 (Page 1)
  - Section 1.2 (Page 1)
```

--------------------------------

### Initialize sample-files submodule

Source: https://pypdf.readthedocs.io/en/stable/_sources/dev/intro.md.txt

Fetches the sample-files submodule, which contains additional test files for edge cases and larger PDFs. Required to run the full test suite.

```bash
git submodule update --init
```

--------------------------------

### Example trailer

Source: https://pypdf.readthedocs.io/en/stable/_sources/dev/pdf-format.md.txt

Shows the trailer dictionary with /Root and /Size entries, followed by startxref and %%EOF markers. The trailer is always at the bottom of the file.

```text
trailer << /Root 5 0 R
           /Size 6
        >>
startxref 1234
%%EOF
```

--------------------------------

### Install docs requirements, change directory, and run doctest

Source: https://pypdf.readthedocs.io/en/stable/dev/documentation.html

These commands install the documentation dependencies, change into the docs directory, and run Sphinx's doctest build. Use them to run the documentation tests locally; a successful run shows a 'Doctest summary' without failures in the output.

```unknown
pip install -r requirements/docs.txt

```

```unknown
cd docs

```

```unknown
make doctest

```

--------------------------------

### codespacerange mapping example

Source: https://pypdf.readthedocs.io/en/stable/_sources/dev/cmaps.md.txt

The bfchar mapping that defines the starting point for the codespacerange, mapping 1B to FB00.

```text
1 beginbfchar
<1B> <FB00>
```

--------------------------------

### Extract all images from a PDF page

Source: https://pypdf.readthedocs.io/en/stable/_sources/user/extract-images.md.txt

Iterates over the images on the first page of a PDF and saves each to a file. Requires optional dependencies (see installation guide). The file names may not be unique and can contain arbitrary characters, so sanitize them before writing to disk.

```python
from pypdf import PdfReader

reader = PdfReader("example.pdf")

page = reader.pages[0]

for i, image_file_object in enumerate(page.images):
    file_name = "out-image-" + str(i) + "-" + image_file_object.name
    image_file_object.image.save(file_name)
```

--------------------------------

### Recursively Print Nested Outlines with pypdf

Source: https://pypdf.readthedocs.io/en/stable/_sources/user/handling-outlines.md.txt

Defines a recursive print_outline function that traverses nested outline lists, printing each item with indentation and page numbers. Uses get_destination_page_number to get page indices and handles missing destinations. The example reads 'nested-example.pdf' and prints the hierarchy.

```python
from typing import List, Union

from pypdf import PdfReader
from pypdf.generic import Destination


def print_outline(
    outlines: List[Union[Destination, List[Destination]]],
    reader: PdfReader,
    level: int = 0
) -> None:
    """Recursively print all outline items with indentation."""
    for item in outlines:
        if isinstance(item, list):
            # Recursively handle the nested list of children
            print_outline(item, reader, level + 1)
        else:
            page_number = reader.get_destination_page_number(item)

            indent = "  " * level

            if page_number is None:
                print(f"{indent}- {item.title} (No page destination)")
            else:
                print(f"{indent}- {item.title} (Page {page_number + 1})")


reader = PdfReader("nested-example.pdf")

print("Nested Outline Hierarchy:")
print("-" * 25)

print_outline(reader.outline, reader)
```

--------------------------------

### Example: transform with vertical and horizontal mirror

Source: https://pypdf.readthedocs.io/en/stable/modules/Transformation.html

Shows how to apply one transformation to another using the transform method, creating vertical and horizontal mirrors.

```python
>>> from pypdf import PdfWriter, Transformation
>>> height, width = 40, 50
>>> page = PdfWriter().add_blank_page(800, 600)
>>> op = Transformation((1, 0, 0, -1, 0, height)) # vertical mirror
>>> op = Transformation().transform(Transformation((-1, 0, 0, 1, width, 0)))  # horizontal mirror
>>> page.add_transformation(op)

```

--------------------------------

### Advanced styling and fit options with Fit helper

Source: https://pypdf.readthedocs.io/en/stable/_sources/user/handling-outlines.md.txt

Demonstrates customizing outline items with color, bold, italic, is_open, and Fit view modes (Fit.fit, Fit.fit_horizontally, Fit.xyz). Creates a chapter and two sections with different styles and saves to 'advanced-example.pdf'.

```python
from pypdf import PdfWriter
from pypdf.generic import Fit

writer = PdfWriter(clone_from="crazyones.pdf")

# Top-level chapter (Points to Page 3, Index 2)
chapter2 = writer.add_outline_item(
    title="Chapter 2",
    page_number=0,
    color=(0, 0, 1),
    bold=True,
    italic=False,
    is_open=True,
    fit=Fit.fit()
)

# Section under Chapter 2 (Points to Page 3, Index 2)
section2_1 = writer.add_outline_item(
    title="Section 2.1",
    page_number=0,
    parent=chapter2,
    color=(0, 0.5, 0),
    bold=False,
    italic=True,
    is_open=False,
    fit=Fit.fit_horizontally(top=800)
)

# Section with custom zoom (Points to Page 3, Index 2)
section2_2 = writer.add_outline_item(
    title="Section 2.2",
    page_number=0,
    parent=chapter2,
    color=(1, 0, 0),
    bold=True,
    italic=True,
    is_open=True,
    fit=Fit.xyz(left=0, top=800, zoom=1.25)
)

writer.write("advanced-example.pdf")
```

--------------------------------

### Example: scale and translate a page

Source: https://pypdf.readthedocs.io/en/stable/modules/Transformation.html

Demonstrates creating a Transformation, scaling by (2,3), translating by (10,20), and applying it to a page.

```python
>>> from pypdf import PdfWriter, Transformation
>>> page = PdfWriter().add_blank_page(800, 600)
>>> op = Transformation().scale(sx=2, sy=3).translate(tx=10, ty=20)
>>> page.add_transformation(op)

```

--------------------------------

### Create XMP Metadata

Source: https://pypdf.readthedocs.io/en/stable/user/metadata.html

Demonstrates creating XMP metadata using XmpInformation.create() and attaching it to a PDF writer.

```APIDOC
## Create XMP Metadata

### Description
Creates a new XMP metadata object using XmpInformation.create(), sets metadata fields, and attaches it to a PdfWriter.

### Usage
```python
from pypdf import PdfWriter
from pypdf.xmp import XmpInformation

# Create a new XMP metadata object
xmp = XmpInformation.create()

# Set metadata fields
xmp.dc_title = {"x-default": "My Document Title"}
xmp.dc_creator = ["Author One", "Author Two"]
xmp.dc_description = {"x-default": "Document description"}
xmp.dc_subject = ["keyword1", "keyword2", "keyword3"]
xmp.pdf_producer = "pypdf"

# Create a writer and add the metadata
writer = PdfWriter()
writer.add_blank_page(612, 792)  # Add a page
writer.xmp_metadata = xmp
writer.write("out-xmp-create.pdf")
```
```

--------------------------------

### Install pypdf with pip

Source: https://pypdf.readthedocs.io/en/stable/_sources/user/installation.md.txt

Installs the latest version of pypdf using pip. Requires Python 3.9+.

```bash
pip install pypdf
```

--------------------------------

### Install pypdf with crypto dependencies

Source: https://pypdf.readthedocs.io/en/stable/_sources/user/installation.md.txt

Installs pypdf with extra dependencies for AES encryption/decryption. RC4 encryption is supported without these extras.

```bash
pip install pypdf[crypto]
```

--------------------------------

### Set viewer preferences with pypdf PdfWriter

Source: https://pypdf.readthedocs.io/en/stable/_sources/user/viewer-preferences.md.txt

Creates a PdfWriter, initializes the /ViewerPreferences dictionary with create_viewer_preferences(), and sets various viewer preference properties such as hide_toolbar, hide_menubar, fit_window, non_fullscreen_pagemode, direction, view_area, print_scaling, duplex, and num_copies. The example then adds 40 blank pages and writes the PDF to out.pdf. The /ViewerPreferences dictionary does not exist by default and must be created before setting these properties.

```python
from pypdf import PdfWriter
from pypdf.generic import ArrayObject, NumberObject

writer = PdfWriter()

writer.create_viewer_preferences()

# /HideToolbar
writer.viewer_preferences.hide_toolbar = True
# /HideMenubar
writer.viewer_preferences.hide_menubar = True
# /HideWindowUI
writer.viewer_preferences.hide_windowui = True
# /FitWindow
writer.viewer_preferences.fit_window = True
# /CenterWindow
writer.viewer_preferences.center_window = True
# /DisplayDocTitle
writer.viewer_preferences.display_doctitle = True

# /NonFullScreenPageMode
writer.viewer_preferences.non_fullscreen_pagemode = "/UseNone"  # default
writer.viewer_preferences.non_fullscreen_pagemode = "/UseOutlines"
writer.viewer_preferences.non_fullscreen_pagemode = "/UseThumbs"
writer.viewer_preferences.non_fullscreen_pagemode = "/UseOC"

# /Direction
writer.viewer_preferences.direction = "/L2R"  # default
writer.viewer_preferences.direction = "/R2L"

# /ViewArea
writer.viewer_preferences.view_area = "/CropBox"
# /ViewClip
writer.viewer_preferences.view_clip = "/CropBox"
# /PrintArea
writer.viewer_preferences.print_area = "/CropBox"
# /PrintClip
writer.viewer_preferences.print_clip = "/CropBox"

# /PrintScaling
writer.viewer_preferences.print_scaling = "/None"
writer.viewer_preferences.print_scaling = "/AppDefault"  # default according to PDF spec

# /Duplex
writer.viewer_preferences.duplex = "/Simplex"
writer.viewer_preferences.duplex = "/DuplexFlipShortEdge"
writer.viewer_preferences.duplex = "/DuplexFlipLongEdge"

# /PickTrayByPDFSize
writer.viewer_preferences.pick_tray_by_pdfsize = True
# /PrintPageRange
writer.viewer_preferences.print_pagerange = ArrayObject(
    [NumberObject("1"), NumberObject("10"), NumberObject("20"), NumberObject("30")]
)
# /NumCopies
writer.viewer_preferences.num_copies = 2

for i in range(40):
    writer.add_blank_page(10, 10)

writer.write("out.pdf")
```

--------------------------------

### Update changelog and version with make_release.py

Source: https://pypdf.readthedocs.io/en/stable/dev/releasing.html

Run this command to update CHANGELOG.md and _version.py. It also prepares the release commit message.

```bash
python make_release.py
```

--------------------------------

### PageRange.__init__

Source: https://pypdf.readthedocs.io/en/stable/_modules/pypdf/pagerange.html

Initializes a PageRange object from a slice, another PageRange, or a string expression. The string syntax supports optional start, stop, and step values, with page indices starting at zero.

```APIDOC
## PageRange.__init__

### Description
Initializes a PageRange object from a slice, another PageRange, or a string expression. The string syntax supports optional start, stop, and step values, with page indices starting at zero.

### Method
Constructor

### Signature
`__init__(self, arg: Union[slice, PageRange, str]) -> None`

### Parameters
- **arg** (Union[slice, PageRange, str]) - Required - The initializer: a slice, a PageRange object, or a string like "int", "[int]:[int]", or "[int]:[int]:[int]".

### Raises
- **ParseError** - If the string is not a valid page range expression.

### Examples
- `PageRange(":")` - all pages
- `PageRange("22")` - just the 23rd page
- `PageRange("0:3")` - the first three pages
- `PageRange("::-1")` - all pages in reverse order
```

--------------------------------

### Run Sphinx doctest build locally

Source: https://pypdf.readthedocs.io/en/stable/_sources/dev/documentation.md.txt

Steps to run the Sphinx doctest build locally: install docs requirements, change to the docs directory, and run the doctest build. If successful, the output shows 'Doctest summary' without failures.

```bash
pip install -r requirements/docs.txt
```

```bash
cd docs
```

```bash
make doctest
```

--------------------------------

### Indirect objects example from test_reader.py

Source: https://pypdf.readthedocs.io/en/stable/dev/pdf-format.html

Concrete example of indirect objects in the PDF body, referenced from test_reader.py::test_get_images_raw. Shows the syntax 'counter generation_number << the_object >> endobj' with objects for pages, catalog, and resources.

```plaintext
1 0 obj << /Count 1 /Kids [4 0 R] /Type /Pages >> endobj
2 0 obj << >> endobj
3 0 obj << >> endobj
4 0 obj << /Contents 3 0 R /CropBox [0.0 0.0 2550.0 3508.0]
 /MediaBox [0.0 0.0 2550.0 3508.0] /Parent 1 0 R
 /Resources << /Font << >> >>
 /Rotate 0 /Type /Page >> endobj
5 0 obj << /Pages 1 0 R /Type /Catalog >> endobj

```

--------------------------------

### Add a simple top-level bookmark with PdfWriter.add_outline_item

Source: https://pypdf.readthedocs.io/en/stable/_sources/user/handling-outlines.md.txt

Creates a PdfWriter from an existing PDF and adds a single top-level outline item titled 'Introduction' pointing to page 0. Saves the result to 'simple-example.pdf'.

```python
from pypdf import PdfWriter

writer = PdfWriter(clone_from="crazyones.pdf")

# Add a top-level bookmark
writer.add_outline_item(
    title="Introduction",
    page_number=0
)

writer.write("simple-example.pdf")
```

--------------------------------

### Example xref table

Source: https://pypdf.readthedocs.io/en/stable/_sources/dev/pdf-format.md.txt

Shows the structure of a cross-reference table with a header line and five entries. The first entry is a free object with generation 65535, and the rest are in-use objects with generation 0.

```text
xref 42 5
0000001000 65535 f
0000001234 00000 n
0000001987 00000 n
0000011987 00000 n
0000031987 00000 n
```

--------------------------------

### RectangleObject.height

Source: https://pypdf.readthedocs.io/en/stable/modules/RectangleObject.html

Property to get the height of the rectangle.

```APIDOC
## RectangleObject.height

### Description
Property to get the height of the rectangle.

### Type
float
```

--------------------------------

### RectangleObject.width

Source: https://pypdf.readthedocs.io/en/stable/modules/RectangleObject.html

Property to get the width of the rectangle.

```APIDOC
## RectangleObject.width

### Description
Property to get the width of the rectangle.

### Type
float
```

--------------------------------

### verify_v5 method

Source: https://pypdf.readthedocs.io/en/stable/_modules/pypdf/_encryption.html

Verifies a password for PDF versions >=5. Tries the owner password first, then the user password. Also verifies the Perms entry and logs a warning if it fails.

```python
    def verify_v5(self, password: bytes) -> tuple[bytes, PasswordType]:
        # verify owner password first
        key = AlgV5.verify_owner_password(
            self.R, password, self.values.O, self.values.OE, self.values.U
        )
        rc = PasswordType.OWNER_PASSWORD
        if not key:
            key = AlgV5.verify_user_password(
                self.R, password, self.values.U, self.values.UE
            )
            rc = PasswordType.USER_PASSWORD
        if not key:
            return b"", PasswordType.NOT_DECRYPTED

        # verify Perms
        self._are_permissions_valid = AlgV5.verify_perms(key, self.values.Perms, self.P, self.EncryptMetadata)
        if not self._are_permissions_valid:
            logger_warning("ignore '/Perms' verify failed", source=__name__)
        return key, rc
```

--------------------------------

### PageObject.get_contents()

Source: https://pypdf.readthedocs.io/en/stable/modules/PageObject.html

Method to get the content stream of the page.

```APIDOC
## PageObject.get_contents()

### Description
Returns the content stream of the page.

### Method
`get_contents()`

### Parameters
None.

### Returns
- The content stream object.
```
Tokens:
Raw