pdftools_toolbox.pdf.document

Classes

Document(handle)

A class representing a PDF document.
class pdftools_toolbox.pdf.document.Document(handle)[source]

Bases: _NativeObject

A class representing a PDF document.

static open(stream: IOBase, password: str | None) → Document[source]

Open a PDF document.

Documents opened with this method are read-only and cannot be modified.

Parameters:

  • stream (io.IOBase) –

    The stream where the PDF document is stored.

    Read access is required.

  • password (Optional[str]) – the password to open the PDF document

Returns:

the newly created document instance

Return type:

pdftools_toolbox.pdf.document.Document

Raises:
static open_with_fdf(pdf_stream: IOBase, fdf_stream: IOBase, password: str | None) → Document[source]

Open a PDF document together with an FDF file.

Documents opened with this method are read-only and cannot be modified.

Parameters:

  • pdfStream (io.IOBase) –

    The stream where the PDF document is stored.

    Read access is required.

  • fdfStream (io.IOBase) –

    The stream where the FDF file is stored.

    Read access is required.

  • password (Optional[str]) – the password to open the PDF document

Returns:

the newly created document instance

Return type:

pdftools_toolbox.pdf.document.Document

Raises:
static create(stream: IOBase, conformance: Conformance | None, encryption: Encryption | None) → Document[source]

Create a new PDF document.

Documents with created with this method are writable and can be modified.

Parameters:

  • stream (io.IOBase) –

    The stream where the PDF document is stored.

    Both, read and write access is required.

  • conformance (Optional[pdftools_toolbox.pdf.conformance.Conformance]) –

    The required conformance level of the PDF document. Adding pages or content from incompatible documents or using incompatible features will lead to a conformance error.

    When using None, the conformance is determined automatically, based on the conformance of the input documents and the requirements of the used features.

    Note that for PDF/A document it is highly recommended to set an output intent using pdftools_toolbox.pdf.document.Document.output_intent .

  • encryption (Optional[pdftools_toolbox.pdf.encryption.Encryption]) – the optional encryption parameters

Returns:

the newly created document instance

Return type:

pdftools_toolbox.pdf.document.Document

Raises:

  • OSError – Error writing to the stream.

  • pdftools_toolbox.conformance_error.ConformanceError – If the conformance level is lower than 1.7 and Unicode passwords are specified. In this context “a Unicode password” is essentially one containing characters that are not in the Windows ANSI encoding (Windows Code Page 1252).

static create_with_fdf(pdf_stream: IOBase, fdf_stream: IOBase, conformance: Conformance | None, encryption: Encryption | None) → Document[source]

Create a new PDF document and an associated FDF.

Documents with created with this method are writable and can be modified. When creating a document with this method, all pdftools_toolbox.pdf.annotations.markup_annotation.MarkupAnnotation s - created or copied - are stored as an FDF file to the fdfStream. In the output PDF (pdfStream), only annotations that are not pdftools_toolbox.pdf.annotations.markup_annotation.MarkupAnnotation s are stored.

Parameters:
Returns:

the newly created document instance

Return type:

pdftools_toolbox.pdf.document.Document

Raises:

  • OSError – Error writing to the pdfStream

  • pdftools_toolbox.conformance_error.ConformanceError – If the conformance level is lower than 1.7 and Unicode passwords are specified. In this context “a Unicode password” is essentially one containing characters that are not in the Windows ANSI encoding (Windows Code Page 1252).

property language: str | None

the default language for the document.

A language identifier specifying the natural language for all text in the document except where overridden by language specifications for structure elements or marked content. If this entry is absent, the language is considered unknown.

Returns:

Optional[str]

Raises:

StateError – if the document has already been closed

property optional_content_groups: OptionalContentGroupList

The optional content groups (layers) of the document.

Returns:

pdftools_toolbox.pdf.optional_content_group_list.OptionalContentGroupList

Raises:

StateError – if the document has already been closed

property conformance: Conformance

the claimed conformance of the document.

This method only returns the claimed conformance level, the document is not validated.

Returns:

pdftools_toolbox.pdf.conformance.Conformance

Raises:

StateError – if the document has already been closed

property metadata: Metadata

the metadata of the document.

If the document is writable, the metadata object will be writable too and all changes to the metadata object are reflected in the document.

Returns:

pdftools_toolbox.pdf.metadata.Metadata

Raises:

StateError – if the document has already been closed

property pages: PageList

the pages of the document.

If the document is writable, it is possible to append new pages to the end of the list.

Returns:

pdftools_toolbox.pdf.page_list.PageList

Raises:

StateError – if the document has already been closed

property output_intent: IccBasedColorSpace | None

the output intent of the document.

The output intent specifies a color profile that characterizes the intended output device. It is used to render device colors on devices other than the intended output device.

Returns:

Optional[pdftools_toolbox.pdf.content.icc_based_color_space.IccBasedColorSpace]

Raises:

StateError – if the document has already been closed

property form_fields: FieldNodeMap

The form fields of the document

This list contains all AcroForm form fields that belong to this document. Adding to this list results in an error:

  • IllegalState if the list has already been closed

  • UnsupportedOperation if the document is read-only

  • IllegalArgument - if the given form field node is None - if the given form field node has already been closed - if the given form field node does not belong to the same document as the list - if the given form field node has already been added to a form field node list - if the given form field node’s identifier equals an identifier of one of the form field nodes in this list

This list does not support removing elements or setting elements or clearing.

Returns:

pdftools_toolbox.pdf.forms.field_node_map.FieldNodeMap

Raises:
property signature_fields: SignatureFieldList

The signature fields of the document

Signature fields are a special kind of form fields, that can contain digital signatures.

Returns:

pdftools_toolbox.pdf.forms.signature_field_list.SignatureFieldList

Raises:

StateError – if the document has already been closed

property plain_embedded_files: FileReferenceList

plain embedded files

This list contains plain embedded files, i.e., files that are embedded in this document without having a specific association (pdftools_toolbox.pdf.document.Document.associated_files ), and without being contained in any pdftools_toolbox.pdf.annotations.file_attachment.FileAttachment .

If the document is writable, then it is possible to append new file references to the list. Every file reference object can occur at most once in this list.

For PDF/A-3 documents, appending to this list results in a Conformance error.

Returns:

pdftools_toolbox.pdf.file_reference_list.FileReferenceList

Raises:

StateError – if the document has already been closed

property associated_files: FileReferenceList

document-associated files

This list contains associated files, whose associated object is the document.

If the document is writable, then it is possible to append new file references to the list. Every file reference object can occur at most once in this list.

Appending to this list results in a Conformance error if the document’s conformance is neither PDF/A-3 nor can be upgraded to PDF 2.0.

Returns:

pdftools_toolbox.pdf.file_reference_list.FileReferenceList

Raises:

StateError – if the document has already been closed

property all_embedded_files: FileReferenceList

plain embedded, associated, and attached files

This read-only list contains the union of all plain embedded files, associated files, and files contained in file attachment annotations. This is the list of files contained in a PDF as presented in a PDF viewer.

This list does not support appending.

Returns:

pdftools_toolbox.pdf.file_reference_list.FileReferenceList

Raises:

StateError – if the document has already been closed

property outline: OutlineItemList

The document outline, also known as “Bookmarks”.

Returns:

pdftools_toolbox.pdf.navigation.outline_item_list.OutlineItemList

Raises:

StateError – if the document has already been closed

property open_destination: Destination | None

The destination that is displayed when the document is opened.

Returns:

Optional[pdftools_toolbox.pdf.navigation.destination.Destination]

Raises:

StateError – if the document has already been closed

property permissions: Permission | None

The permissions in force for this document. This property is None if the document is not encrypted.

Returns:

Optional[pdftools_toolbox.pdf.permission.Permission]

Raises:

StateError – if the document has already been closed

property viewer_settings: ViewerSettings

The settings to use when opening the document in a viewer.

Returns:

pdftools_toolbox.pdf.navigation.viewer_settings.ViewerSettings

Raises:

StateError – if the document has already been closed

property is_linearized: bool

Whether the document is linearized.

Linearization is also known as “Fast Web View” and is a way of optimizing PDFs so they can be streamed into a client application. This helps online documents open almost instantly, without having to wait for a large document to completely download.

Returns:

bool

Raises:

StateError – if the document has already been closed