PDFtk と Python による PDF ページの結合と抽出
PDFtk の cat 操作では、ラスタライズせずに PDF を結合したり、ページ範囲を抽出したり、ページを並べ替えたりできます。このチュートリアルでは PDFtk Java を使い、小さなサンプル文書を二つ結合し、その結果からページを選択します。さらに、失敗時には非ゼロの終了ステータスを返し、既存の出力ファイルを置き換えない Python の結合処理を自動化します。
システム要件
以下のコマンドは、Linux 上で Bash 5.3.15、OpenJDK 21.0.12.1、Python 3.14.7、qpdf 12.4.1、Poppler 26.08.0 を使ってテストしました。開始前に java、python3、qpdf、pdftotext、curl、sha256sum を PATH に配置してください。これらはテスト済みのバージョンであり、それ以前のすべてのバージョンで動作するという意味ではありません。Poppler は pdftotext を提供します。qpdf は PDFtk とは独立して PDF の構造を検証します。
このローカルの例では、信頼できる暗号化されていない PDF を使用してください。パーサーが PDF を受け付けても、無害であること、表示が損なわれていないこと、アクティブコンテンツが含まれないことの証明にはなりません。信頼できない文書は適切に隔離された環境で処理し、このスクリプトをセキュリティフィルターとして使用しないでください。
PDFtk のインストール
PDFtk Java は PDFtk の移植版であり、元のネイティブ版 PDFtk Server 実行ファイルではありません。バージョン別のインストールガイドには、ディストリビューションのパッケージと、依存関係を含む単体の JAR が掲載されています。ここではその JAR を使い、パッケージマネージャーが提供する pdftk ではなく、毎回バージョン 3.3.3 を選択します。このチュートリアルでは Linux のシェルコマンドを使用し、macOS や Windows のインストーラーは扱いません。
書き込み可能なディレクトリで Bash を開き、次のブロックを貼り付けてください。新しい pdf-workflow ディレクトリを作成し、シェルの作業ディレクトリは元のままにします。ディレクトリがすでに存在する場合、ダウンロードに失敗した場合、チェックサムが一致しない場合は、ブロックの実行を停止します。実行を成功させるために既存のプロジェクトを削除しないでください。
(
set -eu
mkdir pdf-workflow
cd pdf-workflow
curl -fsSLo pdftk-java-3.3.3-all.jar \
https://gitlab.com/api/v4/projects/5024297/packages/generic/pdftk-java/v3.3.3/pdftk-all.jar
printf '%s %s\n' \
a694d49bd03e1edd4c23b3ba808bc221eb8a8ccfe7bfd2a0a884b2b2fb425188 \
pdftk-java-3.3.3-all.jar | sha256sum -c -
java -Xms16m -Xmx256m -XX:ActiveProcessorCount=2 -XX:-UsePerfData \
-Djava.io.tmpdir="$PWD" -Duser.home="$PWD" \
-jar pdftk-java-3.3.3-all.jar --version
)
ハッシュはダウンロードするバイト列を固定するもので、発行元の署名ではありません。バージョン出力が PDFtk Java 3.3.3 を示していることを確認してください。セットアップが失敗すると、新しいディレクトリやダウンロード済みファイルが残る場合があります。別の場所を選ぶ前に、その内容を確認してください。
PDF の基本操作
再現可能な入力を用意するため、次の内容を pdf-workflow/make_samples.py として保存してください。Python の標準ライブラリだけを使い、ALPHA ONE と ALPHA TWO のラベルが付いた二ページの PDF と、BETA ONE のラベルが付いた一ページの PDF を作成します。サンプルと同名のファイルが存在する場合は、置き換えずに処理を拒否します。
from pathlib import Path
def write_pdf(path, labels):
page_ids = [4 + 2 * index for index in range(len(labels))]
kids = ' '.join(f'{page_id} 0 R' for page_id in page_ids)
objects = [
b'<< /Type /Catalog /Pages 2 0 R >>',
f'<< /Type /Pages /Count {len(labels)} /Kids [{kids}] >>'.encode(),
b'<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>',
]
for page_id, label in zip(page_ids, labels):
stream = f'BT /F1 24 Tf 40 180 Td ({label}) Tj ET\n'.encode('ascii')
objects.append(
f'<< /Type /Page /Parent 2 0 R /MediaBox [0 0 360 240] '
f'/Resources << /Font << /F1 3 0 R >> >> '
f'/Contents {page_id + 1} 0 R >>'.encode()
)
objects.append(f'<< /Length {len(stream)} >>\nstream\n'.encode()
+ stream + b'endstream')
data = bytearray(b'%PDF-1.4\n')
offsets = [0]
for object_id, payload in enumerate(objects, start=1):
offsets.append(len(data))
data.extend(f'{object_id} 0 obj\n'.encode() + payload + b'\nendobj\n')
xref = len(data)
data.extend(f'xref\n0 {len(offsets)}\n0000000000 65535 f \n'.encode())
for offset in offsets[1:]:
data.extend(f'{offset:010d} 00000 n \n'.encode())
data.extend(f'trailer\n<< /Size {len(offsets)} /Root 1 0 R >>\n'
f'startxref\n{xref}\n%%EOF\n'.encode())
with path.open('xb') as output:
output.write(data)
write_pdf(Path('input-a.pdf'), ['ALPHA ONE', 'ALPHA TWO'])
write_pdf(Path('input-b.pdf'), ['BETA ONE'])
PDF の結合
セットアップ時と同じ親ディレクトリから実行してください。A と B は入力ハンドルです。A1-end B1-end は A の全ページに続けて B の全ページを含めます。ページ範囲とハンドルの詳細は PDFtk マニュアルに記載されています。独自の文書を使う場合は、入力名を置き換え、最初にページ数を確認してください。
(
set -eu
cd pdf-workflow
python3 make_samples.py
java -Xms16m -Xmx256m -XX:ActiveProcessorCount=2 -XX:-UsePerfData \
-Djava.io.tmpdir="$PWD" -Duser.home="$PWD" \
-jar pdftk-java-3.3.3-all.jar A=input-a.pdf B=input-b.pdf \
cat A1-end B1-end output combined.pdf dont_ask
)
低レベルのコマンドでは、意図的に dont_ask を使用しています。確認プロンプトなしで実行し、指定された出力ファイルを上書きします。これらは順番に実行するサンプルコマンドであり、安全に出力を確定するラッパーではありません。失敗すると、不完全な出力が残る場合があります。保存が必要なファイルを指定しないでください。後述の Python 結合スクリプトは、置き換えを行わない別の方針を採用しています。結合ブロック全体を再実行すると、既存のサンプルファイルで停止します。その失敗後に古い入力を使って処理を続行することはありません。
PDF の分割
上で作成した結合済み PDF からページを抽出し、並べ替えます。ページ番号は一から始まります。cat 3 1 は三ページ目、次に一ページ目を選択します。cat 1-2 を指定すると、連続した範囲を選択します。
(
set -eu
cd pdf-workflow
java -Xms16m -Xmx256m -XX:ActiveProcessorCount=2 -XX:-UsePerfData \
-Djava.io.tmpdir="$PWD" -Duser.home="$PWD" \
-jar pdftk-java-3.3.3-all.jar combined.pdf cat 3 1 output selected.pdf dont_ask
)
生成コマンドの終了ステータスだけでなく、実際の出力を両方とも確認してください。
(
set -eu
cd pdf-workflow
qpdf --check combined.pdf >/dev/null
test "$(qpdf --show-npages combined.pdf)" = 3
printf 'Merged pages:\n'
pdftotext -layout combined.pdf -
qpdf --check selected.pdf >/dev/null
test "$(qpdf --show-npages selected.pdf)" = 2
printf 'Selected pages:\n'
pdftotext -layout selected.pdf -
)
結合後のテキストは ALPHA ONE、ALPHA TWO、BETA ONE の順になるはずです。選択後のテキストは BETA ONE、ALPHA ONE の順になるはずです。両方の PDF をビューアーで開き、表示を確認してください。これらのテキストと構造の検証だけでは、任意の文書のフォーム、注釈、署名、表示上の細部がすべて保持されることは証明できません。画像のみのスキャンには、抽出可能なテキストがない場合があります。
PDF ファイルサイズの最適化
PDFtk の compress オプションは、ページストリームの圧縮を復元します。画像のダウンサンプリング機能ではなく、PDF のサイズが小さくなる保証もありません。結合によって文書が「標準化」されるわけでもありません。画像圧縮には、独自の品質確認を伴う別の書き換えワークフローが必要なため、この例には Ghostscript による変換工程を含めていません。
統合の例
次の内容を pdf-workflow/merge_pdfs.py として保存してください。JAR、新しい出力ファイル名、一つ以上の入力を受け取ります。以下の呼び出し例のように、JAR 引数の前に -- を置いてください。これにより、Python の引数パーサーはファイル名の先頭にあるハイフンを文字どおりに扱います。スクリプトは入力パスを解決してから、それぞれを個別のサブプロセス引数として渡します。ファイル名からシェルコマンドを組み立てることはありません。
このローカルの Linux スクリプトは、入力の合計サイズが 100 MiB を超える場合は拒否し、各入力を qpdf で検証して、結合した PDF を出力先ディレクトリに一時配置します。一時配置した PDF の検証後、os.link を使い、既存の出力先を置き換えずに出力を確定します。ファイルシステムはハードリンクに対応している必要があります。クラッシュ時の永続性や、処理中に誰かがディレクトリや入力を悪意をもって変更する状況での安全な動作は保証しません。
import argparse
import os
import subprocess
import sys
import tempfile
from pathlib import Path
def main():
parser = argparse.ArgumentParser(description='Merge PDFs without replacing an output.')
parser.add_argument('jar', type=Path)
parser.add_argument('output', type=Path)
parser.add_argument('inputs', type=Path, nargs='+')
args = parser.parse_args()
destination = args.output.absolute()
if os.path.lexists(destination):
raise FileExistsError(f'Output already exists: {destination}')
jar = args.jar.resolve(strict=True)
inputs = [path.resolve(strict=True) for path in args.inputs]
if not jar.is_file() or any(not path.is_file() for path in inputs):
raise ValueError('The JAR and inputs must be regular files.')
if sum(path.stat().st_size for path in inputs) > 100 * 1024 * 1024:
raise ValueError('Combined inputs exceed 100 MiB.')
for path in inputs:
subprocess.run(['qpdf', '--check', str(path)], check=True,
capture_output=True, timeout=60)
with tempfile.TemporaryDirectory(prefix='.pdf-merge-', dir=destination.parent) as staging:
staged = Path(staging) / 'merged.pdf'
command = [
'java', '-Xms16m', '-Xmx256m', '-XX:ActiveProcessorCount=2', '-XX:-UsePerfData',
f'-Djava.io.tmpdir={staging}', f'-Duser.home={staging}', '-jar', str(jar),
*map(str, inputs), 'cat', 'output', str(staged), 'dont_ask',
]
subprocess.run(command, check=True, capture_output=True, timeout=60)
subprocess.run(['qpdf', '--check', str(staged)], check=True,
capture_output=True, timeout=60)
os.link(staged, destination)
print(f'Created {destination.name}')
if __name__ == '__main__':
try:
main()
except (OSError, ValueError, subprocess.SubprocessError) as error:
print(f'Cannot merge PDFs: {error}', file=sys.stderr)
sys.exit(1)
同じサンプル入力に対して実行してください。出力は combined.pdf と同じ順序の三ページになります。
(
set -eu
cd pdf-workflow
python3 merge_pdfs.py -- pdftk-java-3.3.3-all.jar merged-from-python.pdf input-a.pdf input-b.pdf
qpdf --check merged-from-python.pdf >/dev/null
test "$(qpdf --show-npages merged-from-python.pdf)" = 3
pdftotext -layout merged-from-python.pdf -
)
ファイルの欠落、無効な PDF、サイズ超過の入力、実行ファイルの欠落、タイムアウト、出力確定の失敗があると、結合成功を報告せずに非ゼロのステータスを返します。二度目の呼び出しでは merged-from-python.pdf を拒否し、そのバイト列を変更しません。事前検証の失敗では一時出力を作成しません。処理中の通常の失敗では、一時配置用ディレクトリを削除します。強制終了すると、その非公開ディレクトリが残る場合があります。各ネイティブサブプロセスには 60 秒の制限時間があります。結合処理全体で 60 秒ではありません。ここでは qpdf の警告を失敗として扱います。修復された文書を黙って受け入れるのではなく、元の文書を確認してください。
よくある問題のトラブルシューティング
メモリー関連のエラー
100 MiB の検証は入力を受け入れるための方針であり、RAM 使用量の見積もりではありません。PDF の複雑さ、展開、Java のヒープ外の割り当ても影響します。-Xmx256m が制限するのは Java ヒープであり、プロセス全体のメモリーではありません。受け入れた入力の処理が完了する保証もありません。自動バッチ処理はありません。サイズ超過の文書は拒否され、サイズ超過のバッチに入れられたり、その前に空のバッチが作られたりすることはありません。
ファイルアクセスのエラー
入力と JAR が読み取り可能で、出力の親ディレクトリが存在し、書き込み可能かを確認してください。出力先がすでに存在する場合は、新しい出力先を選んでください。Python スクリプトは、別の処理が失敗した場合でも既存の出力先を削除しません。結合を動作させるためだけにファイルのアクセス権限を広く緩めないでください。qpdf や PDFtk が失敗した場合は、問題のある入力に対して該当コマンドをローカルで実行し、診断メッセージを確認してください。
最初は一度に一つのジョブを処理してください。入力ファイルが小さいだけでは、メモリー使用量の上限やスループットの向上は確認できません。独自のワークロードと利用可能なリソースを測定した後でのみ、並行処理を追加してください。
セキュリティ上の考慮事項
PDF の安全な取り扱い
PDFtk の encrypt_128bit モードは、最新の AES ではなく、旧式の RC4 を使用します。機密文書の保護には使用しないでください。所有者パスワードだけでは、PDF を開く際のパスワード入力は必須になりません。開く際にパスワードを要求するのは、別の仕組みであるユーザーパスワードです。従来のワークフローを保守する場合は、パスワードをコマンド引数やスクリプトにコピーせず、パスワードオプションを参照してください。対話形式でのパスワード入力には PROMPT を使用できます。この非対話型の結合スクリプトは、パスワードで保護された入力を扱いません。
ファイルのアクセス権限の管理
PDF の印刷や変更の制限は、閲覧アプリケーションがその制限を守ることに依存します。アクセス制御の境界にはなりません。ファイル自体へのアクセスを制限してください。結合スクリプトは、機密テキストやメタデータの削除も、組織の保存・共有ポリシーの設定も行いません。
まとめ
順序が重要な場合はページ範囲を明示し、生成された文書を確認してください。また、コマンドを自動化する前に、出力の置き換えを許容できるかを決めてください。この小規模なワークフローが要件に合うことを確認したら、PDFtk Java プロジェクトで追加の操作を調べられます。
