pdftools_sdk.pdf_a.conversion.converter

Classes

Converter()

The class to convert PDF documents to PDF/A

class pdftools_sdk.pdf_a.conversion.converter.Converter

Bases: _NativeObject

The class to convert PDF documents to PDF/A

__init__()

add_invoice_xml(invoice_type: InvoiceType, invoice: io.IOBase, af_relationship: AFRelationship | None = None) → None

Prepares the invoice XML file (ZUGFeRD or Factur-X) for embedding.

Note: This requires the compliance to be set to PDF/A-3.

Parameters:

• invoiceType (InvoiceType) – The type of invoice.

• invoice (io.IOBase) – The XML invoice stream.

• afRelationship (Optional[AFRelationship]) – If no value is provided, a sensible default value is chosen based on the invoice type and version.

Raises:

ValueError – The invoice stream could not be opened for reading.

add_associated_file(embedded_file: io.IOBase, name: str, associate: int | None = None, af_relationship: AFRelationship | None = None, mime_type: str | None = None, description: str | None = None, modification_date: datetime | None = None) → None

Prepares the associated file for embedding.

Add a file to the document’s embedded files. For PDF/A-3, the embedded file is associated with an object of the document, i.e. it is an associated file. The file is embedded as-is. Embedding files is not allowed for PDF/A-1 and restricted to PDF/A conforming files for PDF/A-2.

Parameters:

• embeddedFile (io.IOBase) – The stream of the embedded file.

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

• associate (Optional[int]) – The object to associate the embedded file with, -1 for none, 0 for document, number greater than 0 for respective page. If None, the default value is 0 for PDF/A-3 and -1 otherwise.

• afRelationship (Optional[AFRelationship]) – The relationship of the embedded file to the object associate. (Ignored, if associate is -1.) If None, the default value is pdftools_sdk.pdf_a.conversion.a_f_relationship.AFRelationship.UNSPECIFIED.

• mimeType (Optional[str]) – MIME ­Type of the embedded file. Common values other than the default are “application/pdf”, “application/xml” or “application/msword”. If None, the default value is “application/octet-stream”.

• description (Optional[str]) – A description of the embedded file. This is presented to the user when viewing the list of embedded files. If None, the default value is “”.

• modificationDate (Optional[datetime]) – The modify date of the file. If None, the default value is modification date of the file on the file system or current time, if not available.

Raises:

• ValueError – The associated file stream could not be opened for reading.

• ValueError – The associate argument is invalid.

• OSError – Error reading from embeddedFile.

convert(analysis: AnalysisResult, document: Document, out_stream: io.IOBase, options: ConversionOptions | None = None, out_options: OutputOptions | None = None) → Document

Convert a document to PDF/A.

Note that it is highly recommended to use pdftools_sdk.pdf_a.conversion.converter.Converter.ConversionEvent to detect critical conversion events.

Parameters:

• analysis (AnalysisResult) – The result of the document’s analysis using pdftools_sdk.pdf_a.validation.validator.Validator.analyze.

• document (Document) – The document to convert

• outStream (io.IOBase) – The stream where the converted document is written

• options (Optional[ConversionOptions]) – The conversion options

• outOptions (Optional[OutputOptions]) – The output options object

Returns:

The result of the conversion

Return type:

Document

Raises:

• pdftools_sdk.license_error.LicenseError – The license check has failed.

• ValueError – The outOptions argument is invalid.

• ValueError – The output stream could not be opened for writing.

• StateError – The document has already been closed.

• ValueError – The analysis has already been closed, e.g. due to a previous conversion.

• ValueError – The PDF/A version of the analysis and the conversion options do not match.

• ValueError – The analysis is not the analysis result of document.

• OSError – Error reading from or writing to the outStream.

• pdftools_sdk.conformance_error.ConformanceError – The conformance required by options cannot be achieved. - PDF/A level U: All text of the input document must be extractable. - PDF/A level A: In addition to the requirements of level U, the input document must be tagged.

• pdftools_sdk.conformance_error.ConformanceError – The PDF/A version of the conformances of analysis and options differ. The same PDF/A version must be used for the analysis and conversion.

• ValueError – The outOptions specifies document encryption, which is not allowed in PDF/A documents.

• pdftools_sdk.generic_error.GenericError – The document cannot be converted to PDF/A.

• pdftools_sdk.corrupt_error.CorruptError – The analysis has been stopped.

• pdftools_sdk.processing_error.ProcessingError – Failed to add the invoice file. Possible reasons include an invalid XML format, or that the invoice type conflicts with the content of the XML file.

• pdftools_sdk.unsupported_feature_error.UnsupportedFeatureError – The document is not a PDF, but an XFA document. See pdftools_sdk.pdf.document.Document.xfa for more information on how to detect and handle XFA documents.

• pdftools_sdk.not_found_error.NotFoundError – A required font is missing from the installed font directories.

• StateError – Invalid associate value for an embedded file.

add_conversion_event_handler(handler: ConversionEventFunc) → None

Add handler for the ConversionEventFunc event.

Parameters:

handler – Event handler. If a handler is added that is already registered, it is ignored.

remove_conversion_event_handler(handler: ConversionEventFunc) → None

Remove registered handler of the ConversionEventFunc event.

Parameters:

handler – Event handler that shall be removed. If a handler is not registered, it is ignored.