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

지정된 필드가 노트를 지원하면 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) → str

모든 노트 데이터를 사전으로 반환하거나 노트가 존재하지 않으면 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을 반환합니다.

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. 마지막 업데이트 날짜: 4월 10, 2026.