Get started with Python

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

info

The Python interface wraps the Toolbox add-on C API. For more details about specific functions and properties, review C API reference documentation.

Request trial or full license

Unlike the Pdftools SDK or the Pdftools SDK Shell Tool, the Toolbox add-on requires a license key for both evaluation and full use. To request a license key, follow these steps:

1. Contact the sales team through the Contact page and mark the Toolbox add-on 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 code example. The AddText example adds text to a PDF. Use similar steps to run any other code example from the toolbox-examples-python repository.

Clone and run the sample

1. Clone the toolbox-examples-python repository:

   git clone https://github.com/pdf-tools/toolbox-examples-python.git

2. Find your license key. For more information, review Find the license key.

3. In the code example folder, open the Python file (for example add_text.py).

4. In the add_text.py file, replace the string "YOUR_LICENSE_KEY" with your license key:

   # Set and check license key. If the license key is not valid, an exception is thrown.
   Sdk.initialize("YOUR_LICENSE_KEY", None)

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

5. Install the package for the Toolbox add-on by executing:

   pip install https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSDKXT/latest/pdftools_toolbox-latest.tar.gz

6. Navigate to the AddText code example:

   cd toolbox-examples-python/AddText

7. 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 example 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.
• The text to be added to the output PDF, written between double quotation marks.

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

python ./add_text.py INPUT_FILE "TEXT_TO_BE_ADDED" 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

To add the Toolbox add-on to your project, follow these steps:

1. Install the package for the Toolbox add-on by executing:

   pip install https://pdftools-public-downloads-production.s3.eu-west-1.amazonaws.com/productkits/PDFSDKXT/latest/pdftools_toolbox-latest.tar.gz

2. Clone the toolbox-examples-python repository and navigate to any sample directory.

3. Review the README.md file with usage details. Every code example includes a README.md with different usage instructions.

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

   from pdftools_toolbox.sdk import Sdk
   from pdftools_toolbox.geometry.real import Point
   from pdftools_toolbox.pdf import Document, FileReference, Metadata, PageCopyOptions, Page, PageList
   from pdftools_toolbox.pdf.content import Font, ContentGenerator, IccBasedColorSpace, Text, TextGenerator
   from pdftools_toolbox.pdf.navigation import ViewerSettings

Imports depend on the sample you use

The imports depend on the Python sample you use. Imports displayed in the last step of the previous procedure are valid for the Add text to PDF sample. Every sample includes a single Python file from which you can copy the imports. In case you want to use another functionality, copy the correct imports into your project with the following steps:

1. In the toolbox-examples-python repository, navigate to a sample directory. For example: toolbox-examples-python/MultipleUp.
2. Open the multiple_up.py file, and then copy its imports to the header of your Python code.

Initialize the Toolbox add-on

The Toolbox add-on always requires a license key to operate (unlike the Pdftools SDK). Without a valid license, every Toolbox add-on function call fails with LicenseError: No license key was set.

Getting a license key

Contact the Pdftools sales team through the Contact page to get a full license.

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

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

2. Call Sdk.initialize once at application startup, before any other Toolbox add-on method call:

   Sdk.initialize("YOUR_LICENSE_KEY", None)

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

To get a working reference with the Sdk.initialize method, follow these steps:

1. On the Code samples page, clone a sample repository. For example, clone toolbox-examples-python and navigate to toolbox-examples-python/AddText.
2. Find the Sdk.initialize method in the Python file of the sample. For example: Add text to PDF includes the Sdk.initialize method in the add_text.py file.
3. Replace the "insert-license-key-here" placeholder in the sample with your license key. Include the less-than (<) and greater-than (>) signs.

Implement your use case

Find other code examples that show you how to implement specific use cases with the Toolbox add-on using Python. Review the Toolbox add-on code examples page.