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.