데이터베이스 인터페이스에 대한 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(*values)

book_created = 4

데이터베이스에 새 책 레코드가 생성될 때, 책 ID를 유일한 인자로 전달합니다

book_edited = 8

책 형식이 편집될 때, 인자: (book_id, fmt)

books_removed = 5

책이 데이터베이스에서 제거될 때, 책 ID 목록을 유일한 인자로 전달합니다

format_added = 2

책에 형식이 추가될 때, 인자: (book_id, format)

formats_removed = 3

책에서 형식이 제거될 때, 인자: (책 ID에서 해당 책에서 제거된 형식 집합으로의 매핑)

indexing_progress_changed = 9

인덱싱 진행률이 변경될 때

items_removed = 7

태그나 저자 같은 항목이 일부 책에서 제거될 때. 인자: (필드 이름, 영향을 받은 책 ID, 제거된 항목의 ID)

items_renamed = 6

태그나 저자 같은 항목이 일부 또는 모든 책에서 이름이 변경될 때. 인자: (필드 이름, 영향을 받은 책 ID, 이전 항목 ID에서 새 항목 ID로의 매핑)

links_changed = 11

항목과 연결된 링크가 변경될 때, 인자: (필드 이름, item_ids)

metadata_changed = 1

일부 책의 일부 메타데이터가 변경될 때, 인자: (변경된 필드 이름, 영향을 받은 책 ID 집합)

notes_changed = 10

항목과 연결된 노트가 변경될 때, 인자: (필드 이름, item_ids)

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

지정된 책을 라이브러리에 추가합니다. books는 2-튜플의 반복 가능 객체여야 하며, 각 2-튜플은 (mi, format_map) 형식입니다. 여기서 mi는 Metadata 객체이고 format_map은 {fmt: path_or_stream} 형식의 사전입니다. 예: {'EPUB': '/path/to/file.epub'}.

두 목록의 쌍을 반환합니다: ids, duplicates. ``ids``는 데이터베이스에 새로 생성된 모든 책의 책 ID를 포함합니다. ``duplicates``는 :meth:`has_book`이 사용하는 간단한 중복 감지 휴리스틱에 따라 데이터베이스에 이미 존재하는 모든 책의 :code:`(mi, format_map)`을 포함합니다.

add_custom_book_data(name, val_map, delete_first=False)

name에 대한 데이터를 추가합니다. 여기서 val_map은 book_id에서 값으로의 매핑입니다. delete_first가 True이면 name에 대해 이전에 저장된 모든 데이터가 제거됩니다.

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

추가 데이터 파일을 추가합니다

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)

이 데이터베이스에서 특정 작업이 수행된 후 호출될 콜백 함수를 등록합니다. 함수는 세 개의 인자를 받아야 합니다: (EventType, library_id, event_type_specific_data)

add_notes_resource(path_or_stream_or_data, name: str, mtime: float | None = None) → int

지정된 리소스를 추가하여 노트에서 참조할 수 있도록 하고 해당 콘텐츠 해시를 반환합니다

all_annotation_styles()

모든 내장 주석 스타일의 튜플을 반환합니다.

all_annotation_types()

데이터베이스의 모든 주석 유형의 튜플을 반환합니다.

all_annotation_users()

주석이 있는 모든 (user_type, 사용자 이름)의 튜플을 반환합니다.

all_annotations(restrict_to_user=None, limit=None, annotation_type=None, annotation_style=None, ignore_removed=False, restrict_to_book_ids=None)

지정된 조건과 일치하는 모든 주석의 튜플을 반환합니다. `ignore_removed`는 제거된(삭제된) 주석도 반환할지 여부를 제어합니다. 제거된 주석은 주석 병합에 사용되는 골격일 뿐입니다.

all_annotations_for_book(book_id)

지정된 book_id에 대한 모든 주석을 format, user_type, user, annotation 키를 가진 사전으로 포함하는 튜플을 반환합니다. 여기서 annotation은 주석 데이터입니다.

all_book_ids(type=<class 'frozenset'>)

모든 알려진 책 ID의 고정 집합입니다.

all_field_for(field, book_ids, default_value=None)

field_for와 같지만, 여러 책에 대해 동시에 작동합니다

all_field_ids(name)

필드 ``name``의 모든 값에 대한 ID의 고정 집합입니다.

all_field_names(field)

모든 필드 이름의 고정 집합입니다(다대일 및 다대다 필드에만 사용해야 합니다)

annotation_count_for_book(book_id)

데이터베이스에서 사용 가능한 지정된 책의 주석 수를 반환합니다.

annotations_map_for_book(book_id, fmt, user_type='local', user='viewer')

지정된 book_id, format, user 및 user_type에 대한 주석 유형 -> 주석 데이터의 매핑을 반환합니다.

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

저자 데이터를 키가 있는 사전으로 반환: 이름, 정렬, 링크

지정된 ID를 가진 저자를 찾을 수 없으면 빈 사전이 반환됩니다. author_ids가 None이면 모든 저자의 데이터가 반환됩니다.

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

저자 목록이 주어지면, 계산된 문자열보다 저자와 연결된 저자 정렬을 우선하여 저자들의 author_sort 문자열을 반환합니다.

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

지정된 저자들의 저자 정렬을 반환합니다.

지정된 ID를 가진 저자를 찾을 수 없으면 빈 사전이 반환됩니다. author_ids가 None이면 모든 저자의 데이터가 반환됩니다.

books_for_field(name, item_id)

항목이 필드 ``name``에 속하는 경우, ``item_id``로 식별된 항목과 연결된 모든 책을 반환합니다.

반환값은 책 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 – True이면 이미지를 QPixmap 객체로 반환합니다

• as_path – True이면 이미지를 임시 파일을 가리키는 경로로 반환합니다

data_for_find_identical_books()

데이터베이스에 접근하지 않는 워커 프로세스에서 :meth:`find_identical_books`를 구현하는 데 사용할 수 있는 데이터를 반환합니다. 구현은 db.utils를 참조하십시오.

data_for_has_book()

:meth:`has_book`에 사용하기에 적합한 데이터를 반환합니다. 이는 데이터베이스에 접근하지 않는 워커 프로세스에서 :meth:`has_book`의 구현에 사용할 수 있습니다.

delete_annotations(annot_ids)

지정된 ID의 주석을 삭제합니다.

delete_custom_book_data(name, book_ids=())

name에 대한 데이터를 삭제합니다. 기본적으로 모든 데이터를 삭제하며, 일부 book_id에 대한 데이터만 삭제하려면 book_id 목록을 전달하십시오.

delete_trash_entry(book_id, category)

휴지통에서 항목을 삭제합니다. 여기서 category는 책의 경우 ‘b’, 형식의 경우 ‘f’입니다.

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

지정된 book_ids의 모든 형식에 있는 메타데이터를 데이터베이스의 현재 메타데이터로 업데이트합니다.

expire_old_trash()

너무 오래된 휴지통 항목을 만료시킵니다

export_note(field, item_id) → str

노트를 data: URL로 임베드된 이미지가 포함된 단일 HTML 문서로 내보냅니다

fast_field_for(field_obj, book_id, default_value=None)

field_for와 같지만, 필드 객체를 얻기 위한 추가 조회를 피합니다

field_for(name, book_id, default_value=None)

``book_id``로 식별된 책의 필드 ``name``의 값을 반환합니다. 해당 책이 존재하지 않거나 필드 ``name``에 대해 정의된 값이 없거나 해당 필드가 존재하지 않으면 ``default_value``가 반환됩니다.

``default_value``는 title, title_sort, authors, author_sort, series_index에는 사용되지 않습니다. 이 필드들은 항상 데이터베이스에 값이 있기 때문입니다. ``default_value``는 모든 사용자 정의 열에 사용됩니다.

is_multiple 필드의 반환값은 값이 발견되지 않아도 항상 튜플입니다(즉, default_value는 무시됩니다). 예외적으로 identifiers의 반환값은 항상 사전입니다. 반환된 튜플은 항상 링크 순서, 즉 생성된 순서로 반환됩니다.

field_ids_for(name, book_id)

``book_id``로 식별된 책에서 필드 ``name``이 가진 값에 대한 ID를 튜플로 반환합니다. 값이 없거나 해당 책이 없거나 해당 필드가 없으면 빈 튜플이 반환됩니다.

field_supports_notes(field=None) → bool | frozenset

지정된 필드가 노트를 지원하면 True를 반환합니다. 필드가 None이면 노트를 지원하는 모든 필드의 frozenset을 반환합니다.

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

mi의 저자를 포함하고 같은 제목을 가진 책을 찾습니다(제목은 퍼지 매칭됩니다). :meth:`data_for_find_identical_books`도 참조하십시오.

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

전자책 형식을 바이트 문자열로 반환하거나, 형식이 존재하지 않거나 전자책 파일에 대한 쓰기 권한이 없으면 `None`을 반환합니다.

매개변수:

• as_file – True이면 전자책 형식이 파일 객체로 반환됩니다. 파일 객체는 SpooledTemporaryFile이므로, 형식을 다른 파일에 복사하려는 경우 성능을 위해 :meth:`copy_format_to`를 대신 사용하십시오.

• as_path – 형식 파일을 임시 파일에 복사하고 해당 임시 파일의 경로를 반환합니다

• preserve_filename – True이고 경로를 반환하는 경우 파일 이름은 라이브러리에서 사용되는 것과 동일합니다. 이를 사용하면 반복 호출 시 동일한 임시 파일이 반환됩니다(매번 다시 생성됨)

format_abspath(book_id, fmt)

format 형식의 전자책 파일에 대한 절대 경로를 반환합니다. 이는 이 API의 스레드 안전성을 깨뜨리므로 거의 사용해서는 안 됩니다. 대신 :meth:`copy_format_to`를 사용하십시오.

현재 calibredb list, 뷰어, 책 편집, 원본 형식과의 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의 스레드 안전 보장이 깨지므로, 반드시 필요한 경우가 아니면 path를 사용해서는 안 됩니다. 대신 copy_format_to() 메서드를 사용하십시오.

매개변수:

• allow_cache – ``True``이면 캐시된 값이 사용되고, 그렇지 않으면 느린 파일 시스템 접근이 수행됩니다. 이 API 외부에서 파일 시스템에 접근이 수행된 경우 캐시 값이 오래되었을 수 있습니다.

• update_db – ``True``이면 이 책에 대한 데이터베이스의 max_size 필드가 업데이트됩니다.

formats(book_id, verify_formats=True)

지정된 책의 모든 형식의 튜플을 반환합니다. verify_formats가 True이면 파일이 디스크에 존재하는지 확인합니다.

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

지정된 필드에서 노트가 있는 모든 항목의 item_ids를 반환하거나, field_name이 None이면 모든 필드에 대해 반환합니다

get_all_link_maps_for_book(book_id)

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 – 해당 책 ID입니다.

반환:

해당 책에 대해 field_value가 비어 있지 않은 링크 값을 가진 모든 필드에 대한 {field: {field_value, link_value}, …}

get_book_path(book_id, sep='/', unsafe=False)

지정된 ID에 해당하는 책의 상대 경로를 반환합니다. 디렉터리 구분자를 직접 지정할 수 있으므로 이 방법을 권장하며, 기본값은 OS에서 사용하는 구분자를 따릅니다. unsafe가 True인 경우, book_id가 라이브러리에 존재하지 않을 때 None을 반환할 수 있습니다.

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

태그 브라우저를 구현하는 데 내부적으로 사용됩니다

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

name에 대한 데이터를 가져옵니다. 기본적으로 모든 book_id의 데이터를 반환하며, 일부 데이터만 원하면 book_id 목록을 전달하십시오. book_id에서 값으로의 매핑을 반환합니다. 특정 값을 디코딩할 수 없으면 해당 값에 기본값을 사용합니다.

get_id_map(field)

지정된 필드에 대한 ID 번호에서 값으로의 매핑을 반환합니다. 필드는 다대일 또는 다대다 필드여야 하며, 그렇지 않으면 ValueError가 발생합니다.

get_ids_for_custom_book_data(name)

name에 데이터가 있는 book_id의 집합을 반환합니다.

get_item_id(field, item_name, case_sensitive=False)

item_name에 대한 항목 ID를 반환하거나 찾지 못하면 None을 반환합니다. 여러 이름에 대해 조회를 수행하는 경우 이 함수는 매우 느리므로 get_item_ids()나 get_item_name_map()을 사용하십시오. 마찬가지로 대소문자 구분 조회가 대소문자 무시 조회보다 빠릅니다.

get_item_ids(field, item_names, case_sensitive=False)

item_name을 항목 ID에 매핑하는 사전을 반환하거나 None을 반환합니다

get_item_name(field, item_id)

지정된 필드에서 item_id로 지정된 항목의 항목 이름을 반환합니다. :meth:`get_id_map`도 참조하십시오.

get_item_name_map(field, normalize_func=None)

항목 값에서 ID로의 매핑을 반환합니다

get_link_map(for_field)

제공된 필드에 대한 링크의 사전을 반환합니다.

매개변수:

for_field – 링크 맵이 필요한 필드의 조회 이름

반환:

비어 있지 않은 링크에 대한 {field_value:link_value, …}

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

book_id로 식별된 책의 메타데이터를 calibre.ebooks.metadata.book.base.Metadata 객체로 반환합니다. 형식 목록은 검증되지 않음에 유의하십시오. 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_notes_resource(resource_hash) → dict | None

리소스 데이터와 이름이 포함된 사전을 반환하거나, 지정된 해시의 리소스를 찾을 수 없으면 None을 반환합니다

get_pages(book_id: int) → Pages | None

지정된 책의 페이지 수 정보를 반환합니다

get_proxy_metadata(book_id)

:meth:`get_metadata`와 비슷하지만, 필요할 때만 데이터베이스에서 값을 읽는 ProxyMetadata 객체를 반환합니다. 반환된 메타데이터 객체에서 소수의 필드만 접근해야 할 때 get_metadata보다 훨씬 빠릅니다.

get_usage_count_by_id(field)

다대일 또는 다대다 필드여야 하는 지정된 필드의 모든 값에 대한 ID에서 사용 횟수로의 매핑을 반환합니다.

has_book(mi)

데이터베이스에 전달된 Metadata 객체와 같은 제목의 항목이 포함되어 있으면 True를 반환합니다. 비교는 대소문자를 구분하지 않습니다. :meth:`data_for_has_book`도 참조하십시오.

has_format(book_id, fmt)

형식이 디스크에 존재하면 True를 반환합니다

has_id(book_id)

지정된 book_id가 데이터베이스에 존재하면 True를 반환합니다

import_note(field, item_id, path_to_html_file, path_is_data=False)

이전에 내보낸 노트나 임의의 HTML 파일을 지정된 항목의 노트로 가져옵니다

init()

백엔드의 데이터로 이 캐시를 초기화합니다.

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

지정된 책의 각 필드에 대해 연결된 노트가 있는 항목의 필드에서 항목으로의 사전을 반환합니다

link_for(field, item_id)

지정된 항목의 링크가 있으면 반환하고, 찾지 못하면 None을 반환합니다

list_extra_files(book_id, use_cache=False, pattern='') → 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, fmt, annots_list, user_type='local', user='viewer')

지정된 주석을 book_id, fm, user_type, user에 대한 기존 주석에 병합합니다.

merge_extra_files(dest_id, src_ids, replace=False)

src_ids의 추가 파일을 dest_id에 병합합니다. 충돌하는 파일은 자동 이름이 변경되며, replace=True이면 교체됩니다.

move_book_from_trash(book_id)

휴지통 디렉터리에서 책을 복원합니다

move_format_from_trash(book_id, fmt)

휴지통 디렉터리에서 형식을 복원합니다

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

정렬된 책 ID의 목록을 반환합니다. ids_to_sort가 None이면 모든 책 ID가 반환됩니다.

fields는 (field_name, ascending=True 또는 False) 형식의 2-튜플 목록이어야 합니다. 가장 중요한 필드가 첫 번째 2-튜플입니다.

notes_data_for(field, item_id) → dict[str, Any] | None

모든 노트 데이터를 사전으로 반환하거나 노트가 존재하지 않으면 None을 반환합니다

notes_for(field, item_id) → str

노트 문서를 반환하거나 찾지 못하면 빈 문자열을 반환합니다

notes_resources_used_by(field, item_id)

지정된 항목의 노트가 사용하는 모든 리소스의 리소스 해시 집합을 반환합니다

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

페이지 수 업데이트를 위해 스캔이 필요한 것으로 표시된 책의 하위 집합을 반환합니다(또는 비어 있으면 모든 책)

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

지정된 환경 설정의 값을 반환하거나, 환경 설정이 설정되지 않은 경우 ``default``로 지정된 값을 반환합니다.

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

스캔이 필요한 모든 책의 페이지 수를 업데이트하는 스캔을 시작합니다. book_id가 지정되면 해당 책만 스캔되며 항상 스캔됩니다. `force`가 True이면 기존 페이지 값(있는 경우)이 무시되어 기존 값이 최신 상태여도 책이 강제로 다시 스캔됩니다.

read_backup(book_id)

책의 OPF 메타데이터 백업을 바이트 문자열로 반환하거나 해당 백업이 존재하지 않으면 None을 반환합니다.

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

Update the database with the on-disk sizes of the specified format files. size_map maps (book_id, fmt) to the size of the format file. Used to fix stored sizes that have gone stale because format files were changed outside of calibre. Returns the ids of the books whose stored sizes were changed.

remove_books(book_ids, permanent=False)

book_ids로 지정된 책을 데이터베이스에서 제거하고 해당 형식 파일을 삭제합니다. ``permanent``가 False이면 형식 파일이 라이브러리별 휴지통 디렉터리에 배치됩니다.

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

지정된 추가 파일을 휴지통으로 보내거나 영구적으로 삭제합니다.

remove_formats(formats_map, db_only=False)

지정된 형식을 지정된 책에서 제거합니다.

매개변수:

• formats_map – book_id에서 책에서 제거할 형식 목록으로의 매핑입니다.

• db_only – True이면 데이터베이스에서 형식에 대한 기록만 제거하고, 실제 형식 파일을 파일 시스템에서 삭제하지 않습니다.

반환:

책 ID에서 해당 책의 파일 시스템에서 실제로 삭제된 형식의 집합으로의 매핑

remove_items(field, item_ids, restrict_to_book_ids=None)

지정된 필드에서 지정된 ID를 가진 모든 항목을 삭제합니다. 영향을 받은 책 ID의 집합을 반환합니다. ``restrict_to_book_ids``는 선택적 책 ID 집합입니다. 지정된 경우 해당 책에서만 항목이 제거됩니다.

rename_extra_files(book_id, map_of_relpath_to_new_relpath, replace=False)

추가 데이터 파일의 이름을 변경합니다

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, allow_templates=True)

지정된 쿼리로 데이터베이스를 검색하여 일치하는 책 ID의 집합을 반환합니다.

매개변수:

• restriction – 지정된 쿼리에 AND로 연결되는 제한 조건입니다. 제한 조건은 캐시되므로, a AND b 검색이 제한 조건 b로 a를 검색하는 것보다 느립니다.

• virtual_fields – 내부적으로 사용됩니다(on_device 같은 가상 필드를 검색하기 위해).

• book_ids – None이 아닌 경우, 모든 책을 검색하는 대신 검색할 책 ID의 집합입니다.

search_annotations(fts_engine_query, use_stemming=True, highlight_start=None, highlight_end=None, snippet_size=None, annotation_type=None, restrict_to_book_ids=None, restrict_to_user=None, ignore_removed=False, annotation_style=None)

지정된 전체 텍스트 쿼리와 일치하는 주석의 튜플을 반환합니다.

search_notes(fts_engine_query='', use_stemming=True, highlight_start=None, highlight_end=None, snippet_size=None, restrict_to_fields=(), return_text=True, result_type=<class 'tuple'>, process_each_result=None, limit=None)

FTS 색인을 사용하여 노트의 텍스트를 검색합니다. 쿼리가 비어 있으면 모든 노트를 반환합니다.

set_annotations_for_book(book_id, fmt, annots_list, user_type='local', user='viewer')

지정된 book_id, fmt, user_type, user에 대한 모든 주석을 설정합니다.

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_ids의 매핑입니다.

• allow_case_change – True이면 다대일 또는 다대다 필드의 대소문자가 변경됩니다. 예를 들어, 책에 태그 ``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)

필드의 항목 값에 대한 링크를 설정합니다. 참고: 이 메서드는 value_to_link_map에 없는 값은 변경하지 않습니다

매개변수:

• field – 조회 이름

• value_to_link_map – dict(field_value:link, …). 이것들은 필드 ID가 아닌 값임에 유의하십시오.

반환:

링크 설정으로 변경된 책

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_notes_for(field, item_id, doc: str, searchable_text: str = '', resource_hashes=(), remove_unused_resources=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, val, namespace=None)

지정된 환경 설정을 지정된 값으로 설정합니다. :meth:`pref`도 참조하십시오.

split_if_is_multiple_composite(f, val)

f가 복합 열 조회 키이고 열이 is_multiple이면 v를 고유한 비어 있지 않은 값으로 분할합니다. 비교는 대소문자를 구분합니다. 순서는 유지되지 않습니다. 프록시 메타데이터 필드 getter(예: 태그)와의 호환성을 위해 list()를 반환합니다.

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이 아닌 경우 일치 목록이 해당 저자를 가진 책으로 제한됩니다(대소문자 무시).

unretire_note_for(field, item_id) → int

지정된 항목에 대해 이전에 은퇴된 노트를 은퇴 해제합니다. 항목이 데이터베이스에서 제거될 때 노트가 은퇴됩니다

update_annotations(annot_id_map)

주석을 업데이트합니다.

user_categories_for_books(book_ids, proxy_metadata_map=None)

지정된 책의 사용자 카테고리를 반환합니다. proxy_metadata_map은 선택적이며, 해당 책의 ProxyMetadata 객체가 이미 존재하는 맥락에서 성능 향상에 유용합니다. book_ids에서 해당 ProxyMetadata 객체로의 매핑이어야 합니다.

© 저작권 Kovid Goyal. 마지막 업데이트 날짜: 9월 18, 2026.