Document (ドキュメント)#
このクラスはドキュメントを表します。ファイルまたはメモリから構築することができます。
このクラスには 「open」 というエイリアスが存在し、つまり、 pymupdf.Document(...)
と pymupdf.open(...)
はまったく同じことを行います。
埋め込まれたファイル の詳細については、付録3を参照してください。
注釈
バージョン1.17.0から、 EPUBファイル専用 の新しいページアドレッシングメカニズムがサポートされています。このドキュメントタイプは、ページがその「場所」によって最も効率的に見つけられるように、章ごとに内部的に組織されています。場所は (章、pno) というタプルで構成され、章番号と その章の中 のページ番号を指します。どちらの番号もゼロベースです。
依然として(絶対的な)番号を使用してページを見つけることは可能ですが、これを行うとページにアクセスする前に完全なEPUBドキュメントをレイアウトする必要があるかもしれません。これはドキュメントが非常に大きい場合、重要なパフォーマンスの影響を持つ可能性があります。ページの (章、pno) を使用することで、これを防ぐことができます。
一貫性のあるAPIを維持するために、PyMuPDFは すべてのファイルタイプ にページの場所構文をサポートしています - この機能のないドキュメントは単に1つの章を持っています。Document.load_page()
および同等のインデックスアクセスも 場所 引数をサポートしています。
ページ番号と場所の間で変換するためのいくつかのメソッドがあり、章の数を決定するためのメソッド、章ごとのページ数を決定するためのメソッド、次の場所と前の場所を計算するためのメソッド、およびドキュメントの最後のページの場所を計算するためのメソッドがあります。
メソッド / 属性 |
短い説明 |
---|---|
PDFのみ:新しいオプションコンテンツ設定を作成 |
|
PDFのみ:新しいオプションコンテンツグループを追加 |
|
暗号化されたドキュメントへのアクセスを取得 |
|
PDF only: make annotations / fields permanent content |
|
インクリメンタルセーブが可能かどうかを確認 |
|
章内のページ数 |
|
ドキュメントを閉じる |
|
PDFバージョンをメモリに書き込む |
|
PDFのみ:ページの参照をコピー |
|
PDFのみ:単一のTOCアイテムを削除 |
|
PDFのみ:ページを削除 |
|
PDFのみ:複数のページを削除 |
|
PDFのみ:バッファから新しい埋め込みファイルを追加 |
|
PDFのみ:埋め込みファイルの数 |
|
PDFのみ:埋め込みファイルエントリを削除 |
|
PDFのみ:埋め込みファイルバッファを抽出 |
|
PDFのみ:埋め込みファイルのメタデータ |
|
PDFのみ:埋め込みファイルのリスト |
|
PDFのみ:埋め込みファイルを変更 |
|
PDFのみ: |
|
PDFのみ: |
|
PDFのみ:異なるデフォルト値で |
|
レイアウトされたドキュメント後のページ位置を取得 |
|
PDFのみ:ページの複製 |
|
PDFのみ:ON、OFF、RBGroups内のOCGのリスト |
|
PDFのみ:オプションコンテンツ設定のリスト |
|
PDFのみ:画像/フォームオブジェクトのOCG / OCMD xrefを取得 |
|
PDFのみ:すべてのオプションコンテンツグループの情報 |
|
PDFのみ: |
|
PDFのみ:ページで参照されるフォントのリスト |
|
PDFのみ:ページで参照される画像のリスト |
|
PDFのみ:ページラベルの定義のリスト |
|
PDFのみ:指定されたラベルを持つページ番号を取得 |
|
ページ番号によるページのピクスマップの作成 |
|
ページ番号によるページのテキストの抽出 |
|
PDFのみ:ページで参照されるXObjectのリスト |
|
PDFのみ:署名状態を確認 |
|
目次を抽出 |
|
PDFのみ:XMLメタデータを読み込む |
|
PDFのみ:PDFに注釈が含まれているかを確認 |
|
PDFのみ:PDFにリンクが含まれているかを確認 |
|
PDFのみ:新しいページを挿入 |
|
PDFのみ:別のPDFからページを挿入 |
|
PDFのみ:任意のドキュメントからページを挿入 |
|
PDFのみ:どのジャーナルアクションが可能か |
|
PDFのみ:ドキュメントのジャーナルを有効にする |
|
PDFのみ:ファイルからジャーナルを読み込む |
|
PDFのみ:ジャーナルステップの名前を返す |
|
PDFのみ:ジャーナリングステータスを返す |
|
PDFのみ:現在の操作をやり直す |
|
PDFのみ:ジャーナルをファイルに保存 |
|
PDFのみ:名前を付けて「操作」を開始 |
|
PDFのみ:現在の操作を終了 |
|
PDFのみ:現在の操作を元に戻す |
|
PDFのみ:オプションコンテンツインテントのリスト |
|
ドキュメントを再ページ化(サポートされている場合) |
|
ページを読み込む |
|
リフローアブルドキュメント内でページポインタを作成 |
|
PDFのみ:ページをドキュメント内の異なる場所に移動 |
|
PDFのみ: |
|
PDFのみ:新しい空白ページを挿入 |
|
次のページの(章、pno) |
|
PDFのみ:TOCアイテムを |
|
PDFのみ:回転していないページの矩形 |
|
PDFのみ:ページ番号の |
|
ページ範囲のイテレータ |
|
PDFのみ:カタログ(ルート)の |
|
PDFのみ:トレイラーソース |
|
前のページの(章、pno)を返す |
|
PDFのみ:ページの新しいコピーを提供 |
|
PDF only: Convert destination names into a Python dict |
|
PDFのみ:ドキュメントを保存 |
|
PDFのみ:ドキュメントを増分保存 |
|
PDFのみ:機密データを削除 |
|
ページ上で文字列を検索 |
|
PDFのみ:ページのサブセットを選択 |
|
PDFのみ:一時的にOCGの表示を設定 |
|
PDFのみ:OCGステータスを一括変更 |
|
PDFのみ:MarkInfoの値を設定 |
|
PDFのみ:メタデータを設定 |
|
PDFのみ:画像/フォームオブジェクトにOCG/OCMDを添付 |
|
PDFのみ: |
|
PDFのみ:ページラベルの定義を追加/更新 |
|
PDFのみ:PageModeを設定 |
|
PDFのみ:PageLayoutを設定 |
|
PDFのみ:単一のTOCアイテムを変更 |
|
PDFのみ:目次(TOC)を設定 |
|
PDFのみ:ドキュメントXMLメタデータを作成または更新 |
|
PDFのみ:フォントのサブセットを作成 |
|
PDFのみ:OC設定をアクティブ化 |
|
PDFのみ:ドキュメントをメモリに書き込む |
|
PDFのみ:PDF辞書を別の |
|
PDFのみ:辞書キーの値を取得 |
|
PDFのみ: |
|
PDFのみ: |
|
PDFのみ:辞書キーの値を設定 |
|
PDFのみ: |
|
PDFのみ: XMLメタデータの |
|
章の数 |
|
PDFのみ:グローバルウィジェットフォントのリスト |
|
ドキュメントが閉じられていますか? |
|
PDFのみ:ドキュメントは変更されましたか? |
|
ドキュメントは(まだ)暗号化されていますか? |
|
PDFは線形化されていますか? |
|
これはフォームPDFですか? |
|
これはPDFですか? |
|
これはリフローアブルドキュメントですか? |
|
PDFのみ:このPDFは開いている間に修復されましたか? |
|
最後のページの(章、pno) |
|
メタデータ |
|
PDF MarkInfoの値 |
|
ドキュメントのファイル名 |
|
データにアクセスするにはパスワードが必要ですか? |
|
最初のアウトラインアイテム |
|
ページ数 |
|
ドキュメントへのアクセス権限 |
|
PDF PageModeの値 |
|
PDF PageLayoutの値 |
|
PDFバージョンの数 |
クラスAPI
- class Document#
- __init__(self, filename=None, stream=None, *, filetype=None, rect=None, width=0, height=0, fontsize=11)#
v1.14.13 で変更: メモリドキュメント用に
io.BytesIO
をサポート。v1.19.6 で変更: より明確で短く、一貫性のある例外メッセージ。ファイルタイプが指定されていない場合、常にファイルタイプ "pdf" が仮定されます。空のファイルとメモリ領域は常に例外を発生させます。
Document オブジェクトを作成します。
デフォルトのパラメータを使用すると、新しい空の PDF ドキュメントが作成されます。
stream が指定されている場合、ドキュメントはメモリから作成され、PDF でない場合は filename または filetype のいずれかがそのタイプを示さなければなりません。
stream が
None
の場合、filename で指定されたファイルからドキュメントが作成されます。そのタイプは拡張子から推測されます。これは filetype によって上書きできます。
- パラメータ:
filename (str,pathlib) -- ファイルパスを含む UTF-8 文字列または pathlib オブジェクト。ドキュメントのタイプはファイル名の拡張子から推測されます。存在しないか、サポートされてい ないタイプに一致しない場合、PDF ドキュメントが仮定されます。メモリドキュメントの場合、
filetype
の代わりにこの引数を使用できます。詳細は以下を参照してください。stream (bytes,bytearray,BytesIO) -- (bytes, bytearray, BytesIO) - サポートされている ドキュメントを含むメモリ領域。PDF でない場合、そのタイプは
filename
またはfiletype
のいずれかによって指定 しなければなりません 。filetype (str) -- ドキュメントのタイプを指定する文字列。ファイル名のように見えるもの(例: "x.pdf")である必要があります。この場合、MuPDF は拡張子を使用してタイプを判断します。application/pdf のような mime タイプも使用できます。単に "pdf" または ".pdf" のような文字列を使用することもできます。PDF ドキュメントの場合、省略可能であり、それ以外の場合は サポートされている ドキュメントタイプに一致しなければなりません。
rect (rect_like) -- 希望のページサイズを指定する矩形。このパラメータは可変ページレイアウト("reflowable" ドキュメント)を持つドキュメント(電子書籍や HTML のようなもの)にのみ意味があり、それ以外の場合は無視されます。指定される場合、非空で有限な矩形で、左上座標 (0, 0) を持っていなければなりません。fontsize パラメータと一緒に、各ページのレイアウトが適切に行われ、したがってページ数も決定されます。
width (float) -- レイアウト情報を指定するための rect の代替として、height と一緒に使用できます。
height (float) -- レイアウト情報を指定するための rect の代替として、width と一緒に使用できます。
fontsize (float) -- 可変ページドキュメントタイプのデフォルト
fontsize
。rect または width と height のいずれのパラメータも指定されていない場合、このパラメータは無視されます。ページレイアウトを計算するために使用されます。
- 例外:
TypeError -- 任意のパラメータの 型 が準拠していない場合。
FileNotFoundError -- ファイル/パスが見つからない場合。
RuntimeError
のサブクラスとして再実装されました。EmptyFileError -- ファイル/パスが空であるか、メモリ内の
bytes
オブジェクトの長さがゼロの場合。FileDataError
およびRuntimeError
のサブクラス。ValueError -- 明示的に未知のファイルタイプが指定された場合。
FileDataError -- ドキュメントが指定されたタイプに対して無効な構造を持っているか、ファイルではない場合(たとえば、フォルダの場合)。
RuntimeError
のサブクラス。
- 戻り値:
ドキュメントオブジェクト。ドキュメントを作成できない場合、上記の順序で例外が発生します。PyMuPDF固有の例外、
FileNotFoundError
、EmptyFileError
、およびFileDataError
は、RuntimeError
をチェックする場合にキャッチされます。問題が発生した場合、内部メッセージストアで詳細を確認できます:
print(pymupdf.TOOLS.mupdf_warnings())
(この呼び出しによって空にされますが、これを防ぐこともできます -Tools.mupdf_warnings()
を参照してください)。
注釈
すべてのドキュメントタイプがオープン時に有効なフォーマットで確認されるわけではありません。例えば、ラスター画像はコンテンツにアクセスしようとした際に例外を発生させることがあります。他のタイプ(特にバイナリでないコンテンツを持つもの)は、有効なコンテンツを持たない場合でも成功してオープンされ(そして時に アクセスされる こともあります):
HTM、HTML、XHTML: 常に オープンされ、
metadata["format"]
は "HTML5" または "XHTML" です。XML、FB2: 常に オープンされ、
metadata["format"]
は "FictionBook2" です。
可能なフォームの概要、注:
open
は Document (ドキュメント) の同義語です:>>> # from a file >>> doc = pymupdf.open("some.xps") >>> # handle wrong extension >>> doc = pymupdf.open("some.file", filetype="xps") >>> >>> # from memory, filetype is required if not a PDF >>> doc = pymupdf.open("xps", mem_area) >>> doc = pymupdf.open(None, mem_area, "xps") >>> doc = pymupdf.open(stream=mem_area, filetype="xps") >>> >>> # new empty PDF >>> doc = pymupdf.open() >>> doc = pymupdf.open(None) >>> doc = pymupdf.open("")
注釈
サポートされているが正しくないファイル拡張子を持つラスター画像は 問題ありません 。MuPDFは、ファイルの実際の 内容 がアクセスされると正しい画像タイプを判断し、何もクレームをつけずに処理します。したがって、
pymupdf.open("file.jpg")
はPNG画像でも機能します。Document クラスは コンテキストマネージャ としても使用できます。終了時に、ドキュメントは自動的に閉じられます。
>>> import pymupdf >>> with pymupdf.open(...) as doc: for page in doc: print("page %i" % page.number) page 0 page 1 page 2 page 3 >>> doc.is_closed True >>>
- get_oc(xref)#
v1.18.4 で新規追加
画像またはフォームXObjectに添付された
OCG
またはOCMD
のクロスリファレンス番号を返します。- パラメータ:
xref (int) -- 画像またはフォームXObjectの
xref
。有効なクロスリファレンス番号は、Document.get_page_images()
またはDocument.get_page_xobjects()
で返されます。無効な番号の場合、例外が発生します。- 戻り値の型:
int
- 戻り値:
オプションコンテンツオブジェクトのクロスリファレンス番号、または存在しない場合はゼロ。
- set_oc(xref, ocxref)#
v1.18.4 で新規追加
xref が画像またはフォームXObjectを表す場合、オプションコンテンツオブジェクトのクロスリファレンス番号 ocxref を設定または削除します。
- パラメータ:
xref (int) -- 画像またはフォームXObjectの
xref
[5]。有効なクロスリファレンス番号は、Document.get_page_images()
またはDocument.get_page_xobjects()
で返されます。無効な番号の場合、例外が発生します。ocxref (int) --
OCG
/OCMD
のxref
番号。ゼロでない場合、無効な参照は例外を発生させます。ゼロの場合、任意のOC参照が削除されます。
- get_layers()#
v1.18.3 で新規追加
オプションのレイヤー構成を表示します。常に標準のものが存在し、それは応答に含まれていません。
>>> for item in doc.get_layers(): print(item) {'number': 0, 'name': 'my-config', 'creator': ''} >>> # use 'number' as config identifier in add_ocg
- add_layer(name, creator=None, on=None)#
v1.18.3 で新規追加
オプションのコンテンツ構成を追加します。レイヤーはオプションコンテンツグループのON / OFFの状態のコレクションとして機能し、同じドキュメントの異なるビュー間での高速な表示切り替えを可能にします。
- パラメータ:
name (str) -- 任意の名前。
creator (str) -- (オプション)作成ソフトウェア。
on (sequ) -- このレイヤーがアクティブになったときにONに設定されるOCG
xref
番号のシーケンス。ここでリストされていないすべてのOCGはOFFに設定されます。
- switch_layer(number, as_default=False)#
v1.18.3 で新規追加
オプションレイヤーの構成番号によって定義されたドキュメントビューに切り替えます。これは一時的なものであり、デフォルトとして確立されていない限り、一時的なものです。
- パラメータ:
number (int) --
Document.layer_configs()
によって返される構成番号。as_default (bool) -- これをデフォルト構成にします。
識別されたレイヤーで定義されたOCGのON / OFFの状態をアクティブにします。 as_default=True の場合、追加で、標準のレイヤーを含むすべてのレイヤーがマージされ、結果が標準レイヤーに書き込まれ、 すべてのオプションレイヤーが削除されます 。
- add_ocg(name, config=-1, on=True, intent='View', usage='Artwork')#
v1.18.3 で新規追加
オプションコンテンツグループを追加します。OCGはオブジェクトの表示を決定するための最も重要な情報単位です。PDFでは、オプションコンテンツとして扱われるためには、少なくとも1つのOCGが存在する必要があります。
- パラメータ:
name (str) -- 任意の名前。サポートするPDFビューアに表示されます。
config (int) -- レイヤー構成番号。デフォルトは-1で、標準構成です。
on (bool) -- このOCGを指すオブジェクトの標準の表示状態。
intent (str,list) -- 表示意図を宣言する文字列または文字列のリスト。PDF標準の2つの値から選択できます: "View" と "Design"。デフォルトは "View" です。 正確なスペルが重要です 。
usage (str) -- OCGの表示に影響を与えるもう一つの要因。これはOCGの
/Usage
キーの一部になります。PDF標準の2つの値から選択できます: "Artwork" と "Technical"。デフォルトは "Artwork" です。必要な場合にのみ変更してください。
- 戻り値:
作成されたOCGの
xref
。サポートオブジェクトのoc
パラメータのエントリとして使用します。
注釈
同一のパラメータを持つ複数のOCGを作成することができます。これは問題を引き起こしません。
Document.save()
のゴミオプション3を使用すれば、重複を削除できます。
- set_ocmd(xref=0, ocgs=None, policy='AnyOn', ve=None)#
v1.18.4 で新規追加
OCMD
( Optional Content Membership Dictionary )を作成または更新します。- パラメータ:
- 戻り値の型:
int
- 戻り値:
OCMDの
xref
。サポートオブジェクトのoc=xref
パラメータとして使用し、Document.set_oc()
またはAnnot.set_oc()
にもそれぞれ使用します。
注釈
OCGと同様に、OCMDには表示状態ONまたはOFFがあり、OCGのように使用できます。OCGとは異なり、OCMDの状態は ブール式 の特別な形式を使用して1つ以上のOCGの状態を評価することによって決定されます。式がtrueに評価される場合、OCMDの状態はONで、falseに評価される場合はOFFです。
OCMDの表示を定式化する方法は2つあります:
ocgs と policy の組み合わせを使用する: policy の値は次のように解釈されます:
(デフォルト) 少なくとも1つのOCGがONの場合、true。
少なくとも1つのOCGがOFFの場合、true。
すべてのOCGがONの場合、true。
すべてのOCGがOFFの場合、true。
2つのPDFオブジェクトを、必ず1つずつ表示するようにしたい場合(1つがONの場合、他の1つはOFFにする必要があります):
解決策: オブジェクト1用のOCGとオブジェクト2用のOCMDを使用します。 OCMDは
set_ocmd(ocgs=[xref], policy="AllOff")
を使用して作成し、OCGのxref
を指定します。表示条件式 ve を使用する: これは2つ以上のアイテムから成るリストです。 最初のアイテム は論理キーワードで、文字列 "and" 、"or" 、または "not" のいずれかです。2番目以降のアイテムは整数または別のリストである必要があります。整数はOCGの
xref
番号でなければなりません。リストは再び少なくとも2つのアイテムから始まり、ブールキーワードのいずれかで始まる必要があります。この構文はやや厄介ですが、非常に強力です:
各リストは論理キーワードで始まる必要があります。
キーワードが "not" の場合、リストは正確に2つのアイテムを持たなければなりません。 "and" または "or" の場合、その後にいくつでも他のアイテムが続くことができます。
論理キーワードの後に続くアイテムは、整数または再びリストである必要があります。 整数 はOCGのxref番号でなければなりません。 リスト は前述のルールに従う必要があります。
例:
set_ocmd(ve=["or", 4, ["not", 5], ["and", 6, 7]])
。これは次の条件がtrueの場合にONを返します: "4がON、または5がOFF、または6と7が両方ON "。set_ocmd(ve=["not", xref])
。これは1で作成されたOCMDの例と同じ効果があります。
詳細と例については、 Adobe PDFリファレンス の224ページを参照してください。また、こちら の例のスクリプトもご覧いただけます。
表示条件式
/VE
はPDF仕様バージョン1.6の一部です。したがって、すべてのPDFビューア/リーダーがすでにこの機能をサポートしているわけではなく
- get_ocmd(xref)#
v1.18.4 で新規追加
OCMD
の定義を取得します。- パラメータ:
xref (int) --
xref
(int)- OCMDのxref。- 戻り値の型:
dict
- 戻り値:
xref 、ocgs 、policy、ve のキーを持つ辞書
- get_layer(config=-1)#
v1.18.3 で新規追加
指定された構成内のステータス別オプションコンテンツグループのリスト。これは、OCGsのクロスリファレンス番号のリストを持つ辞書で、
/ON
、/OFF
、またはラジオボタングループ (/RBGroups
) のいずれかに出現するOCGsに対応しています。- パラメータ:
config (int) -- 構成レイヤー(デフォルトは標準の構成レイヤー)。
>>> pprint(doc.get_layer()) {'off': [8, 9, 10], 'on': [5, 6, 7], 'rbgroups': [[7, 10]]} >>>
- set_layer(config, *, on=None, off=None, basestate=None, rbgroups=None, locked=None)#
v1.18.3 で新規追加
バージョン1.22.5で変更: ロックされた OCGのリストをサポート。
オプションコンテンツグループの大量ステータス変更。OCGのステータスを 永続的に 設定します。
- パラメータ:
config (int) -- 希望の構成レイヤー、デフォルトのものには-1を選択します。
on (list) -- ONに設定するOCGの
xref
のリスト。以前の値を置換します。空のリストはもうOCGをONに設定しなくなります。basestate="ON"
が使用される場合は指定する必要があります。off (list) -- OFFに設定するOCGの
xref
のリスト。以前の値を置換します。空のリストはもうOCGをOFFに設定しなくなります。basestate="OFF"
が使用される場合は指定する必要があります。basestate (str) -- on または off で言及されていないOCGの状態。可能な値は「ON」、「OFF」または「Unchanged」です。大文字/小文字を区別できます。
rbgroups (list) -- リストのリスト。以前の値を置換します。各サブリストには2つ以上のOCG xrefを含める必要があります。同じサブリスト内のOCGはラジオボタングループ内のボタンのように処理され、1つをONに設定すると他のすべてのグループメンバーがOFFに設定されます。
locked (list) -- ユーザーインターフェースで変更できないOCG xref番号のリスト。
値
None
は対応するPDF配列を変更しません。>>> doc.set_layer(-1, basestate="OFF") # only changes the base state >>> pprint(doc.get_layer()) {'basestate': 'OFF', 'off': [8, 9, 10], 'on': [5, 6, 7], 'rbgroups': [[7, 10]]}
- get_ocgs()#
v1.18.3 で新規追加
オプションコンテンツグループの詳細情報。これは次のような辞書の辞書です(キーはOCGの
xref
です):>>> pprint(doc.get_ocgs()) {13: {'on': True, 'intent': ['View', 'Design'], 'name': 'Circle', 'usage': 'Artwork'}, 14: {'on': True, 'intent': ['View', 'Design'], 'name': 'Square', 'usage': 'Artwork'}, 15: {'on': False, 'intent': ['View'], 'name': 'Square', 'usage': 'Artwork'}} >>>
- layer_ui_configs()#
v1.18.3 で新規追加
サポートするPDFビューアのユーザーインターフェースで変更可能なオプションコンテンツの表示状態を表示します。
現在選択されているレイヤー設定に含まれるアイテムのみを報告します。
- 辞書のキーの意味は次の通りです:
depth:
/Order
配列内のアイテムのネストレベルlocked: ユーザーインターフェースを介して変更できない場合はtrue
number: 連続するシーケンス番号
on: アイテムの状態
text: 元のOCGのテキスト文字列または名前フィールド
type: "label"(テキスト文字列によって設定)、"checkbox"(単一のOCGによって設定)、または "radiobox"(接続されたOCGのセットによって設定)のいずれか
- set_layer_ui_config(number, action=0)#
v1.18.3 で新規追加
コンテンツグループのOC表示状態を変更します。これは、サポートするPDFビューアが提供するものと同様です。
表示状態はOCGとして保存されるプロパティ ではない ことに注意してください。それはPDFドキュメントに必ずしも存在しない情報でもありません。代わりに、現在の表示状態はサポートするPDF消費者ソフトウェアのユーザーインターフェースを使用して**一時的に** 設定されます。このメソッドでも同じタイプの機能が提供されます。
永続的な 変更を行うには、
Document.set_layer()
を使用してください。- パラメータ:
number (int,str) --
Document.layer_configs()
リストのアイテムのシーケンス番号またはこれらのアイテムの「テキスト」。action (int) --
PDF_OC_ON
= ONに設定(デフォルト)、PDF_OC_TOGGLE
= ON/OFFを切り替え、PDF_OC_OFF
= OFFに設定。
- authenticate(password)#
文字列の パスワード でドキュメントを複合化します。成功した場合、ドキュメントデータにアクセスできます。PDFドキュメントの場合、「オーナー」および「ユーザー」には異なる特権があり、したがってこれらの認証レベルに異なるパスワードが存在する可能性があります。このメソッドは提供されたパスワードに適切な(オーナーまたはユーザー)アクセス権を自動的に確立します。
- パラメータ:
password (str) -- オーナーまたはユーザーパスワード。
- 戻り値の型:
int
- 戻り値:
成功した場合は正の値、それ以外はゼロです(文字列がどちらのパスワードとも一致しない場合)。正の戻り値がある場合、インジケータ
Document.is_encrypted
は False に設定されます。正の 戻り値コードには、次の情報の詳細が含まれています:1 => 認証済み、ただしPDFにはオーナーまたはユーザーパスワードがありません。
2 => ユーザー パスワードで認証済み。
4 => オーナー パスワードで認証済み。
6 => 認証済みで両方のパスワードが等しい-おそらくまれな状況
注釈
ドキュメントはオーナーによって保護されている場合でも、ユーザーパスワードによって保護 されていない 場合があります。この状況は、
doc.authenticate("") == 2
を使用して検出できます。これにより、認証なしでドキュメントを開いて読むことができますが、Document.permissions
値に応じて、他のアクションが制限される場合があります。この場合、PyMuPDF(MuPDFと同様)はこれらの 制限を無視します 。したがって、PDF_PERM_COPY
、PDF_PERM_MODIFY
、PDF_PERM_ANNOTATE
などの対応する許可フラグがオフに設定されていても、テキストを抽出したり、コンテンツを追加または変更したりすることができます!該当する場合、法的に適合するアプリケーションを構築する責任があります。
- get_page_numbers(label, only_one=False)#
バージョン 1.18.6 での新機能
PDF のみ:指定されたラベルを持つページ番号のリストを返します。ラベルは PDF では一意でないことがあることに注意してください。これは、すべてのページ番号 を逐次検索してそのラベルを比較することを意味します。
注釈
実装の詳細 - この目的でページは 読み込まれません 。
- パラメータ:
label (str) -- 検索対象のラベル、例: "vii"(ローマ数字 7)。
only_one (bool) -- 最初の一致で停止します。ラベリングが一意であることがわかっている場合や、多くのページがある場合などに便利です。デフォルトではすべてのページ番号をチェックします。
- 戻り値の型:
list
- 戻り値:
このラベルを持つページ番号のリスト。見つからない場合やラベルが定義されていない場合などは空です。
- get_page_labels()#
バージョン 1.18.7 での新機能
PDF のみ:ページラベルの定義のリストを抽出します。通常は
Document.set_page_labels()
に渡す前の変更に使用されます。- 戻り値:
Document.set_page_labels()
で定義されたように辞書のリスト。
- set_page_labels(labels)#
バージョン 1.18.6 での新機能
PDF のみ:PDF のページラベルの定義を追加または更新します。
- パラメータ:
labels (list) --
辞書のリスト。各辞書はラベル構築ルールと 0 ベースの "start" ページ番号を定義します。その開始ページはラベル定義が有効になる最初のページです。各辞書は最大 4 つの項目を持ち、
{'startpage': int, 'prefix': str, 'style': str, 'firstpagenum': int}
という形式で、次の項目を持ちます。startpage
:(int)ラベルルールを適用する最初のページ番号(0 ベース)。このキーは 存在する必要があります 。ルールはドキュメントの終端に達するか、次の大きなページ番号を持つルールに置き換えられるまで、すべての後続ページに適用されます。prefix
:(str)ラベルの先頭に付ける任意の文字列、例: "A-"。デフォルトは "" です。style:(str)番号付けのスタイル。使用できるのは "D"(10 進数)、"r"/"R"(ローマ数字、小文字/大文字)、および "a"/"A"(小文字/大文字のアルファベット番号: "a" から "z"、次に "aa" から "zz" など)。デフォルトは "" です。 "" の場合、番号付けは行われず、その範囲のページはプレフィックス値から成る同じラベルを受け取ります。
prefix
も省略された場合、ラベルは "" になります。firstpagenum
:(int)この値から番号付けを開始します。デフォルトは 1 で、小さい値は無視されます。
例:
[{'startpage': 6, 'prefix': 'A-', 'style': 'D', 'firstpagenum': 10}, {'startpage': 10, 'prefix': '', 'style': 'D', 'firstpagenum': 1}]
次のラベルを生成します: "A-10"、"A-11"、"A-12"、"A-13"、"1"、"2"、"3"、... ページ 6、7、など、ドキュメントの終了まで続きます。ページ 0 から 5 まではラベル "A-" が付きます。
- make_bookmark(loc)#
バージョン 1.17.3 での新機能
リフロータブルなドキュメント内のページポインターを返します。ドキュメントの再レイアウト後、このメソッドの結果はページの新しい位置を見つけるために使用できます。
注釈
目次の項目とは混同しないでください。
- パラメータ:
loc (list,tuple) -- ページの位置。有効なものである必要があります (章、ページ番号) 。
- 戻り値の型:
pointer
- 戻り値:
ポインターフォーマットの長整数。ドキュメントの再レイアウト後のページの新しい位置を見つけるために使用されます。変更しないでください。
- find_bookmark(bookmark)#
バージョン 1.17.3 での新機能
ドキュメントの再レイアウト後の新しいページの位置を返します。
- パラメータ:
bookmark (pointer) --
Document.make_bookmark()
によって作成されたもの。- 戻り値の型:
tuple
- 戻り値:
ページの新しい(章、ページ番号)。
- chapter_page_count(chapter)#
バージョン 1.17.0 での新機能
章のページ数を返します。
- パラメータ:
chapter (int) -- 0 ベースの章番号。
- 戻り値の型:
int
- 戻り値:
章内のページ数。章のサポートを持つドキュメントタイプに関連します(現在は EPUB のみ)。
- next_location(page_id)#
バージョン 1.17.0 での新機能
次のページの位置を返します。
- パラメータ:
page_id (tuple) -- 現在のページ ID。これは既存のページを識別するタプル (章、ページ番号) である必要があります。
- 戻り値:
次のページのタプル、つまり (章、ページ番号 + 1) または (章 + 1、0) 、または 引数が最後のページである場合は空のタプル () 。章のサポートを持つドキュメントタイプに関連します(現在は EPUB のみ)。
- prev_location(page_id)#
バージョン 1.17.0 での新機能
前のページの位置を返します。
- パラメータ:
page_id (tuple) -- 現在のページ ID。これは既存のページを識別するタプル (章、ページ番号) である必要があります。
- 戻り値:
前のページのタプル、つまり (章、ページ番号 - 1) または 前の章の最後のページ、または引数が最初のページである場合は空のタプル () 。章のサポートを持つドキュメントタイプに関連します(現在は EPUB のみ)。
- load_page(page_id=0)#
バージョン 1.17.0 で変更: "章の構造" をサポートするドキュメントタイプ(例:EPUB)の場合、絶対ページ番号の代わりに章番号と相対ページ番号の組み合わせを使用してページをロードすることもできます。これにより、大きなドキュメントへの アクセスが大幅に高速化される はずです。
さらなる処理(レンダリング、テキスト検索など)のための Page (ページ) オブジェクトを作成します。
- パラメータ:
page_id (int,tuple) --
(バージョン 1.17.0 で変更)
0ベースのページ番号またはタプル (章、ページ番号) のいずれか。整数 の場合、
-∞ < page_id < page_count
が許容されます。page_id
が負の場合、page_count
が追加されます。たとえば、最後のページを読み込むには、doc.load_page(-1) を使用できます。これにより、page.number = doc.page_count - 1
となります。タプルの場合、chapter は
Document.chapter_count
の範囲内になければならず、ページ番号 はその章のDocument.chapter_page_count()
の範囲内になければなりません。両方の値は0から始まります。この表記法を使用すると、Page.number
は指定されたタプルに等しくなります。章のサポートを持つドキュメントタイプに関連します(現在は EPUB のみ)。- 戻り値の型:
注釈
ドキュメントはページ番号をインデックスとするPythonのシーケンスプロトコルに従います:indices: doc.load_page(n) == doc[n] 。
絶対ページ番号 の場合、式 "for page in doc: …" および "for page in reversed(doc): …" は文書のページを順次生成します。スライシングのようにページを処理できる
Document.pages()
を参照してください。新しい章ベースのページ識別にもインデックス表記を使用できます: page = doc[(5, 2)] として、 6番目の章の3番目のページを読み込むことができます。
一貫性のあるAPIを維持するため、章の構造をサポートしていないドキュメントタイプ(PDFなど)の場合、
Document.chapter_count
は1であり、ページはタプル (0、pno) を使用しても読み込むことができます。パフォーマンスの改善に関するコメントについては、この [3] の注釈を参照してください。- reload_page(page)#
バージョン 1.16.10 での新機能
PDF のみ:保留中のすべての変更を終了および更新した後、ページの新しいコピーを提供します。
- パラメータ:
page (Page (ページ)) -- ページオブジェクト。
- 戻り値の型:
- 戻り値:
同じページの新しいコピー。すべての保留中の更新(注釈やウィジェットなど)が確定し、ページの新しいコピーが読み込まれます。
注釈
典型的なユースケースでは、注釈やウィジェットが追加または変更された後にページの Pixmap を取得する必要があります。これらの変更がページ構造に反映されるようにするために、このメソッドは "document -> page -> annotations/widgets" のオブジェクト階層を保持したまま、新しいコピーを再設定します。
- resolve_names()#
PDFのみ: ページの目的地名をPythonの辞書に変換します
- 戻り値:
以下のキーを持つ辞書:
キー: (str) 名前
- 以下のキーを持つ辞書:
"page": 対象のページ番号(0から始まる)。ページ番号が見つからない場合は-1。
"to": (x, y) ページ上のターゲットポイント。現在はPDF座標であり、つまり点(0,0)がページの左下になります。
"zoom": ターゲットページ上のズームファクター(float)。
"dest": (str) "/XYZ" としてターゲット位置が指定されていない場合や、ページ番号が見つからない場合にのみ存在します。
例:
{ '__bookmark_1': {'page': 0, 'to': (0.0, 541.0), 'zoom': 0.0}, '__bookmark_2': {'page': 0, 'to': (0.0, 481.45), 'zoom': 0.0}, }
または:
{ '21154a7c20684ceb91f9c9adc3b677c40': {'page': -1, 'dest': '/XYZ 15.75 1486 0'}, ... }
キー "/Dests" および "/Names/Dests" の下でカタログ内に見つかるすべての名前が含まれます。
v1.23.6で新登場
- page_cropbox(pno)#
バージョン 1.17.7 での新機能
PDF のみ:ページを読み込まずに(
Document.load_page()
を介さずに)、回転を無視してページの長方形を返します。これは、最高のパフォーマンスを必要とする内部目的のために使用されます。- パラメータ:
pno (int) -- 0から始まるページ番号。
- 戻り値:
Page.rect()
のようなページの Rect (矩形) ですが、回転を無視します。
- page_xref(pno)#
バージョン 1.17.7 での新機能
PDF のみ: ページを読み込まずに (
Document.load_page()
を介さずに)、ページのxref
を返します。これは、最高のパフォーマンスを必要とする内部目的のために使用されます。
- pages(start=None[, stop=None[, step=None]])#
バージョン 1.16.4 での新機能
一連のページのためのジェネレーター。パラメーターの意味は組み込みの range() 関数と同じです。 "for page in doc.pages(start, stop, step): …" の形式の式に使用することを意図しています。
- パラメータ:
start (int) -- このページ番号から反復を開始します。デフォルトはゼロで、許容値は
-∞ < start < page_count
です。負の値の間は反復を開始する 前にpage_count
が追加されます。stop (int) -- このページ番号で反復を停止します。デフォルトは
page_count
で、可能な値は-∞ < stop <= page_count
です。大きな値はデフォルトで 静かに置き換えられます 。負の値は逆順でページを循環的に生成します。組み込みの range() 関数と同様に、これは 返されない 最初のページです。step (int) -- ステップ値。start < stop の場合はデフォルトで1、start > stop の場合は-1です。ゼロは許可されていません。
- 戻り値:
ドキュメントのページに対するジェネレーターイテレーターです。いくつかの例:
"doc.pages()" はすべてのページを生成します。
"doc.pages(4, 9, 2)" はページ4、6、8を生成します。
"doc.pages(0, None, 2)" はすべての偶数ページを生成します。
"doc.pages(-2)" は最後の2ページを生成します。
"doc.pages(-1, -1)" は逆の順序ですべてのページを生成します。
"doc.pages(-1, -10)" は常に逆の順序で10ページを生成し、最後のページから始まり、ドキュメントが10ページ未満の場合は 繰り返し 生成します。したがって、4ページのドキュメントの場合、次のページ番号が生成されます: 3、2、1、0、3、2、1、0、3、2、1、0、3。
- convert_to_pdf(from_page=-1, to_page=-1, rotate=0)#
現在のドキュメントのPDFバージョンを作成し、メモリに書き込みます。すべてのドキュメントタイプ がサポートされています。パラメータは
insert_pdf()
と同じ意味を持ちます。 基本的に、ページのサブセットに変換を制限し、ページの回転を指定し、ページの順序を逆にすることができます。- パラメータ:
from_page (int) -- コピーする最初のページ(0ベース)。デフォルトは最初のページです。
to_page (int) -- コピーする最後のページ(0ベース)。デフォルトは最後のページです。
rotate (int) -- 回転角度。デフォルトは0度(回転なし)です。整数n(チェックされていない)で n * 90 である必要があります。
- 戻り値の型:
bytes
- 戻り値:
PDFファイルイメージを含むPythonの bytes オブジェクト。内部的に
tobytes(garbage=4, deflate=True)
を使用して作成されます。tobytes()
を参照してください。これを直接ディスクに出力するか、PDFとして開くことができます。以下にいくつかの例を示します:>>> # convert an XPS file to PDF >>> xps = pymupdf.open("some.xps") >>> pdfbytes = xps.convert_to_pdf() >>> >>> # either do this --> >>> pdf = pymupdf.open("pdf", pdfbytes) >>> pdf.save("some.pdf") >>> >>> # or this --> >>> pdfout = open("some.pdf", "wb") >>> pdfout.tobytes(pdfbytes) >>> pdfout.close()
>>> # copy image files to PDF pages >>> # each page will have image dimensions >>> doc = pymupdf.open() # new PDF >>> imglist = [ ... image file names ...] # e.g. a directory listing >>> for img in imglist: imgdoc=pymupdf.open(img) # open image as a document pdfbytes=imgdoc.convert_to_pdf() # make a 1-page PDF of it imgpdf=pymupdf.open("pdf", pdfbytes) doc.insert_pdf(imgpdf) # insert the image PDF >>> doc.save("allmyimages.pdf")
注釈
このメソッドは、mutool convert CLIと同じロジックを使用しています。これはほとんどの場合非常にうまく機能しますが、以下の制限に注意してください。
画像ファイル: 完璧で、問題は検出されません。ただし、画像の透明度は無視されます。透明度が必要な場合(ウォーターマークなど)、代わりに
Page.insert_image()
を使用してください。それ以外の場合、このメソッドははるかに優れたパフォーマンスのために推奨されます。XPS: 外観は非常に良好です。リンクは正常に機能し、アウトライン(ブックマーク)は失われますが、簡単に回復できます [2]。
EPUB、CBZ、FB2: XPSと類似しています。
SVG: 中程度です。おおよそ svglib と比較できます。
- get_toc(simple=True)#
ドキュメントのアウトラインチェーンから目次(TOC)を作成します。
- パラメータ:
simple (bool) -- 簡単なTOCまたは詳細なTOCが必要かを示す値です。False の場合、リストの各アイテムにはアウトラインエントリごとの linkDest の詳細を含む辞書も含まれます。
- 戻り値の型:
list
- 戻り値:
リストのリスト。各エントリは次の形式を持っています: [lvl, title, page, dest] 。そのエントリは次の意味を持っています:
lvl – 階層レベル(正の整数)。最初のエントリは常に1です。行内のエントリは 等しい か、1ずつ 増加 または任意の数で 減少 します。
title – タイトル(str)
page – 1から始まるページ番号(int)。
-1
の場合、宛先なしまたはドキュメント外。dest – (dict) simple=False の場合のみ含まれます。TOCアイテムの詳細が以下のように含まれます:
kind: 宛先の種類、リンクの目的の種類 を参照。
file:
kind
がLINK_GOTOR
またはLINK_LAUNCH
の場合のファイル名。page: ターゲットページ、0ベース、
LINK_GOTOR
またはLINK_GOTO
の場合のみ。to: ターゲットページ上の位置 (Point (ポイント))。
zoom: ターゲットページ上のズームファクター(float)。
xref: アイテムの
xref
(PDFがない場合は0)。color: PDF RGB形式
(red, green, blue)
のアイテムカラー、または省略(PDFがない場合は常に省略)。bold: アイテムテキストが太字の場合、または省略。PDFのみ。
italic: アイテムテキストがイタリックの場合、または省略。PDFのみ。
collapse: サブアイテムが折りたたまれている場合、または省略。PDFのみ。
nameddest: target name if kind=4. PDF only. (New in 1.23.7.)
- xref_get_keys(xref)#
バージョン 1.18.7 での新機能
PDFのみ: xref番号で提供される
dictionary
オブジェクトのPDF辞書キーを返します。- パラメータ:
xref (int) --
xref
。 (v1.18.10で変更) "PDF trailer" としてアクセスするには-1
を使用します。- 戻り値:
xref
オブジェクトに存在する辞書キーのタプル。例:>>> from pprint import pprint >>> import pymupdf >>> doc=pymupdf.open("pymupdf.pdf") >>> xref = doc.page_xref(0) # xref of page 0 >>> pprint(doc.xref_get_keys(xref)) # primary level keys of a page ('Type', 'Contents', 'Resources', 'MediaBox', 'Parent') >>> pprint(doc.xref_get_keys(-1)) # primary level keys of the trailer ('Type', 'Index', 'Size', 'W', 'Root', 'Info', 'ID', 'Length', 'Filter') >>>
- xref_get_key(xref, key)#
バージョン 1.18.7 での新機能
PDFのみ: xrefによって提供される
dictionary
オブジェクトのPDF辞書キーの戻り値の型と値を返します。- パラメータ:
xref (int) --
xref
。v1.18.10で変更: 特別な辞書 "PDF trailer" にアクセスするには-1
を使用します。key (str) -- 望ましいPDFキー。
Document.xref_get_keys()
に含まれるキーのいずれかと厳密に一致する必要があります(大文字と小文字を区別します)。
- 戻り値の型:
tuple
- 戻り値:
文字列のタプル(type、value)、ここでtypeは次のいずれかです: "xref"、"array"、"dict"、"int"、"float"、"null"、"bool"、"name"、"string" または "unknown"(発生しないはず)。"type" に関係なく、キーの値は 常に 文字列としてフォーマットされます – 以下の例を参照 – そして(ほとんどの場合)PDFに格納されている内容の忠実な反映です。ほとんどの場合、値文字列のフォーマットもキーのタイプについてのヒントを提供します:
"name" は常に "/" スラッシュで始まります。
"xref" は常に " 0 R" で終わります。
"array" は常に "[...]" 角括弧で囲まれています。
"dict" は常に "<<...>>" 角括弧で囲まれています。
"bool" または "null" は常に "true"、"false" または "null" のいずれかです。
"float" と "int" は文字列形式で表され、したがって常に区別できるわけではありません。
"string" はUTF-8に変換され、したがってPDFに格納されている内容と異なる場合があります。たとえば、PDFキー "Author" はファイル内で "FEFF004A006F0072006A00200058002E0020004D0063004B00690065" という値を持つかもしれませんが、このメソッドは
('string', 'Jorj X. McKie')
を返します。>>> for key in doc.xref_get_keys(xref): print(key, "=" , doc.xref_get_key(xref, key)) Type = ('name', '/Page') Contents = ('xref', '1297 0 R') Resources = ('xref', '1296 0 R') MediaBox = ('array', '[0 0 612 792]') Parent = ('xref', '1301 0 R') >>> # >>> # Now same thing for the PDF trailer. >>> # It has no xref, so -1 must be used instead. >>> # >>> for key in doc.xref_get_keys(-1): print(key, "=", doc.xref_get_key(-1, key)) Type = ('name', '/XRef') Index = ('array', '[0 8802]') Size = ('int', '8802') W = ('array', '[1 3 1]') Root = ('xref', '8799 0 R') Info = ('xref', '8800 0 R') ID = ('array', '[<DC9D56A6277EFFD82084E64F9441E18C><DC9D56A6277EFFD82084E64F9441E18C>]') Length = ('int', '21111') Filter = ('name', '/FlateDecode') >>>
- xref_set_key(xref, key, value)#
バージョン1.18.7で新規追加、バージョン1.18.13で変更されました。
バージョン1.19.4で変更: "null" に設定された場合、キーを "物理的に" 削除します。
PDFのみ: xrefによって提供される
dictionary
オブジェクトのPDFキーの値を設定(追加、更新、削除)します。注意
これはエキスパート向けの機能です。何をしているのかわからない場合、PDFの(一部の)使用不能の高いリスクがあります。PDFオブジェクト仕様フォーマット(ページ18)やページオブジェクトなどの特別な辞書タイプの構造については Adobe PDFリファレンス を参照してください。
- パラメータ:
xref (int) --
xref
。バージョン1.18.13で変更: PDFトレーラーを更新する場合、-1を指定します。key (str) -- 望ましいPDFキー(先頭の "/" なし)。空であってはいけません。既にオブジェクト内に存在するかどうかに関係なく、新しいPDFキーでも構いません。PDFパス表記 (
"Resources/ExtGState"
のような)を使用して、"/Resources"
のサブオブジェクトとしてキー"/ExtGState"
の値を設定することも可能です。value (str) -- キーの値。空でない文字列である必要があり、望ましいPDFオブジェクトのタイプに応じて以下のルールを守る必要があります。一部の構文チェックは行われますが、型チェックやPDFとして意味があるかどうかのチェックは行われません。大文字と小文字の区別が重要です!
xref – 有効なPDFのxref番号nnnを持つ
"nnn 0 R"
として提供される必要があります。サフィックス "0 R
" はPDFアプリケーションによってxref
として認識されるため必要です。array –
"[a b c d e f]"
のような文字列。角括弧が必要です。配列の要素は少なくとも1つのスペースで区切られている必要があります(Pythonのようなカンマではありません)。空の配列"[]"
も可能で、キーを削除することと 同等 です。配列のアイテムは、辞書、xref、他の配列など、PDFオブジェクトである必要があります。Pythonと同様に、配列のアイテムは異なるタイプである場合があります。dict –
"<< ... >>"
のような文字列。角括弧が必要で、有効なPDF辞書定義を囲む必要があります。空の辞書"<<>>"
も可能で、キーを削除することと 同等 です。int – 文字列として フォーマットされた整数。
float – 文字列としてフォーマットされた浮動小数点数。科学的表記法(指数を含む)は PDFでは許可されていません 。
null – 文字列
"null"
。これはPythonのNone
に相当し、キーを無視させますが、必ずしも削除されるわけではありません。ガベージコレクションを伴う保存時に削除される場合があります。バージョン1.19.4で変更: キーがパス階層でない場合(つまりスラッシュ "/" を含まない場合)、それは完全に削除されます。bool –
"true"
または"false"
のいずれかの文字列。name –
"/PageLayout"
のように先頭にスラッシュを持つ有効なPDF名。Adobe PDFリファレンス のページ16を参照してください。string – 有効なPDF文字列。 すべてのPDF文字列は角括弧で囲まれている必要があります 。空の文字列は
"()"
として表記されます。内容に応じて、可能な角括弧は次の通りです。"(…)":ASCIIのテキストの場合。予約されたPDF文字はバックスラッシュでエスケープし、非ASCII文字は先頭にゼロパディングされた3桁のバックスラッシュエスケープの8進数で提供する必要があります。例: 12 = 0x0C は
014
としてエンコードする必要があります。"<…>":16進数でエンコードされたテキストの場合。各文字は2桁の16進数で表されなければなりません(大文字または小文字)。
疑念がある場合は、
get_pdf_str()
の使用を**強くお勧めします**!この関数は自動的に適切な角括弧、エスケープ、および全体のフォーマットを生成します。たとえば、次のような変換を行います。>>> # because of the € symbol, the following yields UTF-16BE BOM >>> pymupdf.get_pdf_str("Pay in $ or €.") '<feff00500061007900200069006e002000240020006f0072002020ac002e>' >>> # escapes for brackets and non-ASCII >>> pymupdf.get_pdf_str("Prices in EUR (USD also accepted). Areas are in m².") '(Prices in EUR \\(USD also accepted\\). Areas are in m\\262.)'
- get_page_pixmap(pno: int, *, matrix: matrix_like = Identity, dpi=None, colorspace: Colorspace = csRGB, clip: rect_like = None, alpha: bool = False, annots: bool = True)#
pno (ゼロベース)のページからピクスマップを作成します。
Page.get_pixmap()
を呼び出します。pno
以外のすべてのパラメーターは キーワード専用 です。- パラメータ:
pno (int) -- pno (int) – ページ番号、ゼロベース、
-∞ < pno < page_count
。- 戻り値の型:
- get_page_xobjects(pno)#
バージョン1.16.13で新規追加
バージョン1.18.11で変更
PDFのみ: ページによって参照されるすべてのXObjectのリストを返します。
- パラメータ:
pno (int) -- ページ番号、ゼロベース、
-∞ < pno < page_count
。- 戻り値の型:
list
- 戻り値:
(画像でない)XObjectのリスト。これらのオブジェクトは通常、他のPDFから 埋め込まれた (コピーされていない)ページを表します。例えば、
Page.show_pdf_page()
はこのタイプのオブジェクトを作成します。このリストのアイテムは以下のレイアウトを持っています:(xref, name, invoker, bbox)
、ここでxref (int) はXObjectの
xref
です。name (str) はXObjectを参照するための象徴的な名前です。
invoker (int) は、ページがそれを直接呼び出す場合はゼロ、それ以外の場合は呼び出し元XObjectの
xref
です。bbox (Rect (矩形)) はXObjectのページ上の位置の境界ボックスで、変換されていない座標で 表されます。実際の、回転していないページ座標を取得するには、ページの変換行列
Page.transformation_matrix
を掛けてください。バージョン1.18.11で変更: bbox は今や Rect (矩形) としてフォーマットされています。
- get_page_images(pno, full=False)#
PDFのみ: ページによって参照されるすべての画像(直接または間接的に)のリストを返します。
- パラメータ:
pno (int) -- ページ番号、ゼロベース、
-∞ < pno < page_count
。full (bool) -- このページがそのページ自体の場合、参照元の
xref
も含めるかどうか(これがページの場合はゼロ)。
- 戻り値の型:
list
- 戻り値:
このページで 参照されている 画像のリスト。各アイテムは以下のようになります:
(xref, smask, width, height, bpc, colorspace, alt. colorspace, name, filter, referencer)
ここで
xref (int) は画像オブジェクトの番号です
smask (int) はそのソフトマスク画像のオブジェクト番号です
width と height (int)は画像の寸法です
bpc (int) はコンポーネントごとのビット数を示します(通常は8)
colorspace (str) は色空間の名前を示す文字列です( DeviceRGB など)
alt. colorspace (str) は colorspace の値に依存する代替の色空間です
name (str) は画像が参照される際の象徴的な名前です
filter (str) は画像のデコードフィルタです(Adobe PDFリファレンス、pp. 22)。
referencer (int) は参照元の
xref
です。直接ページから参照されている場合はゼロ。 full=True の場合のみ存在します
注釈
一般的に、これは 実際に表示されている 画像のリストではありません。このメソッドは埋め込まれた画像への参照を収集するためにいくつかのPDFオブジェクトのみを解析します。実際の画像表示コマンドが定義されているページの内容は解析しません。この情報を取得するには、
Page.get_image_info()
を使用してください。また、辞書出力の構造 のセクションでの議論もご覧ください。
- get_page_fonts(pno, full=False)#
PDFのみ: ページによって参照されるすべてのフォント(直接または間接的に)のリストを返します。
- パラメータ:
- 戻り値の型:
list
- 戻り値:
このページで参照されているフォントのリスト。各エントリは以下のようになります:
(xref, ext, type, basefont, name, encoding, referencer),
ここで
xref (int) はフォントオブジェクト番号です(PDFが組み込みフォントを直接使用している場合、ゼロになることがあります)
ext (str) フォントファイルの拡張子(例: "ttf"、フォントファイルの拡張子 を参照)
type (str) フォントの種類("Type1"や"TrueType"など)
basefont (str) ベースフォント名
name (str) フォントが参照される象徴的な名前
encoding (str) フォントの文字エンコーディング。組み込みエンコーディングと異なる場合(Adobe PDFリファレンス、p. 254を参照):
referencer (int、オプション) 参照元のxref。ページから直接参照されている場合は0、それ以外の場合はXObjectの
xref
です。 full=True の場合のみ存在します。
例:
>>> pprint(doc.get_page_fonts(0, full=False)) [(12, 'ttf', 'TrueType', 'FNUUTH+Calibri-Bold', 'R8', ''), (13, 'ttf', 'TrueType', 'DOKBTG+Calibri', 'R10', ''), (14, 'ttf', 'TrueType', 'NOHSJV+Calibri-Light', 'R12', ''), (15, 'ttf', 'TrueType', 'NZNDCL+CourierNewPSMT', 'R14', ''), (16, 'ttf', 'Type0', 'MNCSJY+SymbolMT', 'R17', 'Identity-H'), (17, 'cff', 'Type1', 'UAEUYH+Helvetica', 'R20', 'WinAnsiEncoding'), (18, 'ttf', 'Type0', 'ECPLRU+Calibri', 'R23', 'Identity-H'), (19, 'ttf', 'Type0', 'TONAYT+CourierNewPSMT', 'R27', 'Identity-H')]
注釈
このリストには重複するエントリはありません:
xref
、name 、および referencer の組み合わせは一意です。一般的に、これはこのページで実際に使用されているフォントのスーパーセットです。PDF作成者は、各ページが部分的にしか使用しない、グローバルリストを指定したかもしれません。
- get_page_text(pno, output='text', flags=3, textpage=None, sort=False)#
ページ番号 pno (0から始まる)を指定して、ページのテキストを抽出します。
Page.get_text()
を呼び出します。- パラメータ:
pno (int) -- ページ番号、0から始まる、任意の値
-∞ < pno < page_count
。
その他のパラメータについては、ページのメソッドを参照してください。
- 戻り値の型:
str
- layout(rect=None, width=0, height=0, fontsize=11)#
与えられたページの寸法とフォントサイズに基づいて、ドキュメントを再ページ割り("リフロー")します。これは電子書籍やHTMLなどの一部のドキュメントタイプにのみ影響します。サポートされていない場合は無視されます。サポートされているドキュメントには
is_reflowable
プロパティで True が設定されています。- パラメータ:
rect (rect_like) -- 望ましいページサイズ。有限で、空でなく、ポイント(0, 0)で始まる必要があります。
width (float) -- rect との代替として、height と一緒に使用します。
height (float) -- rect との代替として、width と一緒に使用します。
fontsize (float) -- 望ましいデフォルトのフォントサイズ。
- select(s)#
PDFのみ:ドキュメントのページ番号がリストに含まれるページのみ保持します。空のシーケンスまたは範囲外の要素
range(doc.page_count)
は ValueError を引き起こします。詳細については、この章の最後の注釈を参照してください。- パラメータ:
s (sequence) -- (PythonシーケンスをPyMuPDFで引数として使用する場合) – ページ番号(0から始まる)のシーケンス(PyMuPDFで引数として使用する場合はPythonシーケンスを使用)を含めるためのもの。シーケンス内に含まれていないページは(メモリから)削除され、ドキュメントが再オープンされるまで利用できなくなります。ページ番号は複数回発生し、任意の順序で発生できます: 結果のドキュメントは指定された正確なシーケンスを反映します。
注釈
シーケンス内のページ番号は一意である必要も、特定の順序である必要もありません。これにより、この方法は、例えば偶数のページだけを選択したり、奇数のページだけを選択したり、その他の基準を満たしたりするなど、多目的に使用できます。
技術的なレベルでは、この方法は常に新しい
pagetree
を作成します。数ページしか扱わない場合、methods
copy_page()
、move_page()
、delete_page()
を使用する方が簡単です。実際、これらの方法は、文書に多くのページがある場合でも、少なくとも1桁のオーダーで 高速です 。
- set_metadata(m)#
PDFのみ: m で指定されたPythonの辞書と同じキーを持つ辞書を設定または更新します。
- パラメータ:
m (dict) -- metadata (以下参照)と同じキーを持つ辞書。すべてのキーはオプションです。PDFのフォーマットと暗号化方法は設定または変更できないため、無視されます。データを含めないべき値がある場合、そのキーを指定しないか、値を
None
に設定しないでください。{} を使用すると、すべてのメタデータ情報が文字列 "none" にクリアされます。一部の値のみを選択的に変更したい場合は、doc.metadata のコピーを変更して引数として使用してください。UTF-8でエンコードされた場合、任意のUnicode値が指定可能です。
(v1.18.4で変更) 空の値または "none" は書き込まれなくなり、完全に省略されます。
- get_xml_metadata()#
PDFのみ:ドキュメントのXMLメタデータを取得します。
- 戻り値の型:
str
- 戻り値:
ドキュメントのXMLメタデータ。存在しない場合やPDFでない場合は空の文字列。
- set_xml_metadata(xml)#
PDFのみ:ドキュメントのXMLメタデータを設定または更新します。
- パラメータ:
xml (str) -- xml(str)–新しいXMLメタデータ。XML構文である必要がありますが、このメソッドではチェックされず、任意の文字列が受け入れられます。
- set_pagelayout(value)#
v1.22.2で新登場
PDFのみ:
/PageLayout
を設定します。- パラメータ:
value (str) -- 以下の文字列のいずれか、"SinglePage"、"OneColumn"、"TwoColumnLeft"、"TwoColumnRight"、"TwoPageLeft"、"TwoPageRight"。小文字もサポートされています。
- set_pagemode(value)#
v1.22.2で新登場
PDFのみ:
/PageMode
を設定します。- パラメータ:
value (str) -- 以下の文字列のいずれか、"UseNone"、"UseOutlines"、"UseThumbs"、"FullScreen"、"UseOC"、"UseAttachments"。小文字もサポートされています。
- set_markinfo(value)#
v1.22.2で新登場
PDFのみ:
/MarkInfo
の値を設定します。- パラメータ:
value (dict) -- 次のような辞書:
{"Marked": False, "UserProperties": False, "Suspects": False}
。この辞書にはタグ付きPDF規則の使用に関する情報が含まれています。詳細については PDF仕様 を参照してください。
- set_toc(toc, collapse=1)#
PDFのみ:提供された引数で 現在のアウトラインツリー(目次)全体 を置き換えます。成功した実行後、新しいアウトラインツリーは通常通り D
Document.get_toc()
またはDocument.outline
を使用してアクセスできます。他の出力指向のメソッドと同様に、変更はsave()
(増分保存対応)を介してのみ永続的になります。内部的には、このメソッドは次の2つのステップで構成されています。デモンストレーションについては以下の例を参照してください。ステップ1:すべての既存のブックマークを削除します。
ステップ2:toc に含まれるエントリを使用して新しいTOCを作成します。
- パラメータ:
toc (sequence) --
新しい目次を形成するための すべてのブックマークエントリ を含むリスト/タプル。
get_toc()
の出力バリエーションが許容されます。目次を完全に削除するには、空のシーケンスまたはNoneを指定してください。各アイテムは、次の形式である必要があります。[lvl, title, page [, dest]] ここで
lvl はアイテムの階層レベル(int > 0)で、最初のアイテムの場合は1で、前のアイテムより最大1大きくする必要があります。
title (str)は表示されるタイトルです。UTF-8でエンコードされていると仮定されています(マルチバイトコードポイントの場合に関連します)。
page**(int)は対象のページ番号です **(注意:1から始まります) 。正の場合、有効な範囲内になければなりません。対象がない場合、または対象が外部の場合は-1に設定します。
dest (オプション)は辞書または数値です。数値の場合、このエントリがページ上で指し示すべき目標の高さ(ポイント単位)と解釈されます。詳細なブックマークのプロパティを制御するには(
get_toc(False)
によって出力されるものと同様の辞書を使用してください)、Document.get_toc()
の説明を参照してください。
collapse (int) -- (v1.16.9で新規追加) アウトラインエントリが初めて折りたたまれて表示される階層レベルを制御します。デフォルトの1はレベル1のみを表示し、より高いレベルはPDFビューアを使用して展開する必要があります。すべてを展開するには、大きな整数、0、またはNoneを指定してください。
- 戻り値の型:
int
- 戻り値:
挿入されたアイテム、または削除されたアイテムの数。
1.23.8 で変更されました: デスティネーションの 'to' 座標は、現在
get_toc()
で返される座標系と同じ座標系であるべきです (内部的にはpage.cropbox
とpage.rotation_matrix
で変換されます)。したがって、例えばset_toc(get_toc())
は、変更されていない 'to' 座標を与えます。
- outline_xref(idx)#
バージョン 1.17.7 での新機能
PDFのみ:アウトラインアイテムの
xref
を返します。これは主に内部用途で使用されます。引数 int idx:
Document.get_toc()
リスト内のアイテムのインデックス。- 戻り値:
xref
.
- del_toc_item(idx)#
バージョン 1.17.7 での新機能
v1.18.14で変更: アイテムのテキストを削除しなくなり、灰色で表示されます。
PDFのみ: この目次アイテムを削除します。これは高速なメソッドで、該当するアイテムを 無効にします が、全体の目次構造はそのままです。物理的には、アイテムはまだ目次ツリーに存在しますが、灰色で表示され、もはやどの宛先も指し示しません。
これはまた、必要な場合に:meth:
Document.set_toc_item
を使用してアイテムを新しい宛先に再割り当てできることを意味します。- パラメータ:
idx (int) --
Document.get_toc()
のリスト内のアイテムのインデックス。
- set_toc_item(idx, dest_dict=None, kind=None, pno=None, uri=None, title=None, to=None, filename=None, zoom=0)#
バージョン 1.17.7 での新機能
v1.18.6で変更
PDFのみ: インデックスによって識別されるTOCアイテムを変更します。アイテムの タイトル 、宛先 、 外観 (色、太字、イタリック)を変更したり、サブアイテムを折りたたんだり、アイテムを完全に削除したりするために使用します。
選択したエントリに対して特定の変更が必要で、完全なTOCを置き換えたくない場合にこのメソッドを使用します。大きな目次を扱う場合に特に便利です。
- パラメータ:
idx (int) --
Document.get_toc()
によって作成されたリスト内のエントリのインデックス。dest_dict (dict) -- 新しい宛先。
doc.get_toc(False)
のアイテムの最後のエントリのような辞書を使用することが推奨されます。指定された場合、他の すべてのパラメータは無視されます - タイトル以外。kind (int) -- リンクの種類、リンクの目的の種類 を参照してください。
LINK_NONE
の場合、残りのパラメータはすべて無視され、TOCアイテムは削除されます -Document.del_toc_item()
と同じです。Noneの場合、タイトルのみが変更され、残りのパラメータは無視されます。それ以外の値は、後続の引数を使用して新しい宛先辞書を作成します。pno (int) -- 1から始まるページ番号、つまり1 <= pno <= doc.page_count。LINK_GOTOの場合に必要です。
uri (str) -- URLのテキスト。LINK_URIの場合に必要です。
title (str) -- 新しいタイトル。変更しない場合はNone。
to (point_like) -- (オプション)対象ページ上の座標を指定します。LINK_GOTOの場合に関連します。省略された場合、ページの上部近くのポイントが選択されます。
filename (str) -- LINK_GOTORおよびLINK_LAUNCHに必要です。
zoom (float) -- 対象ページを表示する際にこのズームファクターを使用します。
使用例: SWIGマニュアルのTOCを変更して、次のことを達成します:
トップレベル以下をすべて折りたたみ、Pythonサポートの章を赤色で太字かつイタリックで表示:
>>> import pymupdf >>> doc=pymupdf.open("SWIGDocumentation.pdf") >>> toc = doc.get_toc(False) # we need the detailed TOC >>> # list of level 1 indices and their titles >>> lvl1 = [(i, item[1]) for i, item in enumerate(toc) if item[0] == 1] >>> for i, title in lvl1: d = toc[i][3] # get the destination dict d["collapse"] = True # collapse items underneath if "Python" in title: # show the 'Python' chapter d["color"] = (1, 0, 0) # in red, d["bold"] = True # bold and d["italic"] = True # italic doc.set_toc_item(i, dest_dict=d) # update this toc item >>> doc.save("NEWSWIG.pdf",garbage=3,deflate=True)
前の例では、ファイルの1240のTOCアイテムのうち、わずか42のみを変更しました。
- bake(*, annots=True, widgets=True)#
PDF のみ: 注釈やウィジェットをページの永続的な部分に変換します。このメソッドによって PDF は変更されます。
widgets
がTrue
の場合、ドキュメントは「フォーム PDF」ではなくなります。すべてのページが同じように見えますが、注釈またはフィールドがなくなります。必要に応じて、表示される部分は標準のテキスト、ベクトルグラフィックス、または画像に変換されます。
このメソッドは、
Document.convert_to_pdf()
を使用して PDF を PDF に変換する際の代替手段として有効な選択肢です。注釈は複雑なオブジェクトであり、視覚的な外観の下にさらに多くのデータが存在する場合があります。例としては、"Text" や "FileAttachment" の注釈が挙げられます。このメソッドで注釈やウィジェットを組み込む際には、この下部情報(添付ファイル、コメント、関連するポップアップ注釈など)がすべて失われ、次のガベージコレクション時に削除されます。
たとえば、
Document.insert_pdf()
(ウィジェットのコピーをサポートしていない)やPage.show_pdf_page()
(注釈やウィジェットをサポートしていない)などのメソッドで、ソースページがターゲットで完全に同じように見えるようにする場合にこの機能を使用します。- パラメータ:
annots (bool) -- 注釈を変換するかどうか。
widgets (bool) -- フィールド / ウィジェットを変換します。実行後、ドキュメントはもはや「フォーム PDF」ではありません。
- can_save_incrementally()#
v1.16.0で新規追加
ドキュメントを増分保存できるかどうかを確認します。例外を発生させずに正しいオプションを選択するために使用します。
- scrub(attached_files=True, clean_pages=True, embedded_files=True, hidden_text=True, javascript=True, metadata=True, redactions=True, redact_images=0, remove_links=True, reset_fields=True, reset_responses=True, thumbnails=True, xml_metadata=True)#
v1.16.14で新規追加
PDFのみ:PDFから潜在的に機密性の高いデータを削除します。この関数はAdobe Acrobat製品の類似の「Sanitize」機能にインスパイアを受けたものです。プロセスはさまざまなオプションで設定可能です。
- パラメータ:
attached_files (bool) -- 'FileAttachment' 注釈を検索してファイルコンテンツを削除します。
clean_pages (bool) -- ページ描画ソースからコメントを削除します。このオプションが False に設定されている場合、hidden_text と redactions に対しても同様の処理が行われます。
embedded_files (bool) -- 埋め込みファイルを削除します。
hidden_text (bool) -- OCRedテキストと不可視テキストを削除します [7]。
javascript (bool) -- JavaScriptソースを削除します。
metadata (bool) -- PDF標準のメタデータを削除します。
redactions (bool) -- レダクション注釈を適用します。
redact_images (int) -- レダクションを適用する場合の画像の処理方法。0(無視)、1(オーバーラップをブランク化)、または2(削除)のいずれかです。
remove_links (bool) -- すべてのリンクを削除します。
reset_fields (bool) -- すべてのフォームフィールドをデフォルトにリセットします。
reset_responses (bool) -- すべての注釈からすべての応答を削除します。
thumbnails (bool) -- ページからサムネイル画像を削除します。
xml_metadata (bool) -- XMLメタデータを削除します。
- save(outfile, garbage=0, clean=False, deflate=False, deflate_images=False, deflate_fonts=False, incremental=False, ascii=False, expand=0, linear=False, pretty=False, no_new_id=False, encryption=PDF_ENCRYPT_NONE, permissions=-1, owner_pw=None, user_pw=None, use_objstms=0)#
v1.18.7で変更
v1.19.0で変更
Changed in v1.24.1
PDFのみ:ドキュメントの 現在の状態 を保存します。
- パラメータ:
outfile (str,Path,fp) -- 保存先のファイルパス、
pathlib.Path
、またはファイルオブジェクト。ファイルオブジェクトはopen(...)
またはio.BytesIO()
を介して事前に作成されている必要があります。io.BytesIO()
を選択することは、以下のDocument.tobytes()
と同等で、内部で作成されたio.BytesIO()
のgetvalue()
出力に等しいです。garbage (int) --
ガベージコレクションを実行します。正の値は「増分」を除外します。
0 = なし
1 = 未使用(参照されていない)オブジェクトを削除します。
2 = 1に加えて、
xref
テーブルを最適化します。3 = 2に加えて、重複したオブジェクトを統合します。
4 = 3に加えて、ストリームオブジェクトの重複をチェックします。これは、そのようなデータが通常大きいため、遅い場合があります。
clean (bool) -- コンテンツストリームをクリーンアップおよびサニタイズします [1]。これは「mutool clean -sc」に対応します。
deflate (bool) -- 未圧縮のストリームをデフレート(圧縮)します。
deflate_images (bool) -- (v1.18.3で新規追加) 未圧縮の画像ストリームをデフレート(圧縮)します [4]。
deflate_fonts (bool) -- (v1.18.3で新規追加)未圧縮のフォントファイルストリームをデフレート(圧縮)します [4]。
incremental (bool) -- PDFへの変更を保存します。 "garbage" および "linear" を除外します。outfile が文字列または
pathlib.Path
であり、Document.name
に等しい場合にのみ使用できます。復号化または修復されたファイルおよび一部の他の場合には使用できません。確実にするために、Document.can_save_incrementally()
を確認してください。これがFalseの場合、新しいファイルに保存する必要があります。ascii (bool) -- バイナリデータをASCIIに変換します。
expand (int) --
オブジェクトを展開します。他のプログラムにより読みやすいバージョンを生成し、ファイルサイズが大きくなります。
0 = なし
1 = 画像
2 = フォント
255 = すべて
linear (bool) -- ドキュメントの線形バージョンを保存します。このオプションは、インターネットアクセスのパフォーマンス向上のためのファイル形式を作成します。 "増分" を除外します。
pretty (bool) -- ドキュメントソースを見やすく整形します。PDFオブジェクトは、
Document.xref_object()
のデフォルト出力のように再フォーマットされます。no_new_id (bool) -- ファイルの
/ID
フィールドの更新を抑制します。 ファイルにそのようなフィールドがまったくない場合、新しいフィールドの作成も抑制します。デフォルトはFalse
で、各保存でファイル識別情報が更新されます。permissions (int) -- (v1.16.0で新規追加)希望の権限レベルを設定します。可能な値については ドキュメントの許可 を参照してください。デフォルトはすべてを許可します。
encryption (int) -- (v1.16.0で新規追加) 希望の暗号化メソッドを設定します。可能な値については PDF暗号化方式コード を参照してください。
owner_pw (str) -- (v1.16.0で新規追加) ドキュメントの所有者パスワードを設定します。 (v1.18.3で変更) 指定しない場合、ユーザーパスワードが提供された場合にユーザーパスワードが使用されます。文字列の長さは40文字を超えてはいけません。
user_pw (str) -- (v1.16.0で新規追加)ドキュメントのユーザーパスワードを設定します。文字列の長さは40文字を超えてはいけません。
use_objstms (int) -- (v1.24.0で新機能) 可変化PDFオブジェクト定義を他のオブジェクトの
stream
データに格納される情報に変換する圧縮オプションです。deflate
パラメータの値に応じて、変換されたオブジェクト定義が圧縮されます。これにより、ファイルサイズが非常に大幅に削減される可能性があります。
警告
このメソッドは、その名前のファイルがすでに存在するかどうかをチェックしません。したがって、確認を求めずにファイルを上書きします。これについては、プログラマーとしての責任があります。
注釈
ファイルサイズの削減
オプションとして、
garbage=3|4, deflate=True, use_objstms=True|1
. デフォルト値に触れないでください。expand=False|0, clean=False|0, incremental=False|0
は変更しないでください。これは「非破壊的」なファイルサイズの削減です。これらの値がデフォルトで設定されたメソッドの簡易版もあります。Document.ez_save()
をご覧ください。本質的に「損失のある」ファイルサイズの削減は、画像に関して何かを犠牲にする必要があります。例えば、(a) すべての画像を削除する、(b) 画像をグレースケールに置換する、(c) 画像の解像度を低下させるなどの方法があります。PyMuPDF Utilities "replace-image" folder に例があります。
- ez_save(*args, **kwargs)#
v1.18.11で新規追加
PDFのみ:
Document.save()
と同じですが、デフォルト値がdeflate=True, garbage=3, use_objstms=1
に変更されています。
- saveIncr()#
PDFのみ:ドキュメントを増分的に保存します。これは、 doc.save(doc.name, incremental=True, encryption=PDF_ENCRYPT_KEEP) の簡略表記です。
注釈
増分保存が必要な場合、ドキュメントに確認済みの署名が含まれている場合、新しいファイルに保存することによって無効になる可能性があります。
- tobytes(garbage=0, clean=False, deflate=False, deflate_images=False, deflate_fonts=False, ascii=False, expand=0, linear=False, pretty=False, no_new_id=False, encryption=PDF_ENCRYPT_NONE, permissions=-1, owner_pw=None, user_pw=None, use_objstms=0)#
v1.18.7で変更
v1.19.0で変更
Changed in v1.24.1
PDFのみ: ドキュメントの現在のコンテンツ をファイルではなくバイトオブジェクトに書き込みます。明らかに、メモリ要件に注意する必要があります。パラメータの意味は
save()
とまったく同じです。チャプター FAQ には、このメソッドを pdfrw の前処理として使用する例が含まれています。(v1.16.0で変更) 拡張暗号サポート用。
- 戻り値の型:
bytes
- 戻り値:
ドキュメント全体を含むbytesオブジェクト。
- search_page_for(pno, text, quads=False)#
"pno" ページ上で "text" を検索します。対応する
Page.search_for()
とまったく同じ方法で機能します。整数-∞ < pno < page_count
ならどのような値でも受け入れられます。
- insert_pdf(docsrc, from_page=-1, to_page=-1, start_at=-1, rotate=-1, links=True, annots=True, show_progress=0, final=1)#
v1.19.3で変更 - 問題# #537 の修正として、フォームフィールドは常に除外されます。
PDFのみ:PDFドキュメント docsrc のページ範囲 [from_page、to_page] (両方を含む)を現在のドキュメントにコピーします。挿入はページ番号 start_at から開始します。値-1はデフォルト値を示します。したがって、コピーされるすべてのページは指定されたように回転します。リンクと注釈は対象から除外することができます(以下参照)。すべてのページ番号は0から始まります。
- パラメータ:
docsrc (Document) -- 現在のドキュメントではない、開かれたPDF ドキュメント 。ただし、同じ基盤ファイルを参照する場合があります。
from_page (int) -- docsrc 内の最初のページ番号。デフォルトはゼロです。
to_page (int) -- コピーする docsrc 内の最後のページ番号。デフォルトは最終ページです。
start_at (int) -- コピーされる最初のページ、対象のページ番号 start_at になります。デフォルト-1はページ範囲を末尾に追加します。ゼロの場合、ページ範囲は現在の最初のページの前に挿入されます。
rotate (int) -- コピーされるすべてのページは、指定された値(度数、90の整数倍)で回転します。
links (bool) -- (内部および外部) リンクをコピーに含めるかどうかを選択します。デフォルトは True です。コピー対象外のコピー範囲外の内部リンクは 常に除外されます 。
annots (bool) -- (v1.16.1で新規追加) 注釈をコピーに含めるかどうかを選択します。 フォームフィールドはコピーできません。
show_progress (int) -- (v1.17.7で新規追加)
sys.stdout
で進捗メッセージを表示するための大きなゼロより大きい間隔を指定します。各間隔後、Inserted 30 of 47 pages.
のようなメッセージが印刷されます。final (int) -- (v1.18.0で新規追加) このメソッドの後にすでにコピーされたオブジェクトのリストを 削除する かどうかを制御します。デフォルトは True です。同じソースPDFからの複数の挿入の最後以外は、0に設定します。これにより、対象ファイルのサイズが節約され、実行が大幅に高速化されます。
注釈
これはページベースのメソッドです。そのため、ソース文書のドキュメントレベルの情報は無視されます。例には、オプショナルコンテンツ、埋め込みファイル、
StructureElem
、AcroForm
、目次、ページラベル、メタデータ、名前付き目的地(および他の名前付きエントリ)などがあります。その結果、具体的にはフォームフィールド(ウィジェット)はコピーできません。 - たとえそれらがページ上に表示されているように見える場合でも。ウィジェットの 外観 を少なくとも保持する必要がある場合は、Document.bake()
をご覧ください。from_page > to_page
の場合、ページは 逆の順序でコピーされます 。0 <= from_page == to_page
の場合、1ページがコピーされます。docsrc のTOCエントリは コピーされません 。ただし、結果のドキュメントの目次を復元することは簡単です。以下の例と、examples ディレクトリのプログラム join.py を参照してください:これはPDFドキュメントを結合し、同時に対応する目次の部分を組み立てることができます。
- insert_file(infile, from_page=-1, to_page=-1, start_at=-1, rotate=-1, links=True, annots=True, show_progress=0, final=1)#
v1.22.0で新規追加
PDFのみ:任意のサポートされているドキュメントを現在のPDFに追加します。 "infile" をドキュメントとして開き、PDFに変換し、
Document.insert_pdf()
を呼び出します。パラメータはそのメソッドと同じです。他のことの中で、これには画像を出力PDFに完全なページとして追加する簡単な方法が含まれています。- パラメータ:
infile (multiple) -- 挿入する入力ドキュメント。Document (ドキュメント) を作成する際に有効なファイル名の指定または Pixmap である可能性があります。
- new_page(pno=-1, width=595, height=842)#
PDFのみ:空のページを挿入します。
- パラメータ:
pno (int) -- 新しいページを挿入する前のページ番号。1 < pno <= page_count である必要があります。特別な値-1および doc.page_count は最後のページの後に挿入します。
width (float) -- ページの幅。
height (float) -- ページの高さ。
- 戻り値の型:
- 戻り値:
作成されたページオブジェクト。
- insert_page(pno, text=None, fontsize=11, width=595, height=842, fontname='helv', fontfile=None, color=None)#
PDFのみ:新しいページを挿入し、テキストを挿入します。
Document.new_page()
とPage.insert_text()
の一部を組み合わせた便利な関数です。- パラメータ:
pno (int) --
挿入する前 のページ番号(0ベース)を指定します。範囲
range(-1, doc.page_count + 1)
内である必要があります。特別な値-1およびdoc.page_count
は最後のページの 後 に挿入します。- v1.14.12で変更
これは今ポジションパラメータです
その他のパラメータについては、前述のメソッドをご参照ください。
- 戻り値の型:
int
- 戻り値:
Page.insert_text()
の結果(正常に挿入された行数)。
- delete_page(pno=-1)#
PDFのみ:0ベースの番号で指定されたページを削除します。
-∞ < pno < page_count - 1
です。v1.18.14で変更:Pythonの
del
文をサポート。
- パラメータ:
pno (int) -- 削除するページ。負の数は文書の末尾から逆に数えます(インデックスと同様)。デフォルトは最後のページです。
- delete_pages(*args, **kwds)#
v1.18.13 で変更されました: 削除するページを指定する柔軟性が向上しました。
v1.18.14で変更:Pythonの
del
文をサポート。
PDF のみ: 0 ベースの番号として指定された複数のページを削除します。
- フォーマット 1: キーワードを使用します。古いフォーマットを表します。連続したページ範囲が削除されます。
"from_page": 削除する最初のページ。省略された場合はゼロです。
"to_page": 削除する最後のページ。省略された場合はドキュメント内の最後のページです。"from_page" より小さくしてはいけません。
フォーマット 2: 位置パラメータとしての2つのページ番号。フォーマット 1 と同様に処理されます。
フォーマット 3: 1 つの位置パラメータの整数。
Page.delete_page()
に相当します。フォーマット 4: ページ番号のリスト、タプル、または range() の1つの位置パラメータ。このシーケンスのアイテムは任意の順序であり、重複していてもかまいません。
フォーマット 5: (v1.18.14 で新規) Python の
del
ステートメントとインデックス / スライス表記を使用することができます。注釈
(v1.14.17 で変更, v1.17.7 で最適化) 有効な PDF 構造を維持するために、このメソッドと
delete_page()
は、削除されたページを指す目次のアイテムも無効化します。ここでの "無効化" とは、ブックマークがどこを指しているのか分からなくなり、サポートされている PDF ビューアによってタイトルがグレーアウト表示されることを意味します。全体の目次構造は維持されます。また、削除されたページを指す 残りのページ上のリンク も削除されます。これにより、多くのページを持つドキュメントでは拡張された応答時間が発生する可能性があります。
以下の例はすべて、ページ500から519を削除します:
doc.delete_pages(500, 519)
doc.delete_pages(from_page=500, to_page=519)
doc.delete_pages((500, 501, 502, ... , 519))
doc.delete_pages(range(500, 520))
del doc[500:520]
del doc[(500, 501, 502, ... , 519)]
del doc[range(500, 520)]
Adobe PDFリファレンス では、上記の操作に約0.6秒かかります。なぜなら、残りの1290ページから無効なリンクを削除する必要があるからです。
一般的に、このメソッドのパフォーマンスは残りのページの数に依存します - 削除されたページの数には依存 しません 。上記の例では、20個のページ 以外のすべてのページを削除する 場合、はるかに少ない時間がかかります。
- copy_page(pno, to=-1)#
PDF のみ: ドキュメント内でページの参照をコピーします。
- パラメータ:
pno (int) -- コピーするページ。範囲は
0 <= pno < page_count
である必要があります。to (int) -- コピーする位置の前のページ番号。デフォルトでは最後のページの 後 に挿入されます。
注釈
ページオブジェクトへの新しい 参照 のみが作成されます - 新しいページオブジェクトは作成されません。すべてのコピーされたページは、
Page.xref
を含む属性値が同じになります。これは、これらのコピーの1つに対する変更がすべてのコピーに反映されることを意味します。
- fullcopy_page(pno, to=-1)#
v1.14.17 で新規
PDF のみ: ページの完全なコピー(複製)を作成します。
- パラメータ:
pno (int) -- 複製するページ。範囲は
0 <= pno < page_count
である必要があります。to (int) -- コピーする位置の前のページ番号。デフォルトでは最後のページの 後 に挿入されます。
注釈
copy_page()
とは異なり、このメソッドは新しいページオブジェクト(新しいxref
を持つ)を作成します。これは元のページから独立して変更できます。ポップアップと "IRT"("応答先")注釈は、潜在的に誤った状況を回避するために コピーされません 。
- move_page(pno, to=-1)#
PDF のみ: ドキュメント内でページを移動します(コピーしてから元のページを削除)。
- パラメータ:
pno (int) -- 移動するページ。範囲は
0 <= pno < page_count
である必要があります。to (int) -- 移動したページの前に挿入するページ番号。デフォルトでは最後のページの 後 に移動します。
- need_appearances(value=None)#
v1.17.4 で新規
PDF のみ: Form PDF の /NeedAppearances プロパティを取得または設定します。引用: "(オプション)ドキュメント内のすべてのウィジェット注釈の外観ストリームと外観辞書を構築するかどうかを指定するフラグ...デフォルト値: false" 。これは一部のリーダー/ビューアの動作を制御するのに役立つかもしれません。
- パラメータ:
value (bool) -- プロパティをこの値に設定します。省略された場合または
None
の場合、現在の値を問い合わせます。- 戻り値の型:
bool
- 戻り値:
None: フォーム PDF ではないか、プロパティが定義されていない。
True / False: プロパティの値(設定されたばかりまたは問い合わせ用に存在する)。フォーム PDF がない場合は影響しません。
- get_sigflags()#
PDF のみ: ドキュメントに署名フィールドが含まれているかどうかを返します。これはオプションの PDF プロパティです。存在しない場合(返り値 -1)、結論を導くことはできません - PDF の作成者は単にそれを使用しなかった可能性があります。
- 戻り値の型:
int
- 戻り値:
-1: フォーム PDF でない / 署名フィールドが記録されていない / SigFlags が見つからない。
1: 少なくとも1つの署名フィールドが存在します。
3: ファイルが前の内容を変更する方法で保存(書き込み)されると、署名が無効になる可能性のある署名が含まれています。これは増分更新とは対照的です。
- embfile_add(name, buffer, filename=None, ufilename=None, desc=None)#
v1.14.16 で変更されました: 位置パラメータ "name" と "buffer" の順序が他の関数の呼び出しパターンに従うように変更されました。
PDF のみ: 新しいファイルを埋め込みます。名前以外のすべての文字列パラメータは Unicode である場合があります(以前のバージョンでは ASCII しか正しく動作しませんでした)。ファイルの内容は(有益な場合に)圧縮されます。
- パラメータ:
name (str) -- エントリの識別子、すでに存在しない必要 があります。
buffer (bytes,bytearray,BytesIO) --
ファイルの内容。
(v1.14.13 で変更) io.BytesIO もサポートされるようになりました。
filename (str) -- オプションのファイル名。ドキュメンテーション専用で、
None
の場合は name に設定されます。ufilename (str) -- オプションのUnicodeファイル名。ドキュメンテーション専用で、
None
の場合は filename に設定されます。desc (str) -- オプションの説明。ドキュメンテーション専用で、
None
の場合は name に設定されます。
- 戻り値の型:
int
- 戻り値:
(v1.18.13 で変更) このメソッドは挿入されたファイルの
xref
も返すようになりました。さらに、ファイルオブジェクトには現在の日時に基づいて自動的に PDF キー/CreationDate
および/ModDate
が設定されるようになりました。
- embfile_count()#
v1.14.16 で変更されました: これは現在のメソッドです。以前のバージョンではプロパティでした。
PDF のみ: 埋め込まれたファイルの数を返します。
- embfile_get(item)#
PDF のみ: エントリ番号または名前によって埋め込まれたファイルの内容を取得します。ドキュメントが PDF でない場合、またはエントリが見つからない場合、例外が発生します。
- パラメータ:
item (int,str) -- エントリのインデックスまたは名前。整数は範囲内である必要があります
range(embfile_count())
。- 戻り値の型:
bytes
- embfile_del(item)#
v1.14.16 で変更されました: インデックスによってアイテムを削除できるようになりました。
PDF のみ:
/EmbeddedFiles
からエントリを削除します。いつものように、適切なガベージオプションを使用して新しいファイルに保存すると、埋め込まれたファイルの内容の物理的な削除(およびファイルスペースの回復)が行われます。- パラメータ:
item (int/str) -- エントリのインデックスまたは名前。
警告
エントリ名を指定する場合、この関数はその名前を持つ 最初のアイテムのみを削除します 。PyMuPDF で作成された PDF 以外の PDF には重複する名前が含まれている可能性があるため、適切な注意を払う必要があるかもしれません。
- embfile_info(item)#
v1.18.13 で変更されました
PDF のみ: 埋め込まれたファイルの情報を取得します。エントリ番号または名前によって指定されたファイルの情報を取得します。
- パラメータ:
item (int/str) -- エントリのインデックスまたは名前。整数は範囲内である必要があります
range(embfile_count())
。- 戻り値の型:
dict
- 戻り値:
以下のキーを持つ辞書:
name – (str) このエントリが格納されている名前
filename – (str) ファイル名
ufilename – (unicode) Unicode ファイル名
desc – (str) 説明
size – (int) 元のファイルサイズ
length – (int) 圧縮ファイルの長さ
creationDate – (v1.18.13 で新規) (str) PDF 形式のアイテム作成の日時
modDate – (v1.18.13 で新規) (str) PDF 形式の最終変更の日時
collection – (v1.18.13 で新規) (int) 関連する PDF ポートフォリオアイテムの :data:`xref`(あれば)、それ以外はゼロ。
checksum – (v1.18.13 で新規) (str) 16進数の文字列として格納されたファイルコンテンツのハッシュコード。PDF 仕様に従えば MD5 であるべきですが、他のハッシュアルゴリズムも見る可能性があるので、準備しておいてください。
- embfile_names()#
v1.14.16 で新規
PDF のみ: 埋め込まれたファイルの名前のリストを返します。名前のシーケンスはドキュメント内の物理的なシーケンスと同じです。
- 戻り値の型:
list
- embfile_upd(item, buffer=None, filename=None, ufilename=None, desc=None)#
PDF のみ: エントリ番号または名前によって指定された埋め込まれたファイルを変更します。すべてのパラメータはオプションです。デフォルトで設定すると、操作は行われません。
- パラメータ:
item (int/str) -- エントリのインデックスまたは名前。整数は範囲内である必要があります
range(embfile_count())
。buffer (bytes,bytearray,BytesIO) -- 新しいファイルの内容。(v1.14.13 で変更) io.BytesIO もサポートされるようになりました。
filename (str) -- 新しいファイル名。
ufilename (str) -- 新しいUnicodeファイル名。
desc (str) -- 新しい説明。
(v1.18.13 で変更) このメソッドはファイルオブジェクトの
xref
も返すようになりました。- 戻り値の型:
int
- 戻り値:
ファイルオブジェクトのxref。自動的に、
/ModDate
PDF キーが現在の日時で更新されます。
- close()#
文書に関連付けられたオブジェクトとスペースの割り当てを解放します。ファイルから作成された場合、ファイル名も閉じられ(OS に制御を解放)ます。文書を明示的に閉じることは、それを削除すること、
del doc
、またはdoc = None
のように別のものに割り当てることと同等です。
- xref_object(xref, compressed=False, ascii=False)#
New in v1.16.8
v1.18.10 で変更
PDF のみ: PDF オブジェクトの定義ソースを返します。
- パラメータ:
xref (int) -- the object's
xref
. Changed in v1.18.10: A value of-1
returns the PDF trailer source.compressed (bool) -- 改行やスペースのないコンパクトな出力を生成するかどうか。
ascii (bool) -- バイナリデータを ASCII エンコードするかどうか。
- 戻り値の型:
str
- 戻り値:
オブジェクトの定義ソース。
- pdf_catalog()#
New in v1.16.8
PDF のみ: PDF カタログ(またはルート)オブジェクトの
xref
番号を返します。これをDocument.xref_object()
で使用してそのソースを表示できます。
- pdf_trailer(compressed=False)#
New in v1.16.8
PDF のみ: PDF のトレーラーソースを返します。通常、これは PDF ファイルの末尾にあります。これは
Document.xref_object()
で xref 引数が -1 の場合です。
- xref_stream(xref)#
New in v1.16.8
PDF のみ:
xref
ストリームオブジェクトの 解凍された コンテンツを返します。- パラメータ:
xref (int) --
xref
番号。- 戻り値の型:
bytes
- 戻り値:
(解凍された)オブジェクトのストリーム。
- xref_stream_raw(xref)#
New in v1.16.8
PDF のみ:
xref
ストリームオブジェクトの**変更前**(特に 解凍されていない)コンテンツを返します。それ以外の点ではDocument.xref_stream()
と同等です。- 戻り値の型:
bytes
- 戻り値:
(元の、変更前の)オブジェクトのストリーム。
- update_object(xref, obj_str, page=None)#
New in v1.16.8
PDF のみ:
xref
のオブジェクト定義を提供された文字列で置き換えます。xref が新しい場合、この命令はオブジェクト定義を完成させます。ページオブジェクトも指定された場合、そのリンクと注釈が後で再ロードされ、リンクと/または注釈に関連する変更が反映されます。- パラメータ:
xref (int) --
xref
番号。obj_str (str) -- 有効な PDF オブジェクト定義を含む文字列。
page (Page (ページ)) -- ページオブジェクト。指定された場合、このページの注釈が変更を反映するために再ロードされることを示します。
- 戻り値の型:
int
- 戻り値:
成功した場合はゼロ、それ以外の場合は例外が発生します。
- update_stream(xref, data, new=False, compress=True)#
v1.16.8 で新規
v1.19.2 で変更: パラメータ "compress" を追加
v1.19.6 で変更: パラメータ "new" を非推奨にし、無視します。オブジェクトが PDF 辞書オブジェクトであることを確認するようになりました。
xref で識別されるオブジェクトのストリームを置き換えます。xref は PDF 辞書である必要があります。オブジェクトがストリームでない場合、それをストリームに変換します。この関数は、有益な場合には自動的に圧縮操作("deflate")を実行します。
- パラメータ:
xref (int) --
xref
番号。stream (bytes|bytearray|BytesIO) --
ストリームの新しい内容。
(v1.14.13 で変更:) io.BytesIO オブジェクトもサポートされるようになりました。
new (bool) -- 非推奨 で無視されます。v1.20.0 以降のある時点で削除されます。
compress (bool) -- 挿入されるストリームを圧縮するかどうか。
True
の場合(デフォルト)、ストリームは/FlateDecode
圧縮を使用して挿入されます(有益な場合)、それ以外の場合はストリームはそのまま挿入されます。
- 例外:
ValueError -- xref が PDF 辞書を表していない場合。空の辞書 < は受け入れられます。したがって、xref を作成し、それにストリームを指定する場合は、まず
doc.update_object(xref, "<<>>")
を実行し、その後、このメソッドでストリームデータを挿入してください。
このメソッドは主に(しかし排他的ではなく)PDFオペレータ構文を含むストリームを操作することを意図しています(Adobe PDFリファレンス の pp. 643 参照)。例えばページのコンテンツストリームのようにです。
コンテンツストリームを更新する場合、PDFオペレータのソースとオブジェクト構造の間の整合性を確保するために save パラメータを clean=True で使用することを検討してください。
例: ある画像をページに表示させたくないと仮定しましょう。これは、そのコンテンツソース内の該当する参照を削除することによって実現できます - そして実際には、ページを再読み込みした後、画像は消えてしまいます。ただし、ページの
resources
は、まだその画像がページによって参照されていると表示されます。この保存オプションは、そのような不一致をクリーンアップします。
- xref_copy(source, target, *, keep=None)#
v1.19.5 で新規
PDF のみ: ターゲット の xref をソースの正確なコピーにします。ソース が
stream
の場合、これらのデータもコピーされます。- パラメータ:
注釈
このメソッドは、Python の dict メソッド
copy()
と多くの共通点があります。両方の xref 番号は既存の辞書を表す必要があります。
データがソースからコピーされる前に、すべての ターゲット 辞書のキーが削除されます。この削除からの例外を keep リストで指定できます。ただし、ソース に同じ名前のキーがある場合、その値はターゲットに置き換えられます。
ソース がストリームオブジェクトの場合、これらのデータもコピーされ、ターゲット はストリームオブジェクトに変換されます。
典型的な使用例は、赤塗り注釈を使用せずに既存の画像を置き換えたり削除したりすることです。例のスクリプトは こちら で確認できます。
- extract_image(xref)#
PDF のみ: 文書に格納された画像のデータとメタ情報を抽出します。出力は、画像ファイルとして保存するための直接的な使用、PIL、Pixmap の作成などに使用できます。このメソッドは、できる限りピクマップを使用せず、画像をその元の形式(例:JPEG として)で表示することを目的としています。
- パラメータ:
xref (int) -- 画像オブジェクトの
xref
。これがrange(1, doc.xref_length())
の範囲外であるか、オブジェクトが画像でないか、その他のエラーが発生した場合、None
が返され、例外は発生しません。- 戻り値の型:
dict
- 戻り値:
以下のキーを持つ辞書
ext (str) 画像タイプ(例:'jpeg')、画像ファイルの拡張子として使用可能
smask (int) ステンシル(/SMask)画像の
xref
番号またはゼロwidth (int) 画像の幅
height (int) 画像の高さ
colorspace (int) 画像のカラースペースの数
cs-name (str) 画像のカラースペースの名前
xres (int) x 方向の解像度。
resolution
も参照してください。yres (int) y 方向の解像度。
resolution
も参照してください。image (bytes) 画像データ、画像ファイルのコンテンツとして使用可能
>>> d = doc.extract_image(1373) >>> d {'ext': 'png', 'smask': 2934, 'width': 5, 'height': 629, 'colorspace': 3, 'xres': 96, 'yres': 96, 'cs-name': 'DeviceRGB', 'image': b'\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x05\ ...'} >>> imgout = open(f"image.{d['ext']}", "wb") >>> imgout.write(d["image"]) 102 >>> imgout.close()
注釈
pix = pymupdf.Pixmap(doc, xref) に続いてpix.tobytes() という機能的な重複があります。主な違いは、extract_imageは、(1) 必ずしもPNG画像形式を提供しない、 (2) PNG以外の画像では非常に高速である、 (3) 抽出された画像のディスクストレージが通常ははるかに少ない、 (4) エラーケースでは
None
を返す(例外を生成しない)という点です。同じPDF内の以下の例の画像を見てみましょう。xref 1268 は PNG 形式です - 比較可能な実行時間と同じ出力:
In [23]: %timeit pix = pymupdf.Pixmap(doc, 1268);pix.tobytes() 10.8 ms ± 52.4 µs per loop (mean ± std. dev. of 7 runs, 100 loops each) In [24]: len(pix.tobytes()) Out[24]: 21462 In [25]: %timeit img = doc.extract_image(1268) 10.8 ms ± 86 µs per loop (mean ± std. dev. of 7 runs, 100 loops each) In [26]: len(img["image"]) Out[26]: 21462
xref 1186 は JPEG です -
Document.extract_image()
は 何倍も速く、はるかに小さい出力を生成します(2.48 MB に対して 0.35 MB):In [27]: %timeit pix = pymupdf.Pixmap(doc, 1186);pix.tobytes() 341 ms ± 2.86 ms per loop (mean ± std. dev. of 7 runs, 1 loop each) In [28]: len(pix.tobytes()) Out[28]: 2599433 In [29]: %timeit img = doc.extract_image(1186) 15.7 µs ± 116 ns per loop (mean ± std. dev. of 7 runs, 100000 loops each) In [30]: len(img["image"]) Out[30]: 371177
- extract_font(xref, info_only=False, named=None)#
v1.19.4 で変更:
named == True
の場合、辞書を返します。
PDF のみ: 埋め込まれたフォントファイルのデータと適切なファイル拡張子を返します。これを使用してフォントを外部ファイルとして保存することができます。このメソッドは例外をスローしません(PDF および有効な
xref
のチェックを除く)。- パラメータ:
xref (int) -- 抽出するフォントの PDF オブジェクト番号。
info_only (bool) -- フォント情報のみを返し、バッファの割り当てを回避するために使用します。
named (bool) --
True
の場合、次のキーを持つ辞書が返されます: 'name'(フォントのベース名)、 'ext'(フォントファイルの拡張子)、 'type'(フォントのタイプ)、 'content'(フォントファイルの内容)。
- 戻り値の型:
tuple,dict
- 戻り値:
(basename, ext, type, content)
のタプルで、ext は3バイトの推奨ファイル拡張子(str)で、basename はフォントの名前(str)で、type はフォントのタイプ(例:「Type1」)で、content はフォントファイルの内容を含むバイトオブジェクトです(または b"" )。可能な拡張子の値とその意味については フォントファイルの拡張子 を参照してください。エラー時の返り値の詳細:("", "", "", b"")
– 無効な xref または xref が(有効な)フォントオブジェクトではない場合。(basename, "n/a", "Type1", b"")
– basename は埋め込まれておらず、したがって抽出できません。これは、例えば PDFベース14フォント フォントや Type 3 フォントの場合に該当します。
例:
>>> # store font as an external file >>> name, ext, _, content = doc.extract_font(4711) >>> # assuming content is not None: >>> ofile = open(name + "." + ext, "wb") >>> ofile.write(content) >>> ofile.close()
警告
ベースネーム は PDF から変更されずに返されます。そのため、それには (空白などの) ファイル名として使用できない文字が含まれている可能性があります。適切な措置を取ってください。
注釈
通常、返される ベースネーム は元のファイル名ではなく、いくつかの類似性があるかもしれません。
named == True
の場合、次のキーを持つ辞書が返されます:{'name': 'T1', 'ext': 'n/a', 'type': 'Type3', 'content': b''}
。
- has_links()#
- has_annots()#
バージョン 1.18.7 での新機能
PDF のみ: ドキュメント内にリンクまたは注釈が存在するかどうかを確認します。
- 戻り値:
True / False 。フィールドとは異なり、リンクや注釈の存在は PDF ドキュメントの中心的な場所に格納されているわけではなく、各ページを解析してのみ検出できます。これらのメソッドは効率的に実行するように調整されており、ページに対して True の回答がある場合、すぐに返されます。ただし、多くのページを持つ PDF の場合、リンクや注釈が見つからない場合、回答に時間がかかることがあります [6]。
- subset_fonts(verbose=False, fallback=False)#
PDF のみ: ドキュメント内のテキストによる使用を検討するための適格なフォントを調査します。サポートされているフォントで、サイズの削減が可能な場合、そのフォントは文字のサブセットを含むバージョンで置換されます。
このメソッドは、ドキュメントを保存する直前に使用します
- パラメータ:
verbose (bool) -- さまざまな進行状況情報を sysout に書き込みます。現在、これは
fallback
がTrue
の場合にのみ効果があります。fallback (bool) --
True
の場合、非推奨のアルゴリズムを使用して、パッケージ fontTools を使用します(従って、fontTools がインストールされている必要があります)。推奨される値False
(デフォルト)を使用すると、MuPDF のネイティブ関数が使用されます。これは非常に高速で、より広範なフォントタイプをサブセット化できます。この場合、パッケージ fontTools は必要ありません。
最大の利点は、アジアのスクリプトに典型的な大きなフォントを使用して新しい PDF を作成する場合に得られます。 Story (ストーリー) クラスまたはメソッド
Page.insert_htmlbox()
を使用する場合、複数のフォントが自動的に含まれる場合がありますが、プログラマーが気付かない場合もあります。これらのすべての場合、実際に使用される Unicode のセットは、使用されるフォントの使用可能なグリフの数に比べて非常に小さいことがほとんどです。このメソッドを使用すると、埋め込まれたフォントのバイナリを容易に2桁のキロバイト量にまで減らすことができます。
フォントのサブセットを作成すると、多数の大きな、今は使用されていない PDF オブジェクト(「ゴースト」)が残ります。そのため、ファイルを保存する際に圧縮およびガベージコレクトを行ってください。
Document.ez_save()
の使用をお勧めします。Show/hide history
バージョン 1.18.7 での新機能
v1.18.9で変更
v1.24.2 で変更され、MuPDF のネイティブ機能を使用するようになりました。
- journal_enable()#
v1.19.0 で新規追加
PDF のみ: ジャーナリングを有効にします。ログ操作を開始する前にこれを使用します。
- journal_start_op(name)#
v1.19.0 で新規追加
PDF のみ: 文字列 "name" で識別される "操作" のジャーナリングを開始します。ジャーナリングが有効な PDF に対しては、操作が開始されていない場合、更新が失敗します。
- journal_stop_op()#
v1.19.0 で新規追加
PDF のみ: 現在の操作を停止します。操作の開始から終了までの間の更新は、同じユニットの作業に属し、一緒に元に戻される / やり直されます。
- journal_position()#
v1.19.0 で新規追加
PDF のみ: 現在の操作番号と総操作数を返します。
- 戻り値:
ジャーナル内の現在の操作番号と総操作数を含むタプル
(step, steps)
が返されます。step が 0 の場合、ジャーナルの先頭にいることを示します。step が steps と等しい場合、ジャーナルの末尾にいることを示します。undo または redo 以外の何かで PDF を更新すると、現在のエントリ以降のすべてのジャーナルエントリが自動的に削除され、新しい更新がジャーナルの新しい最後のエントリになります。削除されたジャーナルエントリに対応する更新は永久に失われます。
- journal_op_name(step)#
v1.19.0 で新規追加
PDF のみ: 操作番号 step の操作名を返します。
- journal_can_do()#
v1.19.0 で新規追加
PDF のみ: 現在のジャーナル位置から前方("やり直し")および後方("元に戻す")の実行が可能かどうかを表示します。
- 戻り値:
{"undo": bool, "redo": bool}
形式の辞書。各メソッドはその値がTrue
の場合に利用可能です。
- journal_undo()#
v1.19.0 で新規追加
PDF のみ: ジャーナル内の現在のステップを元に戻します(元に戻す)。これにより、ジャーナルの先頭に向かって移動します。
- journal_redo()#
v1.19.0 で新規追加
PDF のみ:現在のステップをジャーナルのボトムに戻して再適用します。
- journal_save(filename)#
v1.19.0 で新規追加
PDF のみ:ジャーナルをファイルに保存します。
- パラメータ:
filename (str,fp) -- 文字列としてのファイル名または "wb" で開かれたファイルオブジェクト (または
io.BytesIO()
オブジェクト)。
- journal_load(filename)#
v1.19.0 で新規追加
PDF のみ:ファイルからジャーナルを読み込みます。ドキュメントのジャーナリングを有効にします。既にジャーナリングが有効になっている場合、例外が発生します。
- パラメータ:
filename (str,fp) -- ジャーナルのファイル名 (str) または "rb" で開かれたファイルオブジェクト (または
io.BytesIO()
オブジェクト)。
- save_snapshot()#
v1.19.0 で新規追加
PDF のみ:ドキュメントの「スナップショット」を保存します。これは、ジャーナリングと互換性のある特別なインクリメンタルセーブ形式を持つ PDF ドキュメントです。そのため、セーブオプションは利用できません。新しいドキュメントにはスナップショットを保存することはできません。
これは通常の PDF ドキュメントで、制限はありません。何も変更されていない場合、そのスナップショットはジャーナルと共に操作を元に戻したり、やり直したり、更新を続けたりするために使用できます。
- outline#
ドキュメントの最初のアウトラインエントリを含みます (または
None
)。すべてのアウトラインアイテムを歩く出発点として使用できます。暗号化された、認証されていないドキュメントに対してこのプロパティにアクセスすると、AttributeError が発生します。- タイプ:
- is_closed#
もし文書がまだ開いている場合は False です。閉じた場合、他のほとんどの属性やメソッドが削除されたり無効になります。また、この文書を参照する Page (ページ) オブジェクト(すなわち
Document.load_page()
で作成されたもの)とそれに依存するオブジェクトは利用できなくなります。参照用に、Document.name
はまだ存在し、元の文書のファイル名が含まれます(該当する場合)。- タイプ:
bool
- is_dirty#
これがPDFドキュメントであり、保存されていない変更が含まれている場合は True 、それ以外は False です。
- タイプ:
bool
- is_pdf#
これがPDFドキュメントである場合は True 、それ以外は False です。
- タイプ:
bool
- is_form_pdf#
これがPDFでないか、フォームフィールドが含まれていない場合は False であり、それ以外の場合はルートフォームフィールド(祖先のないフィールド)の数です。
(v1.16.4で変更) (ルート)フォームフィールドの合計数を返します。
- タイプ:
bool,int
- is_reflowable#
文書が可変ページレイアウト(電子書籍やHTMLのような)を持つ場合は True です。この場合、文書の作成(オープン)時または
layout()
メソッドを使用して所望のページ寸法を設定できます。- タイプ:
bool
- is_repaired#
v1.18.2で新しく追加されました。
PDFがオープン時に修復された場合は True です(主要な構造上の問題のため)。非PDF文書の場合は常に False です。True の場合、詳細は
TOOLS.mupdf_warnings()
に保存され、Document.can_save_incrementally()
は False を返します。- タイプ:
bool
- is_fast_webaccess#
v1.22.2で新登場
PDFが直線化形式である場合は True です。非PDF文書の場合はFalseです。
- タイプ:
bool
- markinfo#
v1.22.2で新登場
/MarkInfo
の値を示す辞書です。指定されていない場合、空の辞書が返されます。PDFでない場合はNone
が返されます。- タイプ:
dict
- pagemode#
v1.22.2で新登場
/PageMode
の値を含む文字列です。指定されていない場合、デフォルトの「UseNone」が返されます。PDFでない場合、None
が返されます。- タイプ:
str
- pagelayout#
v1.22.2で新登場
/PageLayout
の値を含む文字列です。指定されていない場合、デフォルトの「SinglePage」が返されます。PDFでない場合、None
が返されます。- タイプ:
str
- version_count#
v1.22.2で新登場
ドキュメント内に存在するバージョンの数をカウントする整数です。PDFでない場合、ゼロです。それ以外の場合、増分保存の数に1を加えたものです。
- タイプ:
int
- needs_pass#
ドキュメントがアクセス制限のあるパスワードで保護されているかどうかを示します。この指示は、ドキュメントが認証された後も 変更されません。
True
の場合、増分保存が不可能です。- タイプ:
bool
- is_encrypted#
この指示は、最初に
Document.needs_pass
と等しいです。認証が成功した後、状況を反映するために False に設定されます。- タイプ:
bool
- permissions#
Changed in v1.16.0: This is now an integer comprised of bit indicators. Was a dictionary previously.
アクセス許可を示します。これは、対応するビット位置にbool値を含む整数です。例えば、doc.permissions & pymupdf.PDF_PERM_MODIFY > 0 の場合、ドキュメントを変更できます。詳細については、ドキュメントの許可 を参照してください。
- タイプ:
int
- metadata#
文書のメタデータをPythonの辞書形式で含んでいます。ただし、is_encrypted=True かつ needPass=True の場合は
None
です。キーは format、encryption、title、author、subject、keywords、creator、producer、creationDate、modDate、trapped です。すべてのアイテムの値は文字列またはNone
です。format と encryption を除いて、PDF 文書の場合、キー名は明らかな方法で PDF キー /Creator、/Producer、/CreationDate、/ModDate、/Title、/Author、/Subject、/Trapped、/Keywords に対応しています。
format には文書のフォーマット(例: 'PDF-1.6'、'XPS'、'EPUB')が含まれます。
encryption には
None
(暗号化なし)または暗号化メソッドを示す文字列(例: 'Standard V4 R4 128-bit RC4') が含まれます。 needs_pass=False の場合でも暗号化メソッドが指定される場合があります。その場合、すべての権限が付与されていない可能性があります。詳細はDocument.permissions
を確認してください。日付フィールドに有効なデータが含まれている場合(必ずしもそうである必要はありません!)、それらは PDF 固有のタイムスタンプ形式 "D:<TS><TZ>" の文字列です。
<TS> は 12 文字の ISO タイムスタンプ YYYYMMDDhhmmss(YYYY - 年、MM - 月、DD - 日、hh - 時、mm - 分、ss - 秒)であり、
<TZ> は GMT に対する時刻間隔を示す符号('+' または '-')、時間(hh)、および分('mm'、アポストロフィに注意!)を含むタイムゾーン値です。
したがって、パラグアイの値は D:20150415131602-04'00' となり、これは Asuncion の現地時間で 2015 年 4 月 15 日午後 1 時 16 分 02 秒を表します。
- タイプ:
dict
- name#
Document が作成された ファイル名 または ファイルタイプ の値を含みます。
- タイプ:
str
- page_count#
文書のページ数を含みます。ページがない文書の場合は 0 を返す場合があります。
len(doc)
関数もこの結果を返します。- タイプ:
int
- chapter_count#
v1.17.0 で新たに追加されました
文書の章の数を含みます。常に少なくとも 1 です。章のサポートがある文書タイプ(現在は EPUB のみ)にのみ関連します。その他の文書は 1 を返します。
- タイプ:
int
- last_location#
v1.17.0 で新たに追加されました
文書の最後のページの(章、pno)を含みます。章のサポートがある文書タイプ(現在は EPUB のみ)にのみ関連します。その他の文書は
(0, page_count - 1)
と(0, -1)
を返します。- タイプ:
int
- FormFonts#
/AcroForm オブジェクトで定義されたフォームフィールドのフォント名のリストです。PDF でない場合は
None
です。- タイプ:
list
注釈
PDFの構造を変更するメソッド (insert_pdf()
、select()
、copy_page()
、delete_page()
など)を使用する場合、プログラム内のオブジェクトやプロパティが無効化されたり孤立したりする可能性があることに注意してください。これには Page (ページ) オブジェクトとその子要素(リンク、注釈、ウィジェット)、古いページ数を保持する変数、目次などが含まれます。このような変数を最新の情報に保つか、孤立したオブジェクトを削除することを忘れないでください。重要なオブジェクトの整合性を確保するためのPyMuPDF も参照してください。
set_metadata()
の例#
メタデータ情報をクリアします。プライバシー/データ保護の理由からこれを行う場合は、ガベージ > 0 でドキュメントを新しいファイルとして保存してから古い /Info オブジェクトもファイルから物理的に削除されることを確認してください。この場合、いくつかのPDFエディタによって挿入されたXMLメタデータもクリアすることを検討するかもしれません。
>>> import pymupdf
>>> doc=pymupdf.open("pymupdf.pdf")
>>> doc.metadata # look at what we currently have
{'producer': 'rst2pdf, reportlab', 'format': 'PDF 1.4', 'encryption': None, 'author':
'Jorj X. McKie', 'modDate': "D:20160611145816-04'00'", 'keywords': 'PDF, XPS, EPUB, CBZ',
'title': 'The PyMuPDF Documentation', 'creationDate': "D:20160611145816-04'00'",
'creator': 'sphinx', 'subject': 'PyMuPDF 1.9.1'}
>>> doc.set_metadata({}) # clear all fields
>>> doc.metadata # look again to show what happened
{'producer': 'none', 'format': 'PDF 1.4', 'encryption': None, 'author': 'none',
'modDate': 'none', 'keywords': 'none', 'title': 'none', 'creationDate': 'none',
'creator': 'none', 'subject': 'none'}
>>> doc._delXmlMetadata() # clear any XML metadata
>>> doc.save("anonymous.pdf", garbage = 4) # save anonymized doc
set_toc()
のデモンストレーション#
これは、目次を変更または追加する方法を示しています。また、examplesディレクトリにある import.py と export.py も参照してみてください。
>>> import pymupdf
>>> doc = pymupdf.open("test.pdf")
>>> toc = doc.get_toc()
>>> for t in toc: print(t) # show what we have
[1, 'The PyMuPDF Documentation', 1]
[2, 'Introduction', 1]
[3, 'Note on the Name fitz', 1]
[3, 'License', 1]
>>> toc[1][1] += " modified by set_toc" # modify something
>>> doc.set_toc(toc) # replace outline tree
3 # number of bookmarks inserted
>>> for t in doc.get_toc(): print(t) # demonstrate it worked
[1, 'The PyMuPDF Documentation', 1]
[2, 'Introduction modified by set_toc', 1] # <<< this has changed
[3, 'Note on the Name fitz', 1]
[3, 'License', 1]
insert_pdf()
の例#
(1)2つの文書を連結して、それぞれの目次を含める:
>>> doc1 = pymupdf.open("file1.pdf") # must be a PDF
>>> doc2 = pymupdf.open("file2.pdf") # must be a PDF
>>> pages1 = len(doc1) # save doc1's page count
>>> toc1 = doc1.get_toc(False) # save TOC 1
>>> toc2 = doc2.get_toc(False) # save TOC 2
>>> doc1.insert_pdf(doc2) # doc2 at end of doc1
>>> for t in toc2: # increase toc2 page numbers
t[2] += pages1 # by old len(doc1)
>>> doc1.set_toc(toc1 + toc2) # now result has total TOC
明らかに、より一般的な状況についても同様の方法が見つかるでしょう。連続するヒエラルキーレベルが1以上増加しないように注意してください。 toc2 セグメントの前後にダミーのブックマークを挿入することで、そのような場合を修正できます。すぐに使用できるGUI(wxPython)の解決策は、examplesディレクトリのスクリプト join.py で見つけることができます。
(2)その他の例:
>>> # insert 5 pages of doc2, where its page 21 becomes page 15 in doc1
>>> doc1.insert_pdf(doc2, from_page=21, to_page=25, start_at=15)
>>> # same example, but pages are rotated and copied in reverse order
>>> doc1.insert_pdf(doc2, from_page=25, to_page=21, start_at=15, rotate=90)
>>> # put copied pages in front of doc1
>>> doc1.insert_pdf(doc2, from_page=21, to_page=25, start_at=0)
他の例#
PDF内のすべてのページ参照画像を個別のPNGファイルに抽出します:
for i in range(doc.page_count):
imglist = doc.get_page_images(i)
for img in imglist:
xref = img[0] # xref number
pix = pymupdf.Pixmap(doc, xref) # make pixmap from image
if pix.n - pix.alpha < 4: # can be saved as PNG
pix.save("p%s-%s.png" % (i, xref))
else: # CMYK: must convert first
pix0 = pymupdf.Pixmap(pymupdf.csRGB, pix)
pix0.save("p%s-%s.png" % (i, xref))
pix0 = None # free Pixmap resources
pix = None # free Pixmap resources
PDFのすべてのページを回転させます:
>>> for page in doc: page.set_rotation(90)
脚注