pdftools_toolbox.pdf.file_reference

Classes

FileReference(handle)

Description of a file
class pdftools_toolbox.pdf.file_reference.FileReference(handle)[source]

Bases: _NativeObject

Description of a file

A file description is used for embedded files.

static create(target_document: Document, data: IOBase, name: str, media_type: str | None, description: str | None, modification_date: datetime | None) → FileReference[source]

Create a new file reference object

The newly created file reference object belongs to the document but is not (yet) used as an embedded file. The object can be added to the list of embedded files or to the list of associated files.

Parameters:

  • targetDocument (pdftools_toolbox.pdf.document.Document) – the output document with which the returned object is associated

  • data (io.IOBase) – A stream of the file to be added. Read access is required.

  • name (str) – The name to be used for the embedded file. This name is presented to the user when viewing the list of embedded files.

  • mediaType (Optional[str]) – The mime type of the embedded file. Default: “application/octet-stream”. Common values other than the default are “application/pdf”, “application/xml”, or “application/msword”.

  • description (Optional[str]) – The description of the embedded file. This is presented to the user when viewing the list of embedded files.

  • modificationDate (Optional[datetime]) – The modify date of the file. Default: current time.

Returns:

the newly created file reference object

Return type:

pdftools_toolbox.pdf.file_reference.FileReference

Raises:
static copy(target_document: Document, file_reference: FileReference) → FileReference[source]

Copy a file reference object

Copy a file reference object from an input document to the given targetDocument. The returned object is associated with the given target document but not yet part of it.

Parameters:
Returns:

the copied file reference, associated with the current document

Return type:

pdftools_toolbox.pdf.file_reference.FileReference

Raises:

  • ValueError – if the targetDocument argument has already been closed

  • ValueError – if the targetDocument argument is read-only

  • ValueError – if the fileReference argument is not associated with an input document

  • ValueError – if the fileReference object has already been closed

  • pdftools_toolbox.conformance_error.ConformanceError – if the document’s conformance is PDF/A-1

  • pdftools_toolbox.conformance_error.ConformanceError – if the document’s conformance is PDF/A-2 and the fileReference object contains an embedded file other than PDF/A-1 or PDF/A-2

  • OSError – Error reading from the input stream or writing to the output stream

property association_relationship: str | None

The file’s association relationship

This property is None if the file is not associated with any object. When associating a file reference with an object such as the document or a page, then this property defines the relationship between the file and the object. Typical values are:

  • “Source”: used if this file is the original source material for the associated content.

  • “Data”: used if this file represents information used to derive a visual presentation such as for a table or a graph.

  • “Alternative”: used if this file is an alternative representation of content, for example audio.

  • “Supplement”: used if this file represents a supplemental representation of the original source or data that may be more easily consumable (e.g., a MathML version of an equation).

  • “EncryptedPayload”: used if this file is an encrypted payload document that should be displayed to the user if the PDF processor has the cryptographic filter needed to decrypt the document.

  • “FormData”: used if this file is the data associated with form fields of this PDF.

  • “Schema”: used if this file is a schema definition for the associated object.

  • “Unspecified”: used when the relationship is not known.

Returns:

Optional[str]

Raises:

StateError – if the object or the owning document has already been closed

property description: str | None

The file’s description

For embedded files, this is the description of the file presented to the user in the list of embedded files.

Returns:

Optional[str]

Raises:

StateError – if the object or the owning document has already been closed

property media_type: str | None

The file’s MIME type

Returns:

Optional[str]

Raises:

StateError – if the object or the owning document has already been closed

property modification_date: datetime | None

The file’s date of last modification

Returns:

Optional[datetime]

Raises:

StateError – if the object or the owning document has already been closed

property name: str

The file name

For embedded files, this is the name presented to the user in a the list of embedded files.

Returns:

str

Raises:

StateError – if the object or the owning document has already been closed

property data: IOBase

The file’s stream

Returns:

io.IOBase

Raises:

StateError – if the object or the owning document has already been closed