Skip to main content
Version: Version 1.7

Get started with Python

This guide walks you through the steps to use the Toolbox add-on in a sample project with Python.

info

The Python interface is implemented as a wrapper around the Toolbox add-on C API. For more details about specific functions and properties, review the C API reference documentation.

Request trial or full license

Unlike the Pdftools SDK or SDK Shell Tool, the Toolbox add-on requires a trial license key for evaluation, or a full license key for valid use. To request the license key:

  1. Reach out to the sales team through the Contact page and mark the Conversion Service as the product of your interest for a trial license.

If you already have a license key and you need to copy it, review Find the license key.

Prerequisites

The Toolbox add-on for Python requires Python 3.6 or higher.

Getting started with a sample project

Learn how to use the Toolbox add-on using a Python sample project and convert a PDF file to an image.

Download and run the sample

  1. Download a sample project, and then unzip the file.

  2. Navigate to the root directory of the unzipped sample project, where add_text.py resides.

  3. To add the text string "Hello World!" to the first page of the PDF file BlankNoneNoTP.pdf, run:

    python ./add_text.py BlankNoneNoTP.pdf "Hello World!" output.pdf
    note

    Run python3 instead on systems where only Python 3 is installed and python is not aliased.

The code sample takes:

  • The input and output files represented as a file name, a file path with the file name, or the output directory.
  • Both file paths (input and output) can be relative or absolute.

Review the following snippet with a placeholder and compare it to the last step of the previous procedure:

python ./add_text.py INPUT_FILE OUTPUT_FILE

Integrate the Toolbox add-on into your application

Integrate and initialize the Toolbox add-on into your application by following the instructions in the next sections.

Add the Toolbox add-on to your project

  1. Install the Python package:

    pip install https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSDKXT/latest/pdftools_toolbox-latest.tar.gz
  2. From the Toolbox add-on code samples page, download any Python code sample.

  3. Unzip a code sample and review the README.md file with usage details. Every code sample includes a README.md with different usage instructions.

  4. Import the following packages in the header of your Python code:

    from ctypes import *
    from pdftools_toolbox.py_ctypes import *
    from pdftools_toolbox.streams import StreamDescriptor

Initialize the Toolbox add-on

To initialize the Toolbox add-on with your license key, follow these steps:

  1. Copy your license key. For more information, review Find the license key.

  2. Replace the <PDFSDK,V1,include-your-key-here> in the following function with the value of your license key:

    # Initialize library
    initialize()

    # Optional: Without a license key the Toolbox add-on returns watermarked results.
    # Initialize the Toolbox add-on with a license key to remove the watermark.
    # The Toolbox add-on returns an error if you use an invalid license key.
    if sdk_initialize("<PDFSDK,1,insert-license-key-here>", None) == 0:
    print_error_message("Failed to set the license key.")
    exit(1)

    Use the license key in the same format as you copied it. Include the less-than (<) and greater-than (>) signs.

tip

Without a valid license key the Toolbox add-on returns an error. Get in touch with the Pdftools sales team through the Contact page to get a full license.

Uninitialize the Toolbox add-on

After processing files with the Toolbox add-on, call the Uninitialize method to unload the library correctly:

# Uninitialize library
uninitialize();
tip

Download other sample projects that show you how to implement specific use cases with the Toolbox add-on using Python. Review the Toolbox add-on code samples page.