データベースの API 説明書

この API はスレッドセーフです。(複数のリーダ、単一のライタのロック機構を使用) この API には次のようにしてアクセスできます:

from calibre.library import db
db = db('Path to calibre library folder').new_api

メインの calibre GUI の一部である calibre プラグインにいるなら、代わりに次のようにしてアクセスします:

db = self.gui.current_db.new_api

class calibre.db.cache.Cache(backend: DB, library_database_instance: LibraryDatabase | None = None)

calibre ライブラリの metadata.db ファイルのメモリ内キャッシュ。このクラスはデータベースにアクセスするためのスレッドセーフな API としても機能します。メモリ内キャッシュは、性能を最大化するために通常の形式で維持されます。

SQLITE は metadata.db に安全に読み書きするための手段として使用されます。テーブルの読取り/並べ替え/検索/キャッシュのロジックが再実装されます。これは性能の最大化と柔軟性のために必要です。

class EventType(*values)

book_created = 4

本の ID を唯一の引数として新しい本のレコードをデータベースに作成するとき

book_edited = 8

次の引数とともに本の形式を編集するとき: (book_id, fmt)

books_removed = 5

本の ID を唯一の引数としてデータベースから本を削除するとき

format_added = 2

次の引数とともに本に形式を追加するとき: (book_id, format)

formats_removed = 3

次の引数とともに本から形式が削除されるとき: (book_id から、削除される本の形式のリストへのマッピング)

indexing_progress_changed = 9

インデックス処理の進行状況が変わったとき

items_removed = 7

タグや著者などの項目を一部の本から削除するとき。引数: (field_name, affected book ids, ids of removed items)

items_renamed = 6

タグや著者などの項目の名前を一部またはすべての本で変更するとき。引数: (field_name, affected book ids, map of old item id to new item id)

links_changed = 11

要素に関連するリンクを変更したとき。引数: (field_name, item_ids)

metadata_changed = 1

次の引数とともに一部の本で一部の書誌を変更するとき: (変更したフィールド名, 影響する本の ID のセット)

notes_changed = 10

要素に関連するノートを変更したとき。引数: (field_name, item_ids)

add_books(books: Iterable[tuple[Metadata, Mapping[str, str | IO[bytes]]]], add_duplicates: bool = True, apply_import_tags: bool = True, preserve_uuid: bool = False, run_hooks: bool = True, dbapi: LibraryDatabase | None = None) → tuple[list[int], list[tuple[Metadata, Mapping[str, str | IO[bytes]]]]]

指定した本をライブラリに追加。本は 2 タプルの繰り返し可能なもので、各 2 タプルは (mi, format_map) のフォームです。mi は Metadata オブジェクトで、format_map はフォーム {fmt: path_or_stream} の辞書です。例: {'EPUB': '/path/to/file.epub'}

リストのペア (ids, duplicates) を返します。ids にはデータベースに新しく作成されたすべての本の ID が含まれます。duplicates には、has_book() が使用する簡単な重複検出ヒューリスティックに従って、データベースにすでにある本の (mi, format_map) が含まれます。

add_custom_book_data(name: str, val_map: Mapping[int, object], delete_first: bool = False) → None

name のデータを追加。val_map は book_ids の値へのマップです。delete_first が True のとき、以前格納していた name のデータはすべて削除されます。

add_extra_files(book_id: int, map_of_relpath_to_stream_or_path: Mapping[str, str | IO[bytes]], replace: bool = True, auto_rename: bool = False) → dict[str, bool]

追加データファイルを追加

add_format(book_id: int, fmt: str, stream_or_path: str | IO[bytes], replace: bool = True, run_hooks: bool = True, dbapi: LibraryDatabase | None = None) → bool

指定した本に形式を追加します。形式が正常に追加された場合は True を返します。

パラメータ:

• replace -- True のとき既存の形式を置き換え、そうでなければ形式がすでに存在しているときに False を返します。

• run_hooks -- True のとき、追加の前後でファイルタイプのプラグインを形式に実行します。

• dbapi -- 内部利用のみ。

add_listener(event_callback_function: EventCallback, check_already_added: bool = False) → bool

このデータベースで特定のアクションが実行された後に呼び出されるコールバック関数を登録します。関数は 3 つの引数が必要です: (EventType, library_id, event_type_specific_data)

add_notes_resource(path_or_stream_or_data: str | bytes | IO[bytes], name: str, mtime: float | None = None) → str

ノートを参照できるリソースを追加して、コンテンツハッシュを返します。

all_annotation_styles() → dict[str, JSONDict]

データベース中のすべての組み込み注釈をタプルで返します。

all_annotation_types() → tuple[str, ...]

データベース中のすべての注釈をタプルで返します。

all_annotation_users() → tuple[tuple[str, str], ...]

注釈を持つすべての(user_type, user name)をタプルで返します。

all_annotations(restrict_to_user: tuple[str, str] | None = None, limit: int | None = None, annotation_type: str | None = None, annotation_style: Mapping[str, object] | None = None, ignore_removed: bool = False, restrict_to_book_ids: Container[int] | None = None) → tuple[JSONDict, ...]

基準に一致するすべての注釈をタプルで返します。ignore_removed で、削除済みの注釈も返すかどうかを制御します。削除済みの注釈は、注釈の統合に使われる骨組みにすぎません。

all_annotations_for_book(book_id: int) → tuple[JSONDict, ...]

指定のbook_idですべての注釈を含むタプルを返します。辞書のKEYは: format, user_type, user, annotation ここのannotaionは注釈データです。

all_book_ids() → frozenset[int]

all_book_ids(type: Callable[[dict[int, str]], T]) → T

すべての既知の本の ID の凍結セット。

all_field_for(field: MultipleFieldName, book_ids: Iterable[int], default_value: object = None) → dict[int, tuple[str, ...]]

all_field_for(field: Literal['identifiers'], book_ids: Iterable[int], default_value: object = None) → dict[int, dict[str, str]]

all_field_for(field: str, book_ids: Iterable[int]) → dict[int, FieldValue]

all_field_for(field: str, book_ids: Iterable[int], default_value: D) → dict[int, FieldValue | D]

field_for と同じですが、一度に複数の本を操作します

all_field_ids(name: str) → frozenset[int]

フィールド name のすべての値の frozenset 。

all_field_names(field: str, book_ids: Iterable[int] | None = None) → frozenset[str]

すべてのフィールド名の frozenset です（多対1または多対多のフィールドにのみ使用してください）。book_ids が None でない場合は、指定した本で使われている名前だけを返します。

annotation_count_for_book(book_id: int) → int

データベース中の指定bookの注釈の個数を返します。

annotations_map_for_book(book_id: int, fmt: str, user_type: str = 'local', user: str = 'viewer') → dict[str, list[JSONDict]]

book_id, format, user, user_typeを指定して、annotation type -> annotation dataのmapを返します。

author_data(author_ids: Iterable[int] | None = None) → dict[int, dict[str, str]]

著者データをキー付きの辞書として返します: name, sort, link

指定された ID を持つ著者が見つからない場合は、空の辞書が返されます。 a uthor_ids が None の場合、すべての著者のデータが返されます。

author_sort_from_authors(authors: ~collections.abc.Iterable[str], key_func: ~collections.abc.Callable[[str], str] = <function make_change_case_func.<locals>.change_case>) → str

著者のリストを指定して、著者の author_sort 文字列を返します。計算された文字列よりも、著者読みに関連付けられた著者の並べ替えを優先します。

author_sorts(author_ids: Iterable[int] | None = None) → dict[int, str]

著者IDを指定してauthor sorts文字列を返します。

指定された ID を持つ著者が見つからない場合は、空の辞書が返されます。 a uthor_ids が None の場合、すべての著者のデータが返されます。

book_ids_for_annotations(annot_ids: Iterable[int], ignore_removed: bool = False) → dict[int, int]

指定されたアノテーションIDのうち、存在するアノテーションについて、アノテーションIDから本のIDへのマッピングを返します。ignore_removed は、削除済みのアノテーションを含めるかどうかを制御します。

book_storage_for_book(book_id: int, fmt: str, user_type: str = 'local', user: str = 'viewer') → BookStorageEntry | None

指定された book_id、format、user_type、および user に対応する、本ごとのストレージ（ビューアーの localStorage 用）を返します。ストレージが存在しない場合は None を返します。このストレージは、{'timestamp': エポックからの経過秒数, 'data': {key: value}} という形式の辞書です。

books_for_field(name: str, item_id: int) → set[int]

item_id で指定される項目に関連付けられた本をすべて返します。ここで、項目はフィールド name に属しています。

戻り値は本の ID のセット、または項目かフィールドが存在しなければ空のセットです。

books_in_virtual_library(vl: str | None, search_restriction: str | None = None, virtual_fields: dict[str, VirtualField] | None = None) → frozenset[int]

指定された仮想ライブラリ内の本のセットを返します

compress_covers(book_ids: Iterable[int], jpeg_quality: int = 100, progress_callback: Callable[[int, int, int | str], object] | None = None) → None

指定した本の表紙画像を圧縮します。圧縮品質が 100 なら、可逆圧縮を実行します。それ以外は、不可逆圧縮を実行します。

進行状況のコールバックは、book_id と、処理されたそれぞれの本の新旧のサイズとともに呼び出されます。エラーが発生すると、新しいサイズはエラーの詳細を含む文字列になります。

copy_cover_to(book_id: int, dest: __annotationlib_name_2__ | SupportsWrite[__annotationlib_name_1__], use_hardlink: bool = False, report_file_size: Callable[[int], object] | None = None) → bool

オブジェクト dest のようなファイルに表紙をコピーします。表紙が存在しない場合、または dest が現在の表紙と同じファイルである場合には、False を返します。 dest にはパスを指定することも可能です。その場合、パスが現在のパスと異なる場合にのみ、表紙をコピーします (大文字と小文字は区別されます)。

copy_format_to(book_id: int, fmt: str | None, dest: __annotationlib_name_2__ | SupportsWrite[__annotationlib_name_1__], use_hardlink: bool = False, report_file_size: Callable[[int], object] | None = None) → bool

形式 fmt をファイルライクオブジェクト dest にコピーします。指定された形式が存在しない場合には、NoSuchFormat エラーを発生させます。 destには (ファイルへの) パスを指定することも可能です。その場合、パスが現在のパスと異なる場合にのみ、形式をコピーします (大文字と小文字は区別されます)。

cover(book_id: int, as_file: Literal[False] = False, as_image: Literal[False] = False, as_path: Literal[False] = False, as_pixmap: Literal[False] = False) → bytes | None

cover(book_id: int, *, as_file: Literal[True]) → SpooledTemporaryFile | None

cover(book_id: int, *, as_path: Literal[True]) → str | None

cover(book_id: int, *, as_image: Literal[True]) → QImage

cover(book_id: int, *, as_pixmap: Literal[True]) → QPixmap

cover(book_id: int, as_file: bool = False, as_image: bool = False, as_path: bool = False, as_pixmap: bool = False) → bytes | str | SpooledTemporaryFile | QImage | QPixmap | None

表紙画像または None を返します。デフォルトでは表紙をバイト列で返します。

警告: as_path を使用すると、表紙が一時ファイルにコピーされ、一時ファイルへのパスが返されます。使い終わったら、一時ファイルを削除する必要があります。

パラメータ:

• as_file -- True のとき、開いているファイルオブジェクト(SpooledTemporaryFile) として画像を返します

• as_image -- True のとき、QImage オブジェクトとして画像を返します

• as_pixmap -- Trueのとき、QPixmapオブジェクトでイメージを返します。

• as_path -- True のとき、一時ファイルを指すパスとして画像を返します

data_for_find_identical_books() → IdenticalBooksData

データベースにアクセスすることなくワーカープロセスで find_identical_books() を実装するのに使えるデータを返します。実装については db.utils を参照してください。

data_for_has_book() → set[str]

has_book() での使用に適したデータを返します。これは、db にアクセスすることなくワーカープロセスで has_book() を実装するために使用できます。

delete_annotations(annot_ids: Iterable[int]) → None

指定のIDで注釈を削除します。

delete_custom_book_data(name: str, book_ids: Collection[int] = ()) → None

name で指定されたデータを削除します。デフォルトではすべてのデータを削除します。一部の本の ID のデータのみ削除したい場合には、本の ID のリストを渡します。

delete_trash_entry(book_id: int, category: str) → None

ごみ箱のエントリを削除します。ここで、'b' は本、'f' はフォーマットです。.

embed_metadata(book_ids: Collection[int], only_fmts: Iterable[str] | None = None, report_error: Callable[[Metadata, str, str], object] | None = None, report_progress: Callable[[int, int, Metadata], object] | None = None) → None

指定された book_ids のすべての形式の書誌を、データベース内の現在の書誌に更新します。

expire_old_trash() → None

ゴミ箱の古いエントリを期限切れとします。

export_note(field: str, item_id: int) → str

埋め込み画像はdata: URLs として、ノートを単一HTMLドキュメントにエクスポートします。

fast_field_for(field_obj: Field, book_id: int) → FieldValue

fast_field_for(field_obj: Field, book_id: int, default_value: D) → FieldValue | D

field_for と同じですが、フィールドオブジェクトを取得するために余分なルックアップ／検索を回避します

field_for(name: MultipleFieldName, book_id: int, default_value: object = None) → tuple[str, ...]

field_for(name: Literal['identifiers'], book_id: int, default_value: object = None) → dict[str, str]

field_for(name: StrFieldName, book_id: int) → str | None

field_for(name: StrFieldName, book_id: int, default_value: D) → str | D

field_for(name: DateFieldName, book_id: int) → datetime | None

field_for(name: DateFieldName, book_id: int, default_value: D) → datetime | D

field_for(name: str, book_id: int) → FieldValue

field_for(name: str, book_id: int, default_value: D) → FieldValue | D

book_id で指定された本のフィールド name の値を返します。そのような本が存在しない、またはフィールド name に定義された値がない、またはそのようなフィールドが存在しない場合、default_value が返されます。

default_value は、title、title_sort、authors、author_sort、series_indexには使用されません。これらは常にデータベースに値を持っているためです。default_value は、すべてのカスタム列に使用されます。

is_multiple フィールドの戻り値は、値が見つからない場合でも常にタプルです（つまり、default_value は無視されます）。例外は識別子で、その戻り値は常に辞書です。戻り値のタプルは常にリンク順、つまり作成順になります。

field_ids_for(name: str, book_id: int) → tuple[int, ...]

book_id で識別される本のフィールド name の値の ID を (タプルとして) 返します。値がない、またはそのような本がない、またはそのようなフィールドがない場合は、空のタプルが返されます。

field_supports_notes(field: str | None = None) → bool | Set[str]

指定されたフィールドがノートをサポートしている場合、Trueを返します。フィールドがNoneの場合、ノートをサポートするすべてのフィールドのfrozensetを返します。

find_identical_books(mi: Metadata, search_restriction: str = '', book_ids: set[int] | None = None) → set[int]

mi に著者のスーパーセットがあり、タイトルが同じ本を検索します (タイトルはあいまい検索)。 data_for_find_identical_books() も参照のこと。

format(book_id: int, fmt: str | None, as_file: Literal[False] = False, as_path: Literal[False] = False, preserve_filename: bool = False) → bytes | None

format(book_id: int, fmt: str | None, *, as_file: Literal[True]) → SpooledTemporaryFile | None

format(book_id: int, fmt: str | None, *, as_path: Literal[True], preserve_filename: bool = False) → str | None

format(book_id: int, fmt: str | None, as_file: bool = False, as_path: bool = False, preserve_filename: bool = False) → bytes | str | SpooledTemporaryFile | None

電子書籍の形式をバイト列として返します。形式が存在しない場合、または電子書籍ファイルに書き込む権限がない場合は、None を返します。

パラメータ:

• as_file -- True のとき、電子書籍の形式がファイルオブジェクトとして返されます。ただしファイルオブジェクトは SpooledTemporaryFile のため、形式を別のファイルにコピーする場合には、性能上の理由により、代わりに copy_format_to() を使用してください。

• as_path -- 形式ファイルを一時ファイルにコピーし、一時ファイルへのパスを返します

• preserve_filename -- True かつパスを返すとき、ファイル名はライブラリで使用されているものと同じです。ただしこれを使用すると、呼び出すたびに同じ一時ファイルを作成します (毎回作り直します)

format_abspath(book_id: int, fmt: str | None) → str | None

format 形式の電子書籍ファイルへの絶対パスを返します。これはこのAPIのスレッドセーフの約束を破るため、原則的に使用すべきではありません。代わりに copy_format_to() を使用してください。

現在これを使用しているのは、calibredbリスト、ビューア、編集ブック、元の形式とのcompare_format、アプリケーションを指定して開く、一括書誌編集、およびカタログ (get_data_as_dict() 経由で) のみです。

ビューア、アプリケーションを指定して本を開く、本の編集を除き、この呼び出しの結果を使用してファイル書き込み I/O を実行する人はいないと思います。

format_hash(book_id: int, fmt: str) → str

指定された本の指定された形式のハッシュを返します。ハッシュの種類はバックエンドに依存しますが、通常はSHA-256です。

format_metadata(book_id: int, fmt: str | None, allow_cache: bool = True, update_db: bool = False) → FormatMetadataDict

指定した本の指定した形式のパス、サイズ、および mtime を返します。パスに直接アクセスするとこのAPIのスレッドセーフの保証が破られるため、絶対に必要な場合を除いてはパスを使用しないでください。代わりに、copy_format_to() メソッドを使用してください。

パラメータ:

• allow_cache -- True のとき、キャッシュした値を使用します。そうでなければ遅いファイルアクセスが行われます。この API 以外からアクセスした場合、キャッシュ値が古い可能性があります。

• update_db -- True のとき、この本の max_size フィールドをデータベースで更新します

formats(book_id: int, verify_formats: bool = True) → tuple[str, ...]

指定された本のすべての形式のタプルを返します。 verify_formats が True の場合、ファイルがディスク上に存在することを検証します。

get_all_items_that_have_notes(field_name: str | None = None) → set[int] | dict[str, set[int]]

指定されたフィールドにノートがあるアイテムのすべてのID一覧 を返します。field_name が None の場合はすべてのフィールドを返します。

get_all_link_maps_for_book(book_id: int) → dict[str, dict[str, str]]

book_idで識別される本が参照するすべてのフィールドのリンクをすべて返します。book_idが存在しない場合は、このメソッドは {} を返します。

例: 著者AにリンクX、著者BにリンクY、タグSにリンクF、タグTにリンクGがあるとします。本1に著者AとタグTがある場合、このメソッドは {'authors':{'A':'X'}, 'tags':{'T', 'G'}} を返します。本2の著者が著者Aでも著者Bでもなく、タグもない場合、このメソッドは {} を返します。

パラメータ:

book_id -- 問い合わせるbook ID

戻り値:

{field: {field_value, link_value}, ... 空でないリンク値を持つ field_value を持つすべてのフィールドについて

get_book_path(book_id: int, sep: str = '/', unsafe: Literal[False] = False) → str

get_book_path(book_id: int, sep: str = '/', unsafe: bool = False) → str | None

指定されたIDに対応する本の相対パスを返します。ディレクトリ区切り文字を選択できるため、こちらの方が望ましいでしょう（デフォルトではOSの区切り文字が使用されます）。unsafeがTrueの場合、book_idがライブラリに存在しない場合はNoneを返します。

get_categories(sort: str = 'name', book_ids: Iterable[int] | None = None, already_fixed: str | None = None, first_letter_sort: bool = False, uncollapsed_categories: Container[str] | None = None) → OrderedDict[__annotationlib_name_1__, __annotationlib_name_2__]

タグブラウザの実装のために内部的に使用。

get_custom_book_data(name: str, book_ids: Iterable[int] = (), default: object = None) → dict[int, object]

name のデータを取得します。デフォルトでは、すべての book_id のデータが返されます。一部のデータのみが必要な場合は、本の ID のリストを渡します。 book_id から値へのマップを返します。特定の値をデコードできなかった場合は、デフォルトを使用します。

get_id_map(field: str, book_ids: Iterable[int] | None = None) → dict[int, str]

指定したフィールドについて、ID 番号から値へのマッピングを返します。フィールドは多対1または多対多のフィールドである必要があり、そうでない場合は ValueError が発生します。book_ids が None でない場合は、指定した本で使われている項目だけを返します。title フィールドの場合、ID は本の ID です。

get_ids_for_custom_book_data(name: str) → frozenset[int]

name がデータを持つ本の ID のセットを返します。

get_item_id(field: str, item_name: str, case_sensitive: bool = False) → int | None

item_name のアイテムIDを返します。見つからない場合はNoneを返します。get_item_ids()またはget_item_name_map()を使用して複数の名前を検索する場合、この関数は非常に遅くなります。同様に、大文字と小文字を区別する検索は、大文字と小文字を区別しない検索より高速です。

get_item_ids(field: str, item_names: Iterable[str], case_sensitive: bool = False) → dict[str, int | None]

item_name をアイテム ID にマッピングする辞書または None を返します。

get_item_name(field: str, item_id: int) → str

指定したフィールドの item_id で指定された項目の項目名を返します。get_id_map() も参照のこと。

get_item_name_map(field: str, normalize_func: Callable[[str], str] | None = None) → dict[str, int]

アイテム値とIDのマッピングを返します。

get_link_map(for_field: str) → dict[str, str]

指定されたフィールドのリンクの辞書を返します。

パラメータ:

for_field -- リンクマップが必要なフィールドのルックアップ名

戻り値:

空でないリンクについて {field_value:link_value, ...}

get_metadata(book_id: int, get_cover: bool = False, get_user_categories: bool = True, cover_as_data: bool = False) → Metadata

calibre.ebooks.metadata.book.base.Metadata オブジェクトとして book_id が指定する本の書誌を返します。ただし形式のリストは検証されません。 get_cover が True のとき、表紙が返されます。mi.coverとして一時ファイルへのパス、または cover_as_data が True であれば mi.cover_data として返されます。

get_next_series_num_for(series: str | None, field: str = 'series', current_indices: Literal[False] = False) → float

get_next_series_num_for(series: str | None, field: str = 'series', *, current_indices: Literal[True]) → dict[int, float]

指定されたシリーズの次のシリーズインデックスを返します。このとき、次のシリーズ番号の生成を制御するさまざまな設定が考慮されます。

パラメータ:

• field -- シリーズのようなフィールド (デフォルトはビルトインのシリーズ列)

• current_indices -- True のとき、代わりに book_id から現在の series_index 値へのマッピングを返します。

get_notes_resource(resource_hash: str) → dict | None

リソースデータと名前を含む辞書を返すか、指定されたハッシュを持つリソースが見つからない場合はNoneを返します。

get_pages(book_id: int) → Pages | None

特定の本のページ数情報を返す

get_proxy_metadata(book_id: int) → ProxyMetadata

get_metadata() と同様ですが、オンデマンドでデータベースから値を読み取るだけの ProxyMetadata オブジェクトを返す点が異なります。これは、返された書誌オブジェクトから少数のフィールドにアクセスするだけでよい場合、 get_metadata よりもはるかに高速です。

get_usage_count_by_id(field: str) → dict[int, int]

IDから、指定したフィールドのすべての値の使用回数へのマッピングを返します。これは、多対1または多対多のフィールドである必要があります。

has_book(mi: Metadata) → bool

渡された Metadata オブジェクトと同じタイトルのエントリがデータベースに含まれていれば True を返します。比較で大文字と小文字は区別されません。data_for_has_book() も参照のこと。

has_format(book_id: int, fmt: str | None) → bool

ディスク上に形式が存在すれば True を返します。

has_id(book_id: int) → bool

指定した book_id が db に存在すれば True を返します

import_note(field: str, item_id: int, path_to_html_file: str | bytes, path_is_data: bool = False) → int

以前にエクスポートしたノートまたは任意の HTML ファイルを、指定したアイテムのノートとしてインポートします。

init() → None

バックエンドからのデータでこのキャッシュを初期化します。

items_using_notes_resource(resource_hash: str) → frozenset[tuple[str, int]]

指定したハッシュのリソースを使用しているすべてのノートについて、(field, item_id) の組の集合を返します

items_with_notes_in_book(book_id: int) → dict[str, dict[int, str]]

指定された本のそのフィールドに関連付けられたノートを持つ、フィールドの辞書を返します。

link_for(field: str, item_id: int) → str | None

存在すれば指定されたアイテムのリンクを返します。存在しない場合は None を返します。

list_extra_files(book_id: int, use_cache: bool = False, pattern: str = '') → tuple[ExtraFile, ...]

本のディレクトリ内に存在する追加ファイルの情報を取得します。

パラメータ:

• book_id -- データベースの本のID

• pattern -- 検索するファイル名のパターン。空のパターンは、すべての追加ファイルに一致します。パターンは/を区切り文字として使用します。データディレクトリ内のファイルに一致させるには、DATA_FILE_PATTERN 定数を使用してください。

戻り値:

指定されたパターンに一致するすべての追加ファイルのタプル。タプルの各要素は ExtraFile(relpath, file_path, stat_result) です。relpathは、/を区切り文字として使用した、本ディレクトリへのファイルの相対パスです。stat_resultは、ファイルに対して os.stat() を呼び出した結果です。

mark_for_pages_recount(book_id: int = 0) → None

ページ数を再カウントするすべての本をマーク

merge_annotations_for_book(book_id: int, fmt: str, annots_list: Iterable[dict] | dict[str, list[dict]], user_type: str = 'local', user: str = 'viewer') → None

指定された注釈を、book_id、fm、user_type、および user の既存の注釈にマージします。

merge_extra_files(dest_id: int, src_ids: Iterable[int], replace: bool = False) → set[str | None]

src_ids から dest_id へ追加ファイルをマージします。ファイル名が衝突する時は、replace=True が指定されていない場合は自動的にファイル名を変更し、指定されている場合はファイルを置換します。

move_book_from_trash(book_id: int) → None

ゴミ箱フォルダから本を復元します。

move_format_from_trash(book_id: int, fmt: str) → None

ゴミ箱フォルダから形式を復元します。

multisort(fields: Sequence[tuple[str, bool]], ids_to_sort: Iterable[int] | None = None, virtual_fields: Mapping[str, SortableVirtualField] | None = None) → list[int]

並べ替えられた本の ID のリストを返します。ids_to_sort が None のとき、すべての ID を返します。

fields は、そのフォームの2 タプルのリストである必要があります (field_name、ascending=TrueまたはFalse)。最も重要なフィールドは最初の 2 タプルです。

notes_data_for(field: str, item_id: int) → NoteData | None

すべてのノートデータを辞書として返します。ノートが存在しない場合はNoneを返します。

notes_for(field: str, item_id: int) → str

ノートドキュメントを返します。存在しない場合は空文字列を返します。

notes_resources_used_by(field: str, item_id: int) → frozenset[str]

指定されたアイテムのノートで使用されるすべてのリソースのハッシュのセットを返します。

pages_needs_scan(books: Iterable[int] = ()) → set[int]

本のページ数を更新するのにスキャンが必要とマークされた本のサブセットを返します。もし存在しない時はすべての本となります。

pref(name: str, default: D, namespace: str | None = None, get_default_from_defaults: bool = False) → D

pref(name: str, default: None = None, namespace: str | None = None, get_default_from_defaults: bool = False) → object

指定した環境設定の値、または環境設定に指定がなければ default に指定した値を返します。

queue_pages_scan(book_id: int = 0, force: bool = False, by_user: bool = True) → None

スキャンが必要なすべての本のページ数を更新しながらスキャンを開始します。book_id が指定されている場合は、その本のみを対象にして常にスキャンされます。force が True の場合、既存のページ値（存在する場合）は破棄されます。そのため、既存の値が最新であっても、本は強制的に再スキャンされます。

read_backup(book_id: int) → bytes | None

本の OPF 書誌バックアップをバイト列として返します。バックアップが存在しない場合は None を返します。

refresh_format_sizes(size_map: dict[tuple[int, str], int]) → set[int]

指定されたフォーマットのディスク上のファイルサイズでデータベースを更新します。size_map は (book_id, fmt) をそのフォーマットのファイルサイズに対応付けます。これは、calibre の外部でファイルが変更されたことによって異なってしまった保存済みサイズを修正するために使用されます。保存済みサイズが変更された本の ID を返します。

remove_books(book_ids: Collection[int], permanent: bool = False) → None

book_ids で指定された本をデータベースから削除し、その形式ファイルも削除します。permanent がFalseの場合、形式ファイルはライブラリごとのゴミ箱ディレクトリに配置されます。

一部の本のファイルが削除できない、またはゴミ箱に移動できない場合、それらの本はそのまま残され、他のすべての本が削除された後に BooksNotRemoved が発生します。

remove_extra_files(book_id: int, relpaths: Iterable[str], permanent: bool = False) → dict[str, Exception | None]

指定された追加ファイルをゴミ箱または完全に削除します。

remove_formats(formats_map: Mapping[int, Iterable[str]], db_only: bool = False) → dict[int, set[str]]

指定した本から指定した形式を削除します。

パラメータ:

• formats_map -- book_id から、削除される本の形式のリストへのマッピング。

• db_only -- True のとき、その形式のレコードを db からだけ削除し、ファイルシステムにある実際の形式ファイルは削除しません。

戻り値:

本IDと、その本のファイルシステムから実際に削除された形式とのマップ

remove_items(field: str, item_ids: Iterable[int], restrict_to_book_ids: Iterable[int] | None = None) → set[int]

指定した ID を持つ指定したフィールドのすべてのアイテムを削除します。影響を受ける本の ID のセットを返します。 restrict_to_book_ids は、オプションの本の ID のセットです。指定すると、項目はそれらの本からのみ削除されます。

rename_extra_files(book_id: int, map_of_relpath_to_new_relpath: Mapping[str, str], replace: bool = False) → set[str]

追加データファイルを名称変更

rename_items(field: str, item_id_to_new_name_map: Mapping[int, str], change_index: bool = True, restrict_to_book_ids: Iterable[int] | None = None) → tuple[set[int], dict[int, int | None]]

タグやシリーズのような、多対多のフィールドから項目の名前を変更します。

パラメータ:

• change_index -- シリーズのようなフィールドで名前を変更する場合は、series_index の値も変更します。

• restrict_to_book_ids -- 名前の変更を実施しようとしている本の ID のセット。デフォルトではすべての本。

restore_book(book_id: int, mi: Metadata, last_modified: datetime, path: str, formats: Iterable[tuple[str, int, str]], annotations: Collection[JSONDict] = ()) → None

ファイルシステムにすでに存在する本の、データベース内のエントリを復元します

restore_original_format(book_id: int, original_fmt: str) → bool

以前に保存した ORIGINAL_FORMAT に指定した形式があれば、復元します。成功時に True を返します。復元が成功すると ORIGINAL_FORMAT は削除されます。

property safe_read_lock: SafeReadLock

安全な読み取りロックは、スレッドがすでに書き込みロックを持っている場合は何もせず、そうでない場合に読み取りロックを取得するロックです。これは、複合列が存在するときに検索キャッシュを更新すると発生する可能性がある DowngradeLockErrors を防ぐために必要です。検索キャッシュを更新すると排他ロックが保持されますが、複合列を検索するには、共有ロックを取得しようとする ProxyMetadata を介してフィールド値を読み取る必要があります。これのトリガーとなる別のシナリオもあるかもしれません。

このプロパティは、アクセスごとに新しいロックオブジェクトを返します。このロックオブジェクトは (性能上の理由で) 再帰的ではなく、必ず with cache.safe_read_lock: として with 文とともに使用する必要があります。そうしないと、よくないことが起こります。

save_original_format(book_id: int, fmt: str) → bool

指定した形式のコピーを ORIGINAL_FORMAT として保存し、既存の ORIGINAL_FORMAT を上書きします。

search(query: str, restriction: str | None = '', virtual_fields: dict[str, VirtualField] | None = None, book_ids: set[int] | None = None, allow_templates: bool = True) → set[int]

指定したクエリをデータベースで検索し、マッチした本のIDのセットを返します。

パラメータ:

• restriction -- 指定したクエリに AND される制限。ただし制限がキャッシュされるため、AND bの 検索は、制限 b よりも遅くなります。

• virtual_fields -- 内部使用 (検索する on_device のような仮想フィールド)

• book_ids -- None でないとき、すべての本を検索するのではなく、検索される本の ID のセット。

search_annotations(fts_engine_query: str, use_stemming: bool = True, highlight_start: str | None = None, highlight_end: str | None = None, snippet_size: int | None = None, annotation_type: str | None = None, restrict_to_book_ids: Container[int] | None = None, restrict_to_user: tuple[str, str] | None = None, ignore_removed: bool = False, annotation_style: Mapping[str, object] | None = None) → tuple[JSONDict, ...]

指定された全文検索クエリに一致する注釈をタプルで返します。

search_notes(fts_engine_query: str = '', use_stemming: bool = True, highlight_start: str | None = None, highlight_end: str | None = None, snippet_size: int | None = None, restrict_to_fields: tuple[str, ...] = (), return_text: bool = True, result_type: ~collections.abc.Callable[[~collections.abc.Iterator[NotesSearchResult]], T] = <class 'tuple'>, process_each_result: ~collections.abc.Callable[[NotesSearchResult], NotesSearchResult] | None = None, limit: int | None = None) → T

FTSインデックスを使用して注釈のテキストを検索します。クエリが空の場合は、すべてのノートを返します。

search_uses_templates(query: str) → bool

指定された検索クエリ（またはそのクエリが利用する保存済み検索）にテンプレート検索が含まれている場合、Trueを返します。このチェックは、クエリを評価することなく行われます。この機能は、信頼できないユーザーがテンプレートを含む検索式（保存済み検索など）を保存するのを防ぐために使用してください。保存された検索式は、後で（例えば仮想ライブラリなどで）テンプレートが許可された状態で評価される可能性があるためです。

クエリを解析できない場合、ParseExceptionをスローします。

set_annotations_for_book(book_id: int, fmt: str, annots_list: Iterable[tuple[JSONDict, float]], user_type: str = 'local', user: str = 'viewer') → None

指定された book_id、fmt、user_type、および user のすべての注釈を設定します。

set_conversion_options(options: Mapping[int, object], fmt: str = 'PIPE') → None

options は、{book_id:conversion_options} 形式のマップでなくてはなりません

set_cover(book_id_data_map: Mapping[int, CoverData]) → set[int]

この本の表紙を設定します。データは、QImage、QPixmap、ファイルオブジェクト、またはバイト列のいずれかです。 None にすることも可能で、その場合、既存の表紙はすべて削除されます。

set_field(name: str, book_id_to_val_map: Mapping[int, object], allow_case_change: bool = True, do_path_update: bool = True) → set[int]

name で指定したフィールドの値を設定します。変更の影響を受けたすべての本 の IDのセットを返します。

パラメータ:

• book_id_to_val_map -- book_id から、適用すべき値へのマッピング。

• allow_case_change -- True のとき、多対1または多対多フィールドの大文字と小文字が変更されます。たとえば、本にタグ tag1 があり、別の本のタグを Tag1 に設定した場合、allow_case_change が True であれば両方の本にタグ Tag1 が付けられ、そうでなければ両方にタグ tag1 が付けられます。

• do_path_update -- 内部利用。決して変更しないこと。

set_link_map(field: str, value_to_link_map: Mapping[str, str], only_set_if_no_existing_link: bool = False) → set[int]

フィールド内のアイテム値のリンクを設定します。注意: このメソッドは value_to_link_map にない値は変更しません。

パラメータ:

• field -- ルックアップ名

• value_to_link_map -- dict(field_value:link, ...) 引数はフィールドIDでなく、値であることに注意してください

戻り値:

リンクを設定することで変更された本

set_metadata(book_id: int, mi: Metadata, ignore_errors: bool = False, force_changes: bool = False, set_title: bool = True, set_authors: bool = True, allow_case_change: bool = False) → set[int]

Metadata オブジェクト mi からの本 id の本に書誌を設定します

force_changes= True を設定すると、miに空の値が含まれていても、強制的に set_metadata を更新します。この場合、'None' と 'empty' は区別されます。 mi.XXX が None のとき XXX は置き換えられませんが、そうでなければ置き換えられます。タグ、識別子、および表紙属性は特殊なケースです。タグと識別子は None に設定できないため、force_changes が true の場合は常に置き換えられます。mi には本に持たせたい値が必ず含まれるようにしてください。新しい表紙が提供されると表紙は常に変更されますが、削除されることはありません。なお、force_changes はタイトルや著者の設定には影響しません。

set_notes_for(field: str, item_id: int, doc: str, searchable_text: str = '', resource_hashes: Collection[str] = (), remove_unused_resources: bool = False) → int

ノートのドキュメントを設定します。検索可能なテキストがドキュメントと異なる場合は、searchable_text で指定してください。ドキュメントがリソースを参照している場合は、そのハッシュを resource_hashes に設定する必要があります。未使用のリソースをクリーンアップするには、remove_unused_resources を True に設定します。ノートを更新すると、そのノートに関連するリソースも自動的にクリーンアップされることに注意してください。

set_pages(book_id: int, pages: int = 0, algorithm: int = 0, format: str = '', format_size: int = 0) → None

指定された本のページ数情報を設定します。本が存在しない場合は、何も行いません。

set_pref(name: str, val: object, namespace: str | None = None) → None

指定した環境設定に指定した値を設定します。pref() も参照のこと。

split_if_is_multiple_composite(f: str, val: str) → str | list[str]

f が複合列のルックアップキーであり、列が is_multiple の場合、v を一意の空でない値に分割します。比較では大文字と小文字が区別されます。順序は保持されません。proxy metadata field getters（例：tags）との互換性のため、list() を返します。

tags_older_than(tag: str, delta: timedelta | None = None, must_have_tag: str | None = None, must_have_authors: Iterable[str] | None = None) → set[int]

指定した時間より古いタグ tag を持つすべての本の ID を返します。tag の比較で大文字と小文字は区別されません。

パラメータ:

• delta -- timedelta オブジェクト、または None。None のときにはそのタグの ID がすべて返されます。

• must_have_tag -- None でないとき、マッチするリストはこのタグが付いた本に制限されます

• must_have_authors -- 著者のリスト。 None でないとき、マッチするリストは指定された著者の本に制限されます (大文字と小文字は区別されません)。

unretire_note_for(field: str, item_id: int) → int

指定されたアイテムの、以前に廃止されたノートを復元します。ノートは、アイテムがデータベースから削除された時に削除されます。

update_annotations(annot_id_map: Mapping[int, JSONDict]) → None

注釈の更新

update_book_storage_for_book(book_id: int, fmt: str, entry: BookStorageEntry, user_type: str = 'local', user: str = 'viewer') → BookStorageEntry

指定された book_id、format、user_type、および user に対応する本ごとのストレージを設定します。ただし、既存のストレージが新しいものである場合は設定されません。更新後に有効となるストレージを返します。空のデータを含むエントリーを渡すことで、ストレージをクリアできます。

user_categories_for_books(book_ids: Iterable[int], proxy_metadata_map: Mapping[int, ProxyMetadata] | None = None) → dict[int, dict[str, list[list[str]]]]

指定した本のユーザカテゴリを返します。 proxy_metadata_map はオプションで、本の ProxyMetadata オブジェクトがすでに存在するコンテキストでパフォーマンスを向上させるのに役立ちます。これは、book_idsから対応するProxyMetadataオブジェクトへのマッピングでないといけません。

© Copyright Kovid Goyal. 最終更新 11月 06, 2026