pdftools_sdk.pdf_a.conversion.converter

Module Attributes

ConversionEventFunc

The event for errors, warnings, and informational messages that occur during conversion

Classes

Converter()

The class to convert PDF documents to PDF/A

pdftools_sdk.pdf_a.conversion.converter.ConversionEventFunc

The event for errors, warnings, and informational messages that occur during conversion

Report a conversion event that occurred in pdftools_sdk.pdf_a.conversion.converter.Converter.convert() . These events can be used to:

• Generate a detailed conversion report.

• Detect and handle critical conversion events.

Note that if a document cannot be converted to the requested conformance, the pdftools_sdk.pdf_a.conversion.converter.Converter.convert() throws an exception. However, even if the output document meets all required standards, the conversion might have resulted in differences that might be acceptable in some processes but not in others. Such potentially critical conversion issues are reported as conversion events.

We suggest checking which conversion events can be tolerated in your conversion process and which must be considered critical:

• Review the suggested severity of events. Each event has a default severity indicated by severity which is based on the event’s category. Review the suggested severity of each pdftools_sdk.pdf_a.conversion.event_category.EventCategory and determine the pdftools_sdk.pdf_a.conversion.event_severity.EventSeverity to be used in your process.

• Handle events according to their severity. - Events of severity pdftools_sdk.pdf_a.conversion.event_severity.EventSeverity.ERROR : The conversion must be considered as failed. - Events of severity pdftools_sdk.pdf_a.conversion.event_severity.EventSeverity.WARNING : In case of a warning, the output file is best presented to a user to decide if the result is acceptable. The properties message, context, and page in combination with the output file are helpful to make this decision. If a manual review is not feasible, critical warnings should be classified as an pdftools_sdk.pdf_a.conversion.event_severity.EventSeverity.ERROR . An exception to this is, if all processed input documents are similar in their content, e.g. because they have been created by a single source (application). In this case, the conversion result can be verified using representative test files and the event severity chosen accordingly. - Events of severity pdftools_sdk.pdf_a.conversion.event_severity.EventSeverity.INFORMATION : No further action is required.

Parameters:

• dataPart (Optional[str]) –

  The data part is None for the main file and a data part specification for embedded files.

  Examples:

  • embedded-file:file.pdf: For a file file.pdf that is embedded in the main file.

  • embedded-file:file1.pdf/embedded-file:file2.pdf: For a file file2.pdf that is embedded in an embedded file file1.pdf.

• message (str) – The event message

• severity (pdftools_sdk.pdf_a.conversion.event_severity.EventSeverity) –

  The suggested severity of the event.

  We suggest checking, which conversion events are tolerable in your conversion process and which must be considered critical. See the documentation of pdftools_sdk.pdf_a.conversion.converter.ConversionEventFunc() for a more detailed description.

• category (pdftools_sdk.pdf_a.conversion.event_category.EventCategory) –

  The category of the event. This parameter can be used to:

  • Classify the severity of an event

  • Specialized handling of events

  See the documentation of pdftools_sdk.pdf_a.conversion.converter.ConversionEventFunc() for a more detailed description.

• code (pdftools_sdk.pdf_a.conversion.event_code.EventCode) – The code identifying particular events which can be used for detection and specialized handling of specific events. For most applications, it suffices to handle events by category.

• context (str) – A description of the context where the event occurred

• pageNo (int) – The page this event is associated to or 0

alias of Callable[[str | None, str, EventSeverity, EventCategory, EventCode, str, int], None]

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: 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 (pdftools_sdk.pdf_a.conversion.invoice_type.InvoiceType) – The type of invoice.

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

• afRelationship (Optional[pdftools_sdk.pdf_a.conversion.a_f_relationship.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: 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[pdftools_sdk.pdf_a.conversion.a_f_relationship.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: 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.ConversionEventFunc() to detect critical conversion events.

Parameters:

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

• document (pdftools_sdk.pdf.document.Document) – The document to convert

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

• options (Optional[pdftools_sdk.pdf_a.conversion.conversion_options.ConversionOptions]) – The conversion options

• outOptions (Optional[pdftools_sdk.pdf.output_options.OutputOptions]) – The output options object

Returns:

The result of the conversion

Return type:

pdftools_sdk.pdf.document.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: Callable[[str | None, str, EventSeverity, EventCategory, EventCode, str, int], None]) → 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: Callable[[str | None, str, EventSeverity, EventCategory, EventCode, str, int], None]) → 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.