文書管理

ドキュメント管理

Document クラスは Aspose.PDF FOSS for Python におけるほぼすべての操作のエントリーポイントです：新しい PDF の作成、既存の PDF の読み込み、ページの編集、結果の書き出しです。このガイドでは、ドキュメントのライフサイクル、ページコレクション操作、最適化、マルチファイルワークフロー、暗号化、および想定すべき例外について解説します。

ドキュメントライフサイクル：作成、オープン、保存

Document() は引数がない場合、空のインメモリドキュメントを作成します。ファイルパス、生の bytes、または任意の読み取り可能なバイナリストリームを最初の引数として渡す（あるいは load_from() を明示的に呼び出す）ことで、既存の PDF を読み込むことができます。save() はパスまたは io.BytesIO のような書き込み可能なバイナリストリームを受け付けます。

from aspose_pdf import Document

# Create a new, empty document and add a blank page
doc = Document()
doc.pages.add()
doc.save("hello.pdf")

# Re-open it — a path, bytes, or a binary stream all work
reopened = Document("hello.pdf")
print(reopened.page_count)   # 1

# ...or load explicitly onto an existing instance
another = Document()
another.load_from("hello.pdf")

reopened.close()
another.dispose()
doc.dispose()

save() は、宛先パスがすでに存在する場合、overwrite=True を渡さない限り FileExistsError を送出します。close() は dispose() のエイリアスです；両方とも冪等であるため、複数回呼び出しても安全です。

保存先として実装されているのは PDF のみです――これはライブラリのコアであり、完全に機能する機能です。SaveFormat.PPTX や DocFormat.HTML のようなエクスポート値を save() に渡すと、誤ったラベルのファイルを書き込む代わりに UnsupportedFeatureException が送出されるため、エクスポート失敗は常に静かではなく明示的に通知されます。

ページコレクションの管理

doc.pagesはPageCollectionです。len()、反復、0ベースインデックス（doc.pages[0]）をサポートし、構造編集のためにadd()、insert(index, page)、delete(index)も利用できます。各Pageはindex、rect（MediaBox）およびrotationを公開します。

from aspose_pdf import Document

doc = Document()
doc.pages.add()            # page 0
doc.pages.add()            # page 1
doc.pages.insert(1, None)  # insert a blank page at index 1

print(doc.page_count)      # 3

first_page = doc.pages[0]
print(first_page.rect)     # (0, 0, 612, 792)

for page in doc.pages:
    print(page.index, page.rotation)

doc.pages.delete(1)        # remove the page we inserted
doc.save("pages_demo.pdf", overwrite=True)

pages.add(page=None)は引数なしで呼び出されたときに空白ページを追加します。pages.insert()は範囲外のインデックスをエラーを出すのではなく、最も近い有効な位置にクランプします。

ドキュメントの最適化と圧縮

Document.optimizeは1回の呼び出しで画像/ストリームの重複排除、未使用オブジェクトのガベージコレクション、ストリーム圧縮を実行します。どの手法を実行するか制御するにはOptimizationOptionsインスタンスを渡してください。省略すると標準のクリーンアッププロファイルが使用されます。

from aspose_pdf import Document, OptimizationOptions

doc = Document("large_report.pdf")

options = OptimizationOptions()
options.remove_unused_objects = True
options.link_duplicate_streams = True
options.image_compression_quality = 60
options.subset_fonts = True

doc.optimize(options)
doc.save("large_report_optimized.pdf", overwrite=True)

optimize_resources()はoptimize()のエイリアスです。構造クリーンアップパスなしでストリーム圧縮だけを行いたい場合は、doc.compress_streams()を直接呼び出してください。

ファイルの結合、分割、編集

すでに開いているドキュメントに対して、Document.merge()は他のDocumentインスタンスを現在のものに追加します：

from aspose_pdf import Document

base = Document("part1.pdf")
extra = Document("part2.pdf")

base.merge(extra)
base.save("combined.pdf", overwrite=True)

自分でDocumentを開かずにファイル間のワークフローを行う場合、ローコードのMergerとSplitterプラグインは、FileDataSource入力と出力から構築されたMergeOptions/SplitOptionsオブジェクトを受け取ります：

from aspose_pdf import Merger, MergeOptions, Splitter, SplitOptions, FileDataSource

# Merge two files into one
merge_options = MergeOptions()
merge_options.add_input(FileDataSource("part1.pdf"))
merge_options.add_input(FileDataSource("part2.pdf"))
merge_options.add_output(FileDataSource("combined.pdf"))
Merger().process(merge_options)

# Split the result into one file per page
split_options = SplitOptions()
split_options.add_input(FileDataSource("combined.pdf"))
split_options.add_output(FileDataSource("combined_page1.pdf"))
split_options.add_output(FileDataSource("combined_page2.pdf"))
Splitter().process(split_options)

PdfFileEditor は、例外を送出する代わりに True/False を返すファサードとして同じ操作群を提供します。バッチスクリプトに便利です：

from aspose_pdf import PdfFileEditor

with PdfFileEditor() as editor:
    ok = editor.concatenate(["part1.pdf", "part2.pdf"], "combined.pdf")
    if not ok:
        print("concatenate failed:", editor.last_exception)

    editor.extract("combined.pdf", "first_page_only.pdf", page_from=1, page_to=1)

PdfFileEditor.extract() and .insert() take 1ベース ページ番号は、…とは異なり PageCollectionの0ベースインデックス — 参照 一般的な問題 以下。

暗号化と文書セキュリティ

Document.encrypt(user_password, owner_password=None, permissions=-4) はメモリ上の文書を暗号化します；decrypt(password) と change_passwords(old, new_user, new_owner=None) はパスワードを逆転またはローテーションします。is_encrypted と permissions は現在の状態を報告します。

from aspose_pdf import Document
from aspose_pdf.exceptions import PdfSecurityException

doc = Document()
doc.pages.add()
doc.encrypt("user-pass", "owner-pass", permissions=-4)
doc.save("secured.pdf", overwrite=True)

try:
    Document("secured.pdf", password="wrong-pass")
except PdfSecurityException as exc:
    print("could not open:", exc)

reopened = Document("secured.pdf", password="user-pass")
print(reopened.is_encrypted)   # True
reopened.decrypt("user-pass")
reopened.save("unsecured.pdf", overwrite=True)

パスワードなしまたは誤ったパスワードで暗号化された文書を開くと PdfSecurityException が送出されます — 常にロードが成功すると思わず、aspose_pdf.exceptions からのこのクラスを捕捉してください。

メタデータ、検証、例外処理

文書メタデータは doc.info（プレーンな dict[str, str]）に格納され、doc.version / doc.id は PDF ヘッダーのバージョンとトレーラーファイル識別子を公開します。validate()（check() のエイリアス）は構造的整合性を報告します；repair() は欠落したページリストや範囲外の MediaBox など、一般的な問題の修正を試みます。

from aspose_pdf import Document, PdfLoadLimits
from aspose_pdf.exceptions import AsposePdfException, PdfIOException

doc = Document()
doc.pages.add()
doc.info["Title"] = "Quarterly Report"
doc.info["Author"] = "Reporting Bot"
doc.save("report.pdf", overwrite=True)

# Load untrusted input under an explicit resource-limit policy
safe_limits = PdfLoadLimits(max_input_bytes=50 * 1024 * 1024, max_pages=1000)

try:
    untrusted = Document("incoming.pdf", limits=safe_limits)
    if not untrusted.validate():
        untrusted.repair()
except (AsposePdfException, PdfIOException) as exc:
    print("failed to process incoming.pdf:", exc)

PdfLoadLimits は信頼できないファイルに対してメモリとオブジェクト数を上限設定します；ソースを完全に信頼する場合は PdfLoadLimits.unlimited() を呼び出してすべての制限を無効にします。AsposePdfException は例外階層全体（PdfIOException と PdfSecurityException を含む）の基底クラスであるため、単一の except AsposePdfException でライブラリが送出するすべてのエラーを捕捉できます。

ヒントとベストプラクティス

• 使用が終わったら、dispose()（またはclose()）をDocumentに対して必ず呼び出すか、短命なローカル変数として使用してください — エンジンはデコードされたページコンテンツと画像を破棄されるまでメモリに保持します。
• 同一実行内で既に作成したパスを書き換える際は、overwrite=Trueをsave()に渡してください；デフォルトはFalseで、FileExistsErrorを発生させます。
• 生成された PDF を配布する前に doc.optimize() を使用してください — それは未使用オブジェクトを削除し、ストリームを圧縮する単一の呼び出しで、通常、出力サイズを顕著に縮小します。
• 信頼できないソース（アップロード、メール添付、ウェブスクレイプ）から PDF を読み込む際は、必ず PdfLoadLimits ポリシーを明示的に設定してください；デフォルトは寛大ですが有限であり、盲目的に依存すべきセキュリティ境界ではありません。
• ロード/セーブ呼び出しの周囲では、裸の Exception ではなく、AsposePdfException（または PdfSecurityException のような特定のサブクラス）を捕捉してください — これがライブラリが発生させるすべてのエラーの共通基底です。

一般的な問題

FAQ

Aspose.PDF FOSS を Python に使用するためにライセンスが必要ですか？

いいえ。これはオープンソース（MIT ライセンス）版です。ライセンスファイルや有効化手順はありません。

Document を PDF 以外の形式にエクスポートできますか？

このリリースではサポートされていません。save() は PDF 出力のみを実装しています — 別の SaveFormat/DocFormat 値を渡すと、誤ったファイル名のファイルを生成する代わりに UnsupportedFeatureException が発生します。

Document.merge() と Merger プラグインの違いは何ですか？

Document.merge() は、メモリ上ですでに開いている Document インスタンスを結合します。Merger（MergeOptions と FileDataSource を使用）は、ファイル間の便利なラッパーで、1 回の呼び出しで開き、マージし、保存します — 中間の Document オブジェクトを必要としないシンプルなバッチスクリプトに便利です。

なぜ pages.insert() は範囲外インデックスで例外を発生させないのでしょうか？

PageCollection.insert() はインデックスを有効範囲にクランプします（負の値は 0 に、末尾を超える値は len(doc.pages) に）ので、例外は発生せず、インデックス値だけが原因で挿入が失敗することはありません。

信頼できないソースからPDFを安全にロードするにはどうすればよいですか？

明示的な上限（max_input_bytes、max_pages、max_objects など）を設定した PdfLoadLimits を構築し、それを Document(...) または load_from() の limits= 引数として渡します。各フィールドはすでに有限の既定値が設定されていますが、期待する入力サイズに合わせて上限を絞ることで、異常なファイルが消費できるリソースを減らすことができます。

API Reference の概要

参照

• API Reference：完全なクラスとメソッドのドキュメントは aspose_pdf
• ナレッジベース: タスク指向のハウツーガイド
• 製品概要: 機能と能力の概要
• はじめに / インストール: インストールとセットアップ
• Aspose.PDF for Python — Enterprise Documentation