Exceptions

Every exception pikepdf raises on its own behalf derives from pikepdf.PikepdfError, and every warning it issues derives from pikepdf.PikepdfWarning.

PikepdfError
├── PdfError                              the document is defective
│   ├── DataDecodingError                 a stream will not decode
│   ├── PdfParsingError                   a content stream will not parse
│   └── ReferenceCycleError
├── PasswordError                         the document is fine; the password is not
├── DependencyError                       a third-party tool is missing
├── OutlineStructureError
├── ForeignObjectError                    ┐
├── DeletedObjectError                    ├ the caller misused the API
├── JobUsageError                         ┘
├── UnsupportedImageTypeError
├── InvalidPdfImageError
├── ImageDecompressionError
├── NotExtractableError
│   └── HifiPrintImageNotTranscodableError
└── DecompressionBombError                (also a PIL.Image.DecompressionBombError)

PikepdfWarning
├── PageCopyWarning
├── XmpTypeWarning                        an XMP value has the wrong type
└── DecompressionBombWarning              (also a PIL.Image.DecompressionBombWarning)

To handle a damaged or unreadable document, catch pikepdf.PdfError: it covers both malformed file structure and streams that will not decode. pikepdf.PasswordError is deliberately not a PdfError, so that code which reports “wrong password” separately from “broken file” can order

try:
    ...
except pikepdf.PdfError:
    ...      # the file is damaged
except pikepdf.PasswordError:
    ...      # the file is fine, we need a password

without the first handler swallowing the second.

Note

except PikepdfError does not catch everything that can escape a pikepdf call. pikepdf raises the ordinary built-in exceptions where they are the natural choice — ValueError, TypeError, KeyError, IndexError and NotImplementedError for invalid arguments or unsupported input, and the OSError family (including FileNotFoundError) for file access. Image extraction may also raise exceptions from Pillow. PikepdfError means “pikepdf-specific error”, not “any error from pikepdf”.

Roots

exception pikepdf.exceptions.PikepdfError

Root of the pikepdf exception hierarchy.

Every exception pikepdf raises on its own behalf derives from this, so except PikepdfError catches all of them. It does not catch the built-in exceptions pikepdf raises for ordinary programming errors (ValueError, TypeError, KeyError, NotImplementedError), the OSError family raised by file access, or exceptions raised by Pillow during image extraction.

Added in version 10.13.

exception pikepdf.exceptions.PikepdfWarning

Root of the pikepdf warning hierarchy.

Every warning pikepdf issues on its own behalf derives from this, so warnings.simplefilter('error', PikepdfWarning) turns all of them into exceptions. See pikepdf.PikepdfError for the exception side.

Document errors

exception pikepdf.exceptions.PdfError

General pikepdf-specific exception.

Raised when a document is defective in some way. See also its subclasses DataDecodingError and ReferenceCycleError.

exception pikepdf.exceptions.DataDecodingError

Exception thrown when a stream object in a PDF cannot be decoded.

Changed in version 10.13: Now derives from PdfError, so except PdfError around Object.read_bytes() also catches undecodable streams. Previously it was a sibling of PdfError.

exception pikepdf.exceptions.PdfParsingError(message=None, line=None)

Error when parsing a PDF content stream.

Changed in version 10.13: Now derives from pikepdf.PdfError, since a content stream that will not parse is a defect in the document.

exception pikepdf.exceptions.ReferenceCycleError

When a direct (non-indirect) object would be made to contain itself.

A direct object may not contain itself, directly or indirectly. Make one of the objects indirect with Pdf.make_indirect() to create a reference cycle.

Added in version 10.8.

exception pikepdf.exceptions.OutlineStructureError

Indicates an error in the outline data structure.

Encryption

exception pikepdf.exceptions.PasswordError

Exception thrown when the supplied password is incorrect.

Deliberately not a PdfError: a wrong password does not mean the document is defective. Handlers that distinguish the two can order except PdfError before except PasswordError safely.

API misuse

exception pikepdf.exceptions.ForeignObjectError

When a complex object is copied into a foreign PDF without proper methods.

Use Pdf.copy_foreign().

exception pikepdf.exceptions.DeletedObjectError

When a required object is accessed after deletion.

Thrown when accessing a Object that relies on a Pdf that was deleted using the Python delete statement or collected by the Python garbage collector. To resolve this error, you must retain a reference to the Pdf for the whole time you may be accessing it.

Added in version 7.0.

exception pikepdf.exceptions.JobUsageError

Exception thrown when the pikepdf.Job interface is used incorrectly.

Environment

exception pikepdf.exceptions.DependencyError

A third party dependency is needed to extract streams of this type.

Image errors

exception pikepdf.exceptions.UnsupportedImageTypeError

This image is formatted in a way pikepdf does not supported.

exception pikepdf.exceptions.InvalidPdfImageError

This image is not valid according to the PDF 1.7 specification.

exception pikepdf.exceptions.ImageDecompressionError

Image decompression error.

exception pikepdf.exceptions.NotExtractableError

Indicates that an image cannot be directly extracted.

exception pikepdf.exceptions.HifiPrintImageNotTranscodableError

Image contains high fidelity printing information and cannot be extracted.

exception pikepdf.DecompressionBombError

Bases: pikepdf.PikepdfError, PIL.Image.DecompressionBombError

Raised by image extraction when an image’s pixel count exceeds twice pikepdf.PdfImage.MAX_IMAGE_PIXELS, indicating a possible decompression-bomb (memory exhaustion) attack. Subclasses Pillow’s exception of the same name, so handlers written for Pillow also catch it.

This class is created lazily on first access so that importing pikepdf does not import Pillow.

Warnings

exception pikepdf.exceptions.PageCopyWarning

Form fields or named destinations may be lost when copying pages.

Emitted when copying pages between documents (e.g. pages.extend()) in a way that drops or orphans AcroForm form fields or fails to carry named destinations referenced by the copied pages. Use pikepdf.Pdf.add_pages_from() to preserve them.

exception pikepdf.exceptions.XmpTypeWarning

A value assigned to an XMP property does not match the property’s type.

The XMP specification defines the type of each standard property. A value of the wrong type produces metadata that other software may silently discard - for example a language alternative where an unordered list of contributors is required. pikepdf converts the value to the type the specification requires and warns; open metadata with Pdf.open_metadata(strict=True) to raise TypeError instead.

exception pikepdf.DecompressionBombWarning

Bases: pikepdf.PikepdfWarning, PIL.Image.DecompressionBombWarning

Emitted by image extraction when an image’s pixel count exceeds pikepdf.PdfImage.MAX_IMAGE_PIXELS (but is not large enough to raise pikepdf.DecompressionBombError). Subclasses Pillow’s warning of the same name.