Process documents with Document Engine and Python

This guide walks you through the steps necessary to start Document Engine. It also shows you how to use it to process documents. By the end, you’ll be able to merge two PDF documents into one using Document Engine’s HTTP API from Python.

Requirements

Document Engine is compatible with a range of platforms. Below is the list of supported operating systems.

• macOS:

  • Ventura
  • Monterey
  • Mojave
  • Catalina
  • Big Sur

• Linux:

  • Ubuntu, Fedora, Debian, and CentOS
  • Ubuntu and Debian derivatives (such as Kubuntu, Xubuntu) are also supported

Processor requirements:

• 64-bit Intel (x86_64) processors
• ARM (AArch64) processors

Minimum system requirements:

• At least 4GB of RAM, regardless of the operating system

Installing Docker

Document Engine is distributed as a Docker container. To run it on your computer, you need to install a Docker runtime distribution for your operating system.

Starting Document Engine

To start Document Engine, follow the steps below.

1. Open your terminal emulator.

   • macOS
   • Windows
   • Linux

   Use the terminal emulator integrated with your code editor or IDE. Alternatively, you can use Terminal.app or iTerm2(opens in a new tab).

2. Run the following command to start the Document Engine container:

docker run --rm -t -p 5000:5000 -e API_AUTH_TOKEN=secret pspdfkit/document-engine:1.10.0

This command may take some time to complete depending on your internet connection speed, as it needs to pull the Docker image. You’ll know that Document Engine is successfully running when you see a message similar to the following in your terminal:

[info]  2024-02-05 18:56:45.286  Running Document Engine version 1.10.0

Document Engine is now up and running!

Installing Python

The interaction with Document Engine happens through its HTTP API — you send documents and commands in the request and receive the resulting file in the response. To do this, you’ll invoke the API from the Python script. But first, you need to install Python for your operating system:

xcode-select --install

brew install python

python3 --version

apt-get update && apt-get install -y python3.9 python3-pip && ln -s /usr/bin/python3.9 /usr/bin/python3

dnf install -y python3 python3-pip

Merging PDFs

To make HTTP requests to Document Engine’s API, you need an HTTP client library. For this scenario, you’ll use the excellent Requests(opens in a new tab) package. Install it by running the following command:

python3 -m pip install requests==2.25.1

python -m pip install requests==2.25.1

python3 -m pip install requests==2.25.1

Now you can create a script to merge the PDFs. It’ll take two file paths as command-line arguments, send the files to Document Engine to merge them, and save the result in another file on disk. Create a merge.py file with the following content:

import sys
import json
import requests

if len(sys.argv) < 3:
  print("Too few arguments.")
  exit(1)

file1 = sys.argv[1]
file2 = sys.argv[2]

url = "http://localhost:5000/api/build"

payload= {
  "instructions": json.dumps({
    "parts": [
      {
        "file": "file1"
      },
      {
        "file": "file2"
      }
    ]
})}

files=[
  ('file1',('file1.pdf',open(file1,'rb'),'application/pdf')),
  ('file2',('file2.pdf',open(file2,'rb'),'application/pdf'))
]
headers = {
  'Authorization': 'Token token=secret'
}

response = requests.post(url, headers = headers, data = payload, files = files)

if response.status_code == 200:
  with open("result.pdf", "wb") as f:
    f.write(response.content)
else:
  print(
    f"Request to Document Engine failed with status code {response.status_code}: '{response.text}'."
  )

The script verifies that the number of arguments is correct and prepares the request data. It includes two files — file1 and file2 — and a list of instructions for Document Engine. By default, Document Engine’s output for the /api/build endpoint is the result of merging all documents or parts of the instructions. To learn more about the /api/build instructions, go to Document Engine’s API Reference(opens in a new tab).

The rest of the code deals with error handling, and if everything goes well, it saves the result in the result.pdf file in the current working directory.

You can check how it works in practice yourself! Pick any two PDFs on your computer (or use file1.pdf and file2.pdf if you don’t have any), and run the script:

python3 merge.py path/to/file1.pdf path/to/file2.pdf

python merge.py path/to/file1.pdf path/to/file2.pdf

python3 merge.py path/to/file1.pdf path/to/file2.pdf

Make sure to replace path/to/file1.pdf and path/to/file2.pdf with the actual location of the PDF files on your computer.

If you used the two files from the links above, you should see a five-page PDF document like what’s shown below.

That’s it! Now you know how to use Document Engine's API to perform operations on documents with Python. To learn more about the various operations you can perform on documents with Document Engine, visit Document Engine's API Reference(opens in a new tab).