pikepdf

https://pikepdf.readthedocs.io/en/latest
Admin
pikepdf is a Python library for creating, manipulating, parsing, repairing, and linearizing PDFs by...
Tokens:48,935
Snippets:685
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install via FreeBSD pkg

Source: https://pikepdf.readthedocs.io/en/latest/installation.html

Standard package installation for FreeBSD.

```bash
pkg install py311-pikepdf
```

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

### Install via APT

Source: https://pikepdf.readthedocs.io/en/latest/installation.html

Command for Debian, Ubuntu, and other APT-based distributions.

```bash
apt install pikepdf
```

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

### Manual install on FreeBSD

Source: https://pikepdf.readthedocs.io/en/latest/installation.html

Manual procedure for installing dependencies and pikepdf on FreeBSD.

```bash
pkg install python3 py311-lxml py311-pip py311-nanobind qpdf
pip install --user pikepdf
```

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

### Install via DNF

Source: https://pikepdf.readthedocs.io/en/latest/installation.html

Command for Fedora systems.

```bash
dnf install python_pikepdf
```

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

### Install via APK

Source: https://pikepdf.readthedocs.io/en/latest/installation.html

Command for Alpine Linux.

```bash
apk add py3-pikepdf
```

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

### Install pikepdf on Windows

Source: https://pikepdf.readthedocs.io/en/latest/source_build.html

Environment configuration and installation steps for pikepdf on Windows.

```powershell
cd $pikepdf
$env:INCLUDE = "$qpdf\include"
$env:LIB = "$qpdf\build\libqpdf\Release\"
cp $LIB\libqpdfXX.dll src\pikepdf  # Help Python loader find libqpdf.dll
uv venv
.venv\scripts\activate
uv pip install -e .
```

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

### Regenerate documentation with Sphinx

Source: https://pikepdf.readthedocs.io/en/latest/source_build.html

Install the required dependencies and execute the make command from the docs directory.

```bash
uv pip install -e .
uv pip install --group docs
cd docs
make html
```

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

### Initialize a PDF object

Source: https://pikepdf.readthedocs.io/en/latest/topics/pages.html

Basic setup for opening a PDF file using the pikepdf library.

```python
>>> from pikepdf import Pdf

>>> pdf = Pdf.open('../tests/resources/fourpages.pdf')
```

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

### Install via pip

Source: https://pikepdf.readthedocs.io/en/latest/installation.html

Standard command to install pikepdf in a Python environment.

```bash
pip install pikepdf
```

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

### Handling missing keys with get()

Source: https://pikepdf.readthedocs.io/en/latest/topics/namepath.html

Using the get() method with NamePath to safely handle missing keys or type mismatches.

```python
>>> pdf = Pdf.new()

>>> # Returns None when path doesn't exist
>>> pdf.Root.get(NamePath.Missing.Path) is None
True

>>> # Returns custom default
>>> pdf.Root.get(NamePath.Missing.Path, "not found")
'not found'
```

```python
>>> # Safe access - returns default if any part of path is missing
>>> font = page.get(NamePath.Resources.Font.F1, None)
>>> if font is not None:
...     # Process the font
```

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

### Build pikepdf against qpdf source on Linux

Source: https://pikepdf.readthedocs.io/en/latest/source_build.html

Commands to compile libqpdf and install pikepdf in a virtual environment.

```bash
# Build libqpdf from source
cd $QPDF_SOURCE_TREE
cmake -S . -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo -DBUILD_SHARED_LIBS=ON
cmake --build build --parallel --target libqpdf
QPDF_BUILD_LIBDIR=$PWD/build/libqpdf

# Create a fresh virtual environment
cd $PIKEPDF_SOURCE_TREE
uv venv
source .venv/bin/activate

# Build pikepdf from source
env QPDF_SOURCE_TREE=$QPDF_SOURCE_TREE QPDF_BUILD_LIBDIR=$QPDF_BUILD_LIBDIR \
    uv pip install -e .
```

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

### Example of a PDF content stream

Source: https://pikepdf.readthedocs.io/en/latest/topics/content_streams.html

A typical content stream sequence demonstrating graphics state management and object drawing.

```text
q                   % 1. Push graphics stack.
100 0 0 100 0 0 cm  % 2. The 6 numbers are the operands, followed by cm operator.
                    %    This configures the current transformation matrix.
/Image1 Do          % 3. Draw the object named /Image1 from the /Resources
                    %    dictionary.
Q                   % 4. Pop graphics stack.
```

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

### Build pikepdf with custom qpdf path

Source: https://pikepdf.readthedocs.io/en/latest/source_build.html

Use environment variables to specify custom include and library paths for qpdf during installation.

```bash
env CXXFLAGS=-I/usr/local/include/libqpdf LDFLAGS=-L/usr/local/lib  \
    uv pip install .
```

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

### Profile pikepdf with py-spy

Source: https://pikepdf.readthedocs.io/en/latest/references/debugging.html

Commands to install profiling tools and record performance data for analysis in speedscope.

```bash
# From a virtual environment with pikepdf installed...

# Install
pip install py-spy
npm install -g speedscope  # may need sudo to install this

# Run profile on a script that executes some pikepdf code we want to profile
py-spy record --native --format speedscope -o profile.speedscope -- python some_script.py

# View results (this will open a browser window)
speedscope profile.speedscope
```

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

### Importing Python classes in C++

Source: https://pikepdf.readthedocs.io/en/latest/references/contributing.html

Example of referencing a Python class within C++ code using nanobind conventions.

```cpp
auto Decimal = py::module_::import_("decimal").attr("Decimal")
```

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

### Registering a font in a PDF

Source: https://pikepdf.readthedocs.io/en/latest/api/canvas.html

Example of adding a registered font to the Resources dictionary of a page or Form XObject.

```python
page.Resources.Font[Name.Arial] = font.register(pdf)
```

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

### Accessing Nested PDF Structures with NamePath

Source: https://pikepdf.readthedocs.io/en/latest/api/main.html

Provides examples for accessing and setting deeply nested dictionary or stream values using NamePath.

```python
# Shorthand syntax - most common
obj[NamePath.Resources.Font.F1]

# With array indices
obj[NamePath.Pages.Kids[0].MediaBox]

# Chained access - supports non Python-identifier names
NamePath['/A']['/B'].C[0]  # equivalent to NamePath.A.B.C[0]

# Alternate syntax to support lists
obj[NamePath(Name.Resources, Name.Font)]

# Using string objects
obj[NamePath('/Resources', '/Weird-Name')]

# Empty path returns the object itself
obj[NamePath()]

# Setting nested values (all parents must exist)
obj[NamePath.Root.Info.Title] = pikepdf.String("Test")

# With default value
obj.get(NamePath.Root.Metadata, None)
```

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

### Initialize and run a qpdf Job

Source: https://pikepdf.readthedocs.io/en/latest/api/main.html

Creates a Job instance using command-line arguments and executes it.

```python
job = Job([‘pikepdf’, ‘–check’, ‘input.pdf’]) job.run()
```

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

### Configure Windows build environment

Source: https://pikepdf.readthedocs.io/en/latest/source_build.html

Set up the Visual Studio 2015 environment variables before building the extension.

```batch
%VS140COMNTOOLS%\..\..\VC\vcvarsall.bat" x64
set DISTUTILS_USE_SDK=1
set MSSdk=1
```

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

### Build qpdf from source on Windows

Source: https://pikepdf.readthedocs.io/en/latest/source_build.html

Commands to configure and build qpdf using CMake.

```powershell
cd $qpdf
cmake -S . -B build
cmake --build build --config Release
```

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

### Constructing PDF Name Objects

Source: https://pikepdf.readthedocs.io/en/latest/api/main.html

Demonstrates the two equivalent notations for creating PDF Name objects.

```python
Name.Resources
Name('/Resources')
```

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

### Create and insert a new NumberTree

Source: https://pikepdf.readthedocs.io/en/latest/api/models.html

Shows how to instantiate a new NumberTree and attach it to the PDF root catalog.

```python
nt = NumberTree.new(pdf)
pdf.Root.PageLabels = nt.obj
```

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

### Create and insert a new NameTree

Source: https://pikepdf.readthedocs.io/en/latest/api/models.html

Demonstrates how to initialize a new NameTree and assign it to the PDF catalog's destination structure.

```python
nt = NameTree.new(pdf)
pdf.Root.Names.Dests = nt.obj
```

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

### Create a new PDF

Source: https://pikepdf.readthedocs.io/en/latest/tutorial.html

Initializes a new PDF document and adds a blank page before saving.

```python
from pikepdf import Pdf

pdf = Pdf.new()
pdf.add_blank_page()
pdf.save('blank_page.pdf')
```

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

### Build pikepdf against local qpdf source

Source: https://pikepdf.readthedocs.io/en/latest/references/debugging.html

Environment variables and build command to link pikepdf._core against a local qpdf build.

```bash
env QPDF_SOURCE_TREE=<location of qpdf> \
  QPDF_BUILD_LIBDIR=<directory containing libqpdf.so> \
  python setup.py build_ext --inplace
```

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

### Enable qpdf tracing

Source: https://pikepdf.readthedocs.io/en/latest/references/debugging.html

Set environment variables to log libqpdf debug messages to a file.

```bash
env TC_SCOPE=qpdf TC_FILENAME=libqpdf_log.txt python my_pikepdf_script.py
```

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

### Generate form appearances using default settings

Source: https://pikepdf.readthedocs.io/en/latest/api/form.html

Demonstrates the standard approach to generating appearance streams for a PDF form.

```python
form = Form(pdf, generate_appearances = None)
...
pdf.generate_appearances()
```

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

### Configure and apply Sanitizer to multiple files

Source: https://pikepdf.readthedocs.io/en/latest/api/sanitize.html

Demonstrates creating a reusable Sanitizer instance to remove JavaScript, external access, and attachments from a list of PDF files.

```python
scrubber = (
    pikepdf.sanitize.Sanitizer()
    .remove_javascript()
    .remove_external_access()
    .remove_attachments()
)
for path in untrusted_paths:
    with pikepdf.open(path) as pdf:
        scrubber.apply(pdf).save(out_dir / path.name)
```

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

### Attaching a file from the filesystem

Source: https://pikepdf.readthedocs.io/en/latest/api/models.html

Create a file specification from a local file path and add it to the PDF attachments mapping.

```python
pdf = Pdf.open(...)

fs = AttachedFileSpec.from_filepath(pdf, Path('somewhere/spreadsheet.xlsx'))

pdf.attachments['spreadsheet.xlsx'] = fs
```

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

### Handle missing keys with NamePath

Source: https://pikepdf.readthedocs.io/en/latest/topics/namepath.html

Demonstrates how NamePath provides contextual error messages when a key traversal fails.

```python
>>> pdf = Pdf.new()
>>> pdf.Root.A = Dictionary(B=Dictionary())

>>> pdf.Root[NamePath.A.B.C]
Traceback (most recent call last):
    ...
KeyError: 'Key /C not found; traversed NamePath.A.B'
```

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

### Accessing PDF images with PdfImage

Source: https://pikepdf.readthedocs.io/en/latest/topics/images.html

Demonstrates opening a PDF, retrieving image objects from a page, and initializing a PdfImage helper.

```python
>>> from pikepdf import Pdf, PdfImage, Name

>>> example = Pdf.open('../tests/resources/congress.pdf')

>>> page1 = example.pages[0]

>>> list(page1.get_images().keys())
['/Im0']

>>> rawimage = page1.get_images()['/Im0']  # The raw object/dictionary

>>> pdfimage = PdfImage(rawimage)

>>> type(pdfimage)
<class 'pikepdf.models.image.PdfImage'>
```

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

### Accessing PDF Name Trees

Source: https://pikepdf.readthedocs.io/en/latest/topics/nametrees.html

Demonstrates opening a PDF and accessing the Dests name tree using the NameTree class.

```python
>>> from pikepdf import Pdf, Page, NameTree

>>> pdf = Pdf.open('../tests/resources/outlines.pdf')

>>> nt = NameTree(pdf.Root.Names.Dests)

>>> print([k for k in nt.keys()])
['0', '1', '2', '3', '4', '5', '6', '7', '8']

>>> nt['2'][0].objgen, nt['2'][1], nt['2'][2]
((3, 0), pikepdf.Name("/XYZ"), Decimal('89.29'))
```

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

### Download qpdf external libraries on Windows

Source: https://pikepdf.readthedocs.io/en/latest/source_build.html

PowerShell commands to download and extract qpdf external dependencies.

```powershell
wget https://github.com/qpdf/external-libs/releases/download/release-$version/qpdf-external-libs-bin.zip -Outfile libs.zip
expand-archive -path libs.zip -destinationpath .
```

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

### Extracting images with and without decoding

Source: https://pikepdf.readthedocs.io/en/latest/topics/images.html

Demonstrates how to extract images using the default decoding behavior versus retrieving raw stored samples.

```python
>>> raw = pdfimage.as_pil_image(apply_decode_array=False)  # stored samples, /Decode ignored

>>> shown = pdfimage.as_pil_image()  # default: matches a PDF viewer
```

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

### Open a PDF and count pages

Source: https://pikepdf.readthedocs.io/en/latest/tutorial.html

Initialize a PDF object from a file path and determine the total page count using the standard length function.

```python
>>> from pikepdf import Pdf

>>> pdf = Pdf.open('../tests/resources/fourpages.pdf')
```

```python
>>> len(pdf.pages)
4
```

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

### Compare manual traversal with NamePath

Source: https://pikepdf.readthedocs.io/en/latest/topics/namepath.html

Compares verbose manual dictionary/attribute access with the concise NamePath syntax.

```python
# Verbose and error-prone
try:
    font = page.Resources.Font.F1
except (KeyError, AttributeError):
    font = None

# Or with multiple get() calls
resources = page.get(Name.Resources)
if resources:
    font_dict = resources.get(Name.Font)
    if font_dict:
        font = font_dict.get('/F1')
```

```python
# Concise and safe
font = page.get(NamePath.Resources.Font.F1)
```

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

### Construct a GoToAction

Source: https://pikepdf.readthedocs.io/en/latest/topics/outlines.html

Create a typed GoToAction and resolve its destination page.

```python
>>> from pikepdf import GoToAction

>>> action = GoToAction(Dictionary(S=Name.GoTo, D=[pdf.pages[0].obj, Name.Fit]))
>>> action.resolve_destination(pdf).page
```

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

### Add a resource to a page

Source: https://pikepdf.readthedocs.io/en/latest/api/models.html

Demonstrates creating a new page and adding a Form XObject resource to its Resources dictionary.

```python
>>> pdf = pikepdf.Pdf.new()
>>> pdf.add_blank_page(page_size=(100, 100))
<pikepdf.Page({
  "/Contents": pikepdf.Stream(owner=<...>, data=<...>, {

  }),
  "/MediaBox": [ 0, 0, 100, 100 ],
  "/Parent": <reference to /Pages>,
  "/Resources": {

  },
  "/Type": "/Page"
})>
>>> formxobj = pikepdf.Dictionary(
...     Type=Name.XObject,
...     Subtype=Name.Form
... )
>>> resource_name = pdf.pages[0].add_resource(formxobj, Name.XObject)
```

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

### Set library paths for local qpdf

Source: https://pikepdf.readthedocs.io/en/latest/references/debugging.html

Commands to force the operating system to load the locally compiled qpdf library instead of the system version.

```bash
# Linux
env LD_LIBRARY_PATH=<directory containing libqpdf.so> python ...
```

```bash
# macOS - may require disabling System Integrity Protection
env DYLD_LIBRARY_PATH=<directory containing libqpdf.so> python ...
```

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

### NamePath construction styles

Source: https://pikepdf.readthedocs.io/en/latest/topics/namepath.html

Various ways to construct a NamePath, including shorthand, array indexing, canonical syntax, and chaining.

```python
>>> # Shorthand syntax (most common)
>>> path = NamePath.Resources.Font.F1
>>> repr(path)
'NamePath.Resources.Font.F1'

>>> # With array indices
>>> path = NamePath.Pages.Kids[0].MediaBox
>>> repr(path)
'NamePath.Pages.Kids[0].MediaBox'

>>> # Canonical syntax (for non-Python-identifier names)
>>> path = NamePath('/Resources', '/Weird-Name')
>>> repr(path)
'NamePath.Resources.Weird-Name'

>>> # Using Name objects
>>> path = NamePath(Name.Resources, Name.Font)
>>> repr(path)
'NamePath.Resources.Font'

>>> # Chained construction
>>> path = NamePath('/A')('/B').C[0]
>>> repr(path)
'NamePath.A.B.C[0]'
```

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

### Set an outline item action

Source: https://pikepdf.readthedocs.io/en/latest/topics/outlines.html

Assign a raw action dictionary to an outline item and access its parsed URI.

```python
>>> from pikepdf import Dictionary, Name

>>> with pdf.open_outline() as outline:
...     item = outline.root[0]
...     item.action = Dictionary(S=Name.URI, URI='https://example.com')
...     item.parsed_action.uri
'https://example.com'
```

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

### Update library path on macOS

Source: https://pikepdf.readthedocs.io/en/latest/references/debugging.html

Use install_name_tool to make the local qpdf library path persistent in the pikepdf binary extension.

```bash
install_name_tool -change /usr/local/lib/libqpdf*.dylib \
    $QPDF_BUILD_LIBDIR/libqpdf*.dylib \
    src/pikepdf/_core.cpython*.so
```

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

### Initialize Form with Appearance Generator

Source: https://pikepdf.readthedocs.io/en/latest/topics/interactive_forms.html

Pass an appearance stream generator class to the Form constructor to handle field appearance generation.

```python
>>> from pikepdf.form import Form, DefaultAppearanceStreamGenerator

>>> form = Form(pdf, DefaultAppearanceStreamGenerator)
```

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

### compress

Source: https://pikepdf.readthedocs.io/en/latest/api/main.html

Configure stream and object-stream compression.

```APIDOC
## compress(*, compress_streams=None, object_streams=None, recompress_flate=False, compression_level=None, decode_level=None, stream_data=None)

### Description
Configure stream and object-stream compression.

### Parameters
- **compress_streams** (bool | None) - Optional - Compress uncompressed streams.
- **object_streams** (Literal['generate', 'preserve', 'disable'] | None) - Optional - Control use of object streams.
- **recompress_flate** (bool) - Optional - Uncompress and recompress flate streams.
- **compression_level** (int | None) - Optional - Flate compression level (1-9).
- **decode_level** (Literal['none', 'generalized', 'specialized', 'all'] | None) - Optional - Which streams to uncompress before recompressing.
- **stream_data** (Literal['compress', 'preserve', 'uncompress'] | None) - Optional - Legacy combined stream compression control.
```

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

### Compile a debug build of qpdf

Source: https://pikepdf.readthedocs.io/en/latest/references/debugging.html

Commands to configure and build qpdf from source with debug symbols enabled.

```bash
# in qpdf source tree
cd $QPDF_SOURCE_TREE
cmake -S . -B build -DENABLE_QTC=ON -DCMAKE_BUILD_TYPE=Debug
cmake --build build -j
```

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

### Open and save a PDF

Source: https://pikepdf.readthedocs.io/en/latest/tutorial.html

Uses the Pdf.open context manager to load a file and save it to a new location.

```python
from pikepdf import Pdf

with Pdf.open('sample.pdf') as pdf:
    pdf.save('output.pdf')
```

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

### Accessing a page trim box

Source: https://pikepdf.readthedocs.io/en/latest/topics/page.html

Demonstrates retrieving the trim box of a page, which resolves to the media box if not explicitly defined.

```python
>>> page1.trimbox
pikepdf.Array([ 0, 0, 200, 304 ])
```

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

### Open a PDF file

Source: https://pikepdf.readthedocs.io/en/latest/api/main.html

Use a context manager to ensure the PDF file is properly closed after processing.

```python
>>> with Pdf.open("test.pdf") as pdf:
...     pass
```

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

### check_pdf_syntax(progress=None)

Source: https://pikepdf.readthedocs.io/en/latest/api/main.html

Checks if a PDF is syntactically well-formed, similar to qpdf --check. It returns a list of strings describing any issues found.

```APIDOC
## check_pdf_syntax(progress=None)

### Description
Checks if the PDF is syntactically well-formed and identifies structural problems. This function attempts to decompress all streams and reports issues as a list of strings.

### Parameters
- **progress** (collections.abc.Callable[[int], None] | None) - Optional - A function to call with progress updates from 0 to 100.

### Returns
- **list[str]** - A list of strings describing issues found, or an empty list if no issues exist.
```

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

### ContentStreamBuilder.begin_text

Source: https://pikepdf.readthedocs.io/en/latest/api/canvas.html

Initiates a text object within the content stream.

```APIDOC
## ContentStreamBuilder.begin_text()

### Description
Begin text object. All text operations must be contained within a text object, and are invalid otherwise. The text matrix and font are reset for each text object.
```

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

### build

Source: https://pikepdf.readthedocs.io/en/latest/api/main.html

Construct a pikepdf.Job from the specification.

```APIDOC
## build()

### Description
Construct a pikepdf.Job from the specification. The job is validated by qpdf during construction but not executed.
```

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

### Accessing a PDF page dictionary

Source: https://pikepdf.readthedocs.io/en/latest/tutorial.html

Demonstrates opening a PDF and accessing the underlying dictionary of the first page.

```python
>>> from pikepdf import Pdf

>>> example = Pdf.open('../tests/resources/congress.pdf')

>>> page1 = example.pages[0]

>>> obj_page1 = page1.obj

>>> obj_page1
<pikepdf.Dictionary(Type="/Page")({
  "/Contents": pikepdf.Stream(owner=<...>, data=b'q\n200.0000 0 0 304.0'..., {
    "/Length": 50
  }),
  "/MediaBox": [ 0, 0, 200, 304 ],
  "/Parent": <reference to /Pages>,
  "/Resources": {
    "/XObject": {
      "/Im0": pikepdf.Stream(owner=<...>, data=<...>, {
        "/BitsPerComponent": 8,
        "/ColorSpace": "/DeviceRGB",
        "/Filter": [ "/DCTDecode" ],
        "/Length": 192956,
        "/Subtype": "/XObject",
        "/Type": "/XObject",
        "/Width": 1000
      })
    }
  },
  "/Type": "/Page"
})>
```

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

### Attach a file to a PDF

Source: https://pikepdf.readthedocs.io/en/latest/topics/attachments.html

Demonstrates how to open a PDF and attach an external file using AttachedFileSpec.

```python
>>> from pikepdf import Pdf, AttachedFileSpec, Name, Dictionary, Array

>>> from pathlib import Path

>>> pdf = Pdf.open('../tests/resources/fourpages.pdf')

>>> filespec = AttachedFileSpec.from_filepath(pdf, Path('../README.md'))

>>> pdf.attachments['README.md'] = filespec

>>> pdf.attachments
<pikepdf._core.Attachments: ['README.md']>
```

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

### pikepdf.Job

Source: https://pikepdf.readthedocs.io/en/latest/api/main.html

The Job class provides an interface to execute qpdf commands. Users can initialize a job with arguments and execute it using the run() method.

```APIDOC
## class pikepdf.Job(json: str)

### Description
Provides access to the qpdf job interface. All functionality of the qpdf command line program is available through this class.

### Methods

#### __init__(json: str) -> None
Creates a Job from command line arguments. The first item should be the program name.

#### run() -> None
Executes the job.

#### check_configuration() -> None
Checks if the configuration is valid; raises an exception if not.

#### property exit_code: int
Returns the integer exit code after run() is called.

#### property has_warnings: bool
Returns True if there were warnings after execution.

### Example
```python
job = pikepdf.Job(['pikepdf', '--check', 'input.pdf'])
job.run()
```
```

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

### Convert an image to PDF for stamping

Source: https://pikepdf.readthedocs.io/en/latest/topics/interactive_forms.html

Convert a non-PDF image to a PDF stream using Pillow before applying it as an overlay.

```python
>>> from PIL import Image

>>> img = Image.open(img).convert('RGB')

>>> img_as_pdf = BytesIO()

>>> img.save(img_as_pdf, 'pdf')

>>> img_as_pdf.seek(0)

>>> sig_pdf = Pdf.open(img_as_pdf)
```

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

### Configure libqpdf crypto provider

Source: https://pikepdf.readthedocs.io/en/latest/references/build_process.html

Explicitly set the crypto provider for libqpdf during the CMake configuration process to ensure deterministic builds.

```bash
cmake -DREQUIRE_CRYPTO_NATIVE=1 -DUSE_IMPLICIT_CRYPTO=OFF ...
```

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

### Create PDF Outlines

Source: https://pikepdf.readthedocs.io/en/latest/topics/outlines.html

Adds outline entries to an existing PDF by specifying page indices.

```python
>>> from pikepdf import Pdf, OutlineItem

>>> pdf = Pdf.open('document.pdf')

>>> with pdf.open_outline() as outline:
...     outline.root.extend([
...         # Page counts are zero-based
...         OutlineItem('Section One', 0),
...         OutlineItem('Section Two', 2),
...         OutlineItem('Section Three', 8)
...     ])

>>> pdf.save('document_with_outline.pdf')
```

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

### Configure PDF compression and image optimization

Source: https://pikepdf.readthedocs.io/en/latest/topics/jobs.html

Use JobBuilder to compress object streams and optimize images within a PDF file.

```python
JobBuilder().input('in.pdf').output('out.pdf') \
    .compress(object_streams='generate', recompress_flate=True) \
    .optimize_images(min_width=100, jpeg_quality=85) \
    .run()
```

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

### load(name, resource_dict)

Source: https://pikepdf.readthedocs.io/en/latest/api/canvas.html

Loads a font from the specified resource dictionary.

```APIDOC
## load(name, resource_dict)

### Description
Load a font from the specified resource dictionary.

### Parameters
- **name** (pikepdf.objects.Name) - Required - The name of the font.
- **resource_dict** (pikepdf.objects.Dictionary) - Required - The resource dictionary containing the font.

### Return
- **SimpleFont** - The loaded font object.
```

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

### Pdf.open(filename_or_stream, ...)

Source: https://pikepdf.readthedocs.io/en/latest/api/main.html

Opens an existing PDF file or stream for reading and manipulation.

```APIDOC
## Pdf.open(filename_or_stream, ...)

### Description
Opens an existing PDF file or stream. The file should not be modified by another process while open unless allow_overwriting_input is set to True.

### Parameters
- **filename_or_stream** (pathlib.Path | str | BinaryIO) - Required - Filename or Python readable and seekable file stream of PDF to open.
- **password** (str | bytes) - Optional - User or owner password to open an encrypted PDF.
- **hex_password** (bool) - Optional - If True, interpret the password as a hex-encoded version of the exact encryption key.
- **ignore_xref_streams** (bool) - Optional - If True, ignore cross-reference streams.
- **suppress_warnings** (bool) - Optional - If True (default), warnings are not printed to stderr.
- **attempt_recovery** (bool) - Optional - If True (default), attempt to recover from PDF parsing errors.
- **inherit_page_attributes** (bool) - Optional - If True (default), push attributes from the /Pages tree down onto each individual page.
- **access_mode** (AccessMode) - Optional - Determines how to access the file (default, mmap, or mmap_only).
- **allow_overwriting_input** (bool) - Optional - If True, allows calling .save() to overwrite the input file.

### Exceptions
- **pikepdf.PasswordError** - If the password failed to open the file.
- **pikepdf.PdfError** - If for other reasons the file could not be opened.
- **TypeError** - If the type of filename_or_stream is not usable.
- **FileNotFoundError** - If the file was not found.
```

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

### Extract image to stream or file

Source: https://pikepdf.readthedocs.io/en/latest/api/models.html

Demonstrates extracting image data to a memory stream or a file path with a prefix.

```python
>>> im.extract_to(stream=bytes_io)
'.png'
```

```python
>>> im.extract_to(fileprefix='/tmp/image00')
'/tmp/image00.jpg'
```

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

### Inspect a PDF page object

Source: https://pikepdf.readthedocs.io/en/latest/topics/page.html

Demonstrates opening a PDF and accessing the first page to view its internal dictionary structure, including contents and resources.

```python
>>> from pikepdf import Pdf, Page

>>> example = Pdf.open('../tests/resources/congress.pdf')

>>> page1 = example.pages[0]

>>> page1
<pikepdf.Page({
  "/Contents": pikepdf.Stream(owner=<...>, data=b'q\n200.0000 0 0 304.0'..., {
    "/Length": 50
  }),
  "/MediaBox": [ 0, 0, 200, 304 ],
  "/Parent": <reference to /Pages>,
  "/Resources": {
    "/XObject": {
      "/Im0": pikepdf.Stream(owner=<...>, data=<...>, {
        "/BitsPerComponent": 8,
        "/ColorSpace": "/DeviceRGB",
        "/Filter": [ "/DCTDecode" ],
        "/Height": 1520,
        "/Length": 192956,
        "/Subtype": "/Image",
        "/Type": "/XObject",
        "/Width": 1000
      })
    }
  },
  "/Type": "/Page"
})>
```

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

### pikepdf.unparse_content_stream(instructions)

Source: https://pikepdf.readthedocs.io/en/latest/api/filters.html

Converts a collection of instructions back into bytes suitable for storing in a PDF.

```APIDOC
## pikepdf.unparse_content_stream(instructions)

### Description
Converts a collection of instructions (as returned by parse_content_stream) into binary format suitable for embedding in a PDF.

### Parameters
- **instructions** (collections.abc.Collection) - Required - A collection of instructions to be converted.

### Returns
- **bytes** - A binary content stream.
```

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

### add_overlay

Source: https://pikepdf.readthedocs.io/en/latest/api/main.html

Overlay pages from another file on top of the output pages.

```APIDOC
## add_overlay(file, *, to=None, from_=None, repeat=None, password=None)

### Description
Overlay pages from another file on top of the output pages.

### Parameters
- **file** (Any) - Required - Source PDF for the overlay.
- **to** (str | None) - Optional - Destination page range in the output.
- **from_** (str | None) - Optional - Source page range in file.
- **repeat** (str | None) - Optional - Source pages to repeat across remaining destination pages.
- **password** (str | None) - Optional - Password for an encrypted source file.
```

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

### Execute qpdf jobs

Source: https://pikepdf.readthedocs.io/en/latest/tutorial.html

Runs qpdf functionality through the Job interface using command-line arguments or JSON configuration.

```python
>>> from pikepdf import Job

>>> Job(['pikepdf', '--check', '../tests/resources/fourpages.pdf'])
```

```python
>>> job_json = {'inputFile': '../tests/resources/fourpages.pdf', 'check': ''}

>>> Job(job_json).run()
```

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

### Accessing dictionary keys with attribute and item notation

Source: https://pikepdf.readthedocs.io/en/latest/tutorial.html

Demonstrates the preferred attribute notation for standard PDF names versus item notation for dictionary-style access.

```python
>>> page1.Type      # preferred notation for standard PDF names
pikepdf.Name("/Page")

>>> page1['/Type']  # also works
pikepdf.Name("/Page")
```

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

### Copy pages with form fields

Source: https://pikepdf.readthedocs.io/en/latest/topics/interactive_forms.html

Use add_pages_from to ensure form fields and widget annotations are correctly migrated between documents.

```python
from pikepdf import Pdf

dest = Pdf.new()
with Pdf.open('a.pdf') as a, Pdf.open('b.pdf') as b:
    result = dest.add_pages_from(a)
    result = dest.add_pages_from(b)
    print(result.renamed_fields)  # fields auto-renamed to avoid collisions
dest.save('merged.pdf')
```

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

### Execute qpdf command directly

Source: https://pikepdf.readthedocs.io/en/latest/topics/jobs.html

Pass an argv list to pikepdf.Job to execute qpdf commands in-process without shelling out to a binary.

```python
from pikepdf import Job

Job(['pikepdf', '--linearize', 'in.pdf', 'out.pdf']).run()
```

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

### Enumerate images on a page

Source: https://pikepdf.readthedocs.io/en/latest/topics/images.html

Use get_images() to retrieve a mapping of resource names to image objects on a specific page.

```python
>>> page = pdf.pages[0]

>>> images = page.get_images()  # {'/Im0': <stream>, ...}
```

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

### input

Source: https://pikepdf.readthedocs.io/en/latest/api/main.html

Sets the input file for the PDF processing job.

```APIDOC
## input(file, *, password=None)

### Description
Set the input file, optionally with a password.

### Parameters
- **file** (Any) - Required - Path to the input PDF.
- **password** (str | None) - Optional - Password for an encrypted input file.
```

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

### Merge PDFs with version handling and resource cleanup

Source: https://pikepdf.readthedocs.io/en/latest/topics/pages.html

A robust approach to merging PDFs that accounts for PDF version compatibility and removes unreferenced resources.

```python
>>> from glob import glob

>>> pdf = Pdf.new()

>>> version = pdf.pdf_version

>>> for file in glob('*.pdf'):
...     src = Pdf.open(file)
...     version = max(version, src.pdf_version)
...     pdf.pages.extend(src.pages)

>>> pdf.remove_unreferenced_resources()

>>> pdf.save('merged.pdf', min_version=version)
```

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

### Inspecting form fields

Source: https://pikepdf.readthedocs.io/en/latest/topics/interactive_forms.html

Access specific fields by name and retrieve their properties.

```python
>>> field = form['MyField']

>>> field.fully_qualified_name
"MyField"

>>> field.alternate_name
"Applicant's first given name"

>>> field.is_text
True

>>> field.is_required
False
```

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

### Parse a PDF content stream

Source: https://pikepdf.readthedocs.io/en/latest/api/filters.html

Iterate through instructions in a page's content stream to extract operators.

```python
>>> with pikepdf.Pdf.open("../tests/resources/pal-1bit-trivial.pdf") as pdf:
...     page = pdf.pages[0]
...     for operands, command in pikepdf.parse_content_stream(page):
...         print(command)
q
cm
Do
Q
```

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

### Accessing arbitrary dictionary keys

Source: https://pikepdf.readthedocs.io/en/latest/tutorial.html

Shows how to access keys that are arbitrarily named by the PDF generator using item notation.

```python
>>> page1.Resources.XObject['/Im0']
```

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

### Extracting images to files

Source: https://pikepdf.readthedocs.io/en/latest/topics/images.html

Saves an image to the filesystem using a specified prefix, automatically determining the file extension.

```python
>>> pdfimage.extract_to(fileprefix='image')
'image.jpg'
```

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

### open_outline

Source: https://pikepdf.readthedocs.io/en/latest/api/main.html

Opens the PDF outline (bookmarks) for editing. Recommended for use in a 'with' block where changes are committed upon exit.

```APIDOC
## open_outline(max_depth=15, strict=False)

### Description
Opens the PDF outline for editing. Changes are committed to the PDF when the 'with' block exits.

### Parameters
- **max_depth** (int) - Optional - Maximum recursion depth of the outline to be imported. Default is 15.
- **strict** (bool) - Optional - If True, raises OutlineStructureError on structural problems.
```

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

### Add attachments and overlays to a PDF

Source: https://pikepdf.readthedocs.io/en/latest/topics/jobs.html

Add multiple attachments and overlays to a PDF document using repeatable methods.

```python
JobBuilder().input('report.pdf').output('out.pdf') \
    .add_attachment('data.csv', mimetype='text/csv') \
    .add_overlay('watermark.pdf', repeat='1') \
    .run()
```

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

### Configure Outline Destinations

Source: https://pikepdf.readthedocs.io/en/latest/topics/outlines.html

Defines specific page locations and fit types for outline navigation.

```python
>>> oi = OutlineItem('First', 0, 'FitB', top=1000)
```

```python
>>> oi.destination = make_page_destination(pdf, 0, 'FitB', top=1000)
```

```python
>>> with pdf.open_outline() as outline:
...     dest = outline.root[0].resolved_destination(pdf)
...     dest.page, dest.fit_type, dest.left, dest.top
```

```python
>>> from pikepdf import Destination, PageLocation

>>> oi = OutlineItem('First', Destination(pdf.pages[0].obj, PageLocation.FitB, top=1000))
```

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

### Using NamePath for nested access

Source: https://pikepdf.readthedocs.io/en/latest/topics/namepath.html

Initializes a NamePath to access a nested font resource within a PDF dictionary.

```python
>>> from pikepdf import Pdf, Dictionary, Array, Name, NamePath

>>> pdf = Pdf.new()
>>> pdf.Root.Resources = Dictionary(
...     Font=Dictionary(F1=Name.Helvetica),
...     XObject=Dictionary()
... )

>>> # Access nested value with NamePath
>>> pdf.Root[NamePath.Resources.Font.F1]
pikepdf.Name("/Helvetica")
```
Tokens:
Raw