Cutlery/calibre
1
0
Fork 0
mirror of https://github.com/kovidgoyal/calibre.git synced 2025-07-09 03:04:10 -04:00
Code Issues Packages Projects Releases Wiki Activity

Document the annotations API at least cursorily

Browse Source
This commit is contained in:
Kovid Goyal 2024-08-17 16:51:45 +05:30
parent 3173b9dd58
commit c778211992
No known key found for this signature in database
GPG Key ID: 06BC317B515ACE7C
1 changed files with 36 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
src/calibre/db/cache.py
View File

@ -3185,6 +3185,9 @@ class Cache:
@read_api @read_api
def annotations_map_for_book(self, book_id, fmt, user_type='local', user='viewer'): def annotations_map_for_book(self, book_id, fmt, user_type='local', user='viewer'):
'''
Return a map of annotation type -> annotation data for the specified book_id, format, user and user_type.
'''
ans = {} ans = {}
for annot in self.backend.annotations_for_book(book_id, fmt, user_type, user): for annot in self.backend.annotations_for_book(book_id, fmt, user_type, user):
ans.setdefault(annot['type'], []).append(annot) ans.setdefault(annot['type'], []).append(annot)
@ -3192,22 +3195,40 @@ class Cache:
@read_api @read_api
def all_annotations_for_book(self, book_id): def all_annotations_for_book(self, book_id):
'''
Return a tuple containing all annotations for the specified book_id as a dict with keys:
`format`, `user_type`, `user`, `annotation`. Here, annotation is the annotation data.
'''
return tuple(self.backend.all_annotations_for_book(book_id)) return tuple(self.backend.all_annotations_for_book(book_id))
@read_api @read_api
def annotation_count_for_book(self, book_id): def annotation_count_for_book(self, book_id):
'''
Return the number of annotations for the specified book available in the database.
'''
return self.backend.annotation_count_for_book(book_id) return self.backend.annotation_count_for_book(book_id)
@read_api @read_api
def all_annotation_users(self): def all_annotation_users(self):
'''
Return a tuple of all (user_type, user name) that have annotations.
'''
return tuple(self.backend.all_annotation_users()) return tuple(self.backend.all_annotation_users())
@read_api @read_api
def all_annotation_types(self): def all_annotation_types(self):
'''
Return a tuple of all annotation types in the database.
'''
return tuple(self.backend.all_annotation_types()) return tuple(self.backend.all_annotation_types())
@read_api @read_api
def all_annotations(self, restrict_to_user=None, limit=None, annotation_type=None, ignore_removed=False, restrict_to_book_ids=None): def all_annotations(self, restrict_to_user=None, limit=None, annotation_type=None, ignore_removed=False, restrict_to_book_ids=None):
'''
Return a tuple of all annotations matching the specified criteria.
`ignore_removed` controls whether removed (deleted) annotations are also returned. Removed annotations are just a skeleton
used for merging of annotations.
'''
return tuple(self.backend.all_annotations(restrict_to_user, limit, annotation_type, ignore_removed, restrict_to_book_ids)) return tuple(self.backend.all_annotations(restrict_to_user, limit, annotation_type, ignore_removed, restrict_to_book_ids))
@read_api @read_api
@ -3223,6 +3244,9 @@ class Cache:
restrict_to_user=None, restrict_to_user=None,
ignore_removed=False ignore_removed=False
): ):
'''
Return of a tuple of annotations matching the specified Full-text query.
'''
return tuple(self.backend.search_annotations( return tuple(self.backend.search_annotations(
fts_engine_query, use_stemming, highlight_start, highlight_end, fts_engine_query, use_stemming, highlight_start, highlight_end,
snippet_size, annotation_type, restrict_to_book_ids, restrict_to_user, snippet_size, annotation_type, restrict_to_book_ids, restrict_to_user,
@ -3231,10 +3255,16 @@ class Cache:
@write_api @write_api
def delete_annotations(self, annot_ids): def delete_annotations(self, annot_ids):
'''
Delete annotations with the specified ids.
'''
self.backend.delete_annotations(annot_ids) self.backend.delete_annotations(annot_ids)
@write_api @write_api
def update_annotations(self, annot_id_map): def update_annotations(self, annot_id_map):
'''
Update annotations.
'''
self.backend.update_annotations(annot_id_map) self.backend.update_annotations(annot_id_map)
@write_api @write_api
@ -3252,10 +3282,16 @@ class Cache:
@write_api @write_api
def set_annotations_for_book(self, book_id, fmt, annots_list, user_type='local', user='viewer'): def set_annotations_for_book(self, book_id, fmt, annots_list, user_type='local', user='viewer'):
'''
Set all annotations for the specified book_id, fmt, user_type and user.
'''
self.backend.set_annotations_for_book(book_id, fmt, annots_list, user_type, user) self.backend.set_annotations_for_book(book_id, fmt, annots_list, user_type, user)
@write_api @write_api
def merge_annotations_for_book(self, book_id, fmt, annots_list, user_type='local', user='viewer'): def merge_annotations_for_book(self, book_id, fmt, annots_list, user_type='local', user='viewer'):
'''
Merge the specified annotations into the existing annotations for book_id, fm, user_type, and user.
'''
from calibre.utils.date import EPOCH from calibre.utils.date import EPOCH
from calibre.utils.iso8601 import parse_iso8601 from calibre.utils.iso8601 import parse_iso8601
amap = self._annotations_map_for_book(book_id, fmt, user_type=user_type, user=user) amap = self._annotations_map_for_book(book_id, fmt, user_type=user_type, user=user)