データベースの 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, library_database_instance=None)

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

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

class EventType(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

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

When the indexing progress changes

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)

metadata_changed = 1

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

add_books(books, add_duplicates=True, apply_import_tags=True, preserve_uuid=False, run_hooks=True, dbapi=None)

指定した本をライブラリに追加。本は 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, val_map, delete_first=False)

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

add_extra_files(book_id, map_of_relpath_to_stream_or_path, replace=True, auto_rename=False)

Add extra data files

add_format(book_id, fmt, stream_or_path, replace=True, run_hooks=True, dbapi=None)

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

パラメータ:

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

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

• dbapi -- 内部利用のみ。

add_listener(event_callback_function, check_already_added=False)

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

all_book_ids(type=<class 'frozenset'>)

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

all_field_for(field, book_ids, default_value=None)

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

all_field_ids(name)

フィイールド name のすべての値の凍結セット。

all_field_names(field)

すべてのフィールド名の凍結セット (多対 1 と多対多のフィールドにのみ使用)

author_data(author_ids=None)

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

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

author_sort_from_authors(authors, key_func=<function make_change_case_func.<locals>.change_case>)

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

books_for_field(name, item_id)

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

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

books_in_virtual_library(vl, search_restriction=None, virtual_fields=None)

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

compress_covers(book_ids, jpeg_quality=100, progress_callback=None)

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

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

copy_cover_to(book_id, dest, use_hardlink=False, report_file_size=None)

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

copy_format_to(book_id, fmt, dest, use_hardlink=False, report_file_size=None)

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

cover(book_id, as_file=False, as_image=False, as_path=False, as_pixmap=False)

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

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

パラメータ:

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

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

• as_pixmap -- If True return the image as a QPixmap object

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

data_for_find_identical_books()

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

data_for_has_book()

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

delete_custom_book_data(name, book_ids=())

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

delete_trash_entry(book_id, category)

Delete an entry from the trash. Here category is 'b' for books and 'f' for formats.

embed_metadata(book_ids, only_fmts=None, report_error=None, report_progress=None)

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

expire_old_trash()

Expire entries from the trash that are too old

fast_field_for(field_obj, book_id, default_value=None)

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

field_for(name, book_id, default_value=None)

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

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

The returned value for is_multiple fields are always tuples, even when no values are found (in other words, default_value is ignored). The exception is identifiers for which the returned value is always a dictionary. The returned tuples are always in link order, that is, the order in which they were created.

field_ids_for(name, book_id)

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

find_identical_books(mi, search_restriction='', book_ids=None)

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

format(book_id, fmt, as_file=False, as_path=False, preserve_filename=False)

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

パラメータ:

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

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

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

format_abspath(book_id, fmt)

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

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

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

format_hash(book_id, fmt)

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

format_metadata(book_id, fmt, allow_cache=True, update_db=False)

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

パラメータ:

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

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

formats(book_id, verify_formats=True)

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

get_all_link_maps_for_book(book_id)

Returns all links for all fields referenced by book identified by book_id. If book_id doesn't exist then the method returns {}.

Example: Assume author A has link X, author B has link Y, tag S has link F, and tag T has link G. If book 1 has author A and tag T, this method returns {'authors':{'A':'X'}, 'tags':{'T', 'G'}}. If book 2's author is neither A nor B and has no tags, this method returns {}.

パラメータ:

book_id -- the book id in question.

戻り値:

{field: {field_value, link_value}, ... for all fields with a field_value having a non-empty link value for that book

get_categories(sort='name', book_ids=None, already_fixed=None, first_letter_sort=False)

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

get_custom_book_data(name, book_ids=(), default=None)

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

get_id_map(field)

指定したフィールドの ID 番号から値へのマッピングを返します。フィールドは多対1または多対多のフィールドである必要があります。そうでない場合、ValueErrorが発生します。

get_ids_for_custom_book_data(name)

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

get_item_id(field, item_name)

Return the item id for item_name (case-insensitive) or None if not found

get_item_ids(field, item_names)

item_name の項目 ID を返します (大文字と小文字は区別しません)

get_item_name(field, item_id)

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

get_link_map(for_field)

Return a dictionary of links for the supplied field.

パラメータ:

for_field -- the lookup name of the field for which the link map is desired

戻り値:

{field_value:link_value, ...} for non-empty links

get_metadata(book_id, get_cover=False, get_user_categories=True, cover_as_data=False)

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, field='series', current_indices=False)

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

パラメータ:

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

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

get_proxy_metadata(book_id)

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

get_usage_count_by_id(field)

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

has_book(mi)

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

has_format(book_id, fmt)

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

has_id(book_id)

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

init()

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

list_extra_files(book_id, use_cache=False, pattern='') → Tuple[ExtraFile, ...]

Get information about extra files in the book's directory.

パラメータ:

• book_id -- the database book id for the book

• pattern -- the pattern of filenames to search for. Empty pattern matches all extra files. Patterns must use / as separator. Use the DATA_FILE_PATTERN constant to match files inside the data directory.

戻り値:

A tuple of all extra files matching the specified pattern. Each element of the tuple is ExtraFile(relpath, file_path, stat_result). Where relpath is the relative path of the file to the book directory using / as a separator. stat_result is the result of calling os.stat() on the file.

merge_extra_files(dest_id, src_ids, replace=False)

Merge the extra files from src_ids into dest_id. Conflicting files are auto-renamed unless replace=True in which case they are replaced.

move_book_from_trash(book_id)

Undelete a book from the trash directory

move_format_from_trash(book_id, fmt)

Undelete a format from the trash directory

multisort(fields, ids_to_sort=None, virtual_fields=None)

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

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

pref(name, default=None, namespace=None)

指定した環境設定の値、または環境設定に指定がなければデフォルト値を返します。

read_backup(book_id)

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

remove_books(book_ids, permanent=False)

Remove the books specified by the book_ids from the database and delete their format files. If permanent is False, then the format files are placed in the per-library trash directory.

remove_formats(formats_map, db_only=False)

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

パラメータ:

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

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

戻り値:

A map of book id to set of formats actually deleted from the filesystem for that book

remove_items(field, item_ids, restrict_to_book_ids=None)

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

rename_items(field, item_id_to_new_name_map, change_index=True, restrict_to_book_ids=None)

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

パラメータ:

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

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

restore_book(book_id, mi, last_modified, path, formats, annotations=())

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

restore_original_format(book_id, original_fmt)

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

property safe_read_lock

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

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

save_original_format(book_id, fmt)

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

search(query, restriction='', virtual_fields=None, book_ids=None)

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

パラメータ:

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

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

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

set_conversion_options(options, fmt='PIPE')

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

set_cover(book_id_data_map)

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

set_field(name, book_id_to_val_map, allow_case_change=True, do_path_update=True)

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, value_to_link_map, only_set_if_no_existing_link=False)

Sets links for item values in field. Note: this method doesn't change values not in the value_to_link_map

パラメータ:

• field -- the lookup name

• value_to_link_map -- dict(field_value:link, ...). Note that these are values, not field ids.

戻り値:

books changed by setting the link

set_metadata(book_id, mi, ignore_errors=False, force_changes=False, set_title=True, set_authors=True, allow_case_change=False)

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

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

set_pref(name, val, namespace=None)

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

split_if_is_multiple_composite(f, val)

If f is a composite column lookup key and the column is is_multiple then split v into unique non-empty values. The comparison is case sensitive. Order is not preserved. Return a list() for compatibility with proxy metadata field getters, for example tags.

tags_older_than(tag, delta=None, must_have_tag=None, must_have_authors=None)

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

パラメータ:

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

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

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

user_categories_for_books(book_ids, proxy_metadata_map=None)

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

© Copyright Kovid Goyal. 最終更新 5月 29, 2023