Debian Codegraph @

src/calibre/devices/interface.py

raw
1 # License: GPLv3 Copyright: 2008, Kovid Goyal <kovid at kovidgoyal.net>
2
3 import os
4 from collections import namedtuple
5 from typing import ClassVar, NamedTuple
6
7 from calibre import prints
8 from calibre.constants import iswindows
9 from calibre.customize import Plugin
10 from calibre.utils.localization import _
11
12 FAKE_DEVICE_SERIAL = '__fake_device_for_use_with_connect_to_folder__:'
13
14
15 class ModelMetadata(NamedTuple):
16 manufacturer_name: str
17 model_name: str
18 vendor_id: int
19 product_id: int
20 bcd: int
21 driver_class: type
22
23 @property
24 def settings_key(self) -> str:
25 return f'{self.manufacturer_name} - {self.model_name}'
26
27 def detected_device(self, folder_path):
28 from calibre.devices.scanner import USBDevice
29
30 return USBDevice(
31 self.vendor_id,
32 self.product_id,
33 self.bcd,
34 self.manufacturer_name,
35 self.model_name,
36 FAKE_DEVICE_SERIAL + folder_path,
37 )
38
39
40 class OpenPopupMessage:
41 def __init__(self, title='', message='', level='info', skip_dialog_skip_precheck=True):
42 self.title = title
43 self.message = message
44 self.level = level
45 self.skip_dialog_skip_precheck = skip_dialog_skip_precheck
46
47
48 class DevicePlugin(Plugin):
49 """
50 Defines the interface that should be implemented by backends that
51 communicate with an e-book reader.
52 """
53
54 type = _('Device interface')
55
56 #: Ordered list of supported formats
57 FORMATS = ['lrf', 'rtf', 'pdf', 'txt']
58 # If True, the config dialog will not show the formats box
59 HIDE_FORMATS_CONFIG_BOX = False
60
61 #: VENDOR_ID can be either an integer, a list of integers or a dictionary
62 #: If it is a dictionary, it must be a dictionary of dictionaries,
63 #: of the form::
64 #:
65 #: {
66 #: integer_vendor_id : { product_id : [list of BCDs], ... },
67 #: ...
68 #: }
69 #:
70 VENDOR_ID: ClassVar[int | list[int] | dict[int, dict[int, list[int] | None]]] = 0x0000
71
72 #: An integer or a list of integers
73 PRODUCT_ID: ClassVar[int | list[int]] = 0x0000
74 #: BCD can be either None to not distinguish between devices based on BCD, or
75 #: it can be a list of the BCD numbers of all devices supported by this driver.
76 BCD = None
77
78 #: Height for thumbnails on the device
79 THUMBNAIL_HEIGHT = 68
80
81 #: Compression quality for thumbnails. Set this closer to 100 to have better
82 #: quality thumbnails with fewer compression artifacts. Of course, the
83 #: thumbnails get larger as well.
84 THUMBNAIL_COMPRESSION_QUALITY = 75
85
86 #: Set this to True if the device supports updating cover thumbnails during
87 #: sync_booklists. Setting it to true will ask device.py to refresh the
88 #: cover thumbnails during book matching
89 WANTS_UPDATED_THUMBNAILS = False
90
91 #: Whether the metadata on books can be set via the GUI.
92 CAN_SET_METADATA = ['title', 'authors', 'collections']
93
94 #: Whether the device can handle device_db metadata plugboards
95 CAN_DO_DEVICE_DB_PLUGBOARD = False
96
97 # Set this to None if the books on the device are files that the GUI can
98 # access in order to add the books from the device to the library
99 BACKLOADING_ERROR_MESSAGE = _('Cannot get files from this device')
100
101 #: Path separator for paths to books on device
102 path_sep = os.sep
103
104 #: Icon for this device
105 icon = 'reader.png'
106
107 # Encapsulates an annotation fetched from the device
108 UserAnnotation = namedtuple('UserAnnotation', 'type, value')
109
110 #: GUI displays this as a message if not None in the status bar. Useful if opening can take a
111 #: long time
112 OPEN_FEEDBACK_MESSAGE = None
113
114 #: Set of extensions that are "virtual books" on the device
115 #: and therefore cannot be viewed/saved/added to library.
116 #: For example: ``frozenset(['kobo'])``
117 VIRTUAL_BOOK_EXTENSIONS = frozenset()
118
119 #: Message to display to user for virtual book extensions.
120 VIRTUAL_BOOK_EXTENSION_MESSAGE = None
121
122 #: Whether to nuke comments in the copy of the book sent to the device. If
123 #: not None this should be short string that the comments will be replaced
124 #: by.
125 NUKE_COMMENTS = None
126
127 #: If True indicates that this driver completely manages device detection,
128 #: ejecting and so forth. If you set this to True, you *must* implement the
129 #: detect_managed_devices and debug_managed_device_detection methods.
130 #: A driver with this set to true is responsible for detection of devices,
131 #: managing a blacklist of devices, a list of ejected devices and so forth.
132 #: calibre will periodically call the detect_managed_devices() method and
133 #: if it returns a detected device, calibre will call open(). open() will
134 #: be called every time a device is returned even if previous calls to open()
135 #: failed, therefore the driver must maintain its own blacklist of failed
136 #: devices. Similarly, when ejecting, calibre will call eject() and then
137 #: assuming the next call to detect_managed_devices() returns None, it will
138 #: call post_yank_cleanup().
139 MANAGES_DEVICE_PRESENCE = False
140
141 #: If set the True, calibre will call the :meth:`get_driveinfo()` method
142 #: after the books lists have been loaded to get the driveinfo.
143 SLOW_DRIVEINFO = False
144
145 #: If set to True, calibre will ask the user if they want to manage the
146 #: device with calibre, the first time it is detected. If you set this to
147 #: True you must implement :meth:`get_device_uid()` and
148 #: :meth:`ignore_connected_device()` and
149 #: :meth:`get_user_blacklisted_devices` and
150 #: :meth:`set_user_blacklisted_devices`
151 ASK_TO_ALLOW_CONNECT = False
152
153 #: Set this to a dictionary of the form {'title':title, 'msg':msg, 'det_msg':detailed_msg} to have calibre popup
154 #: a message to the user after some callbacks are run (currently only upload_books).
155 #: Be careful to not spam the user with too many messages. This variable is checked after *every* callback,
156 #: so only set it when you really need to.
157 user_feedback_after_callback = None
158
159 @classmethod
160 def get_gui_name(cls):
161 if hasattr(cls, 'gui_name'):
162 return cls.gui_name
163 if hasattr(cls, '__name__'):
164 return cls.__name__
165 return cls.name
166
167 @classmethod
168 def get_open_popup_message(self):
169 "GUI displays this as a non-modal popup. Should be an instance of OpenPopupMessage"
170 return
171
172 @classmethod
173 def model_metadata(self) -> tuple[ModelMetadata, ...]:
174 "Metadata about all the actual device models this driver supports"
175 return ()
176
177 # Device detection {{{
178 def test_bcd(self, bcdDevice, bcd):
179 if bcd is None or len(bcd) == 0:
180 return True
181 for c in bcd:
182 if c == bcdDevice:
183 return True
184 return False
185
186 def is_usb_connected(self, devices_on_system, debug=False, only_presence=False):
187 """
188 Return True, device_info if a device handled by this plugin is currently connected.
189
190 :param devices_on_system: List of devices currently connected
191
192 """
193 vendors_on_system = {x[0] for x in devices_on_system}
194 vendor_id = self.VENDOR_ID
195 if isinstance(vendor_id, dict):
196 vendors = set(vendor_id)
197 products: list[int] = []
198 for ven in vendor_id:
199 products.extend(vendor_id[ven].keys())
200 elif isinstance(vendor_id, list):
201 vendors = set(vendor_id)
202 products = self.PRODUCT_ID if isinstance(self.PRODUCT_ID, list) else [self.PRODUCT_ID]
203 else:
204 vendors = {vendor_id}
205 products = self.PRODUCT_ID if isinstance(self.PRODUCT_ID, list) else [self.PRODUCT_ID]
206
207 ch = self.can_handle_windows if iswindows else self.can_handle
208 for vid in vendors_on_system.intersection(vendors):
209 for dev in devices_on_system:
210 cvid, pid, bcd = dev[:3]
211 if cvid == vid:
212 if pid in products:
213 if isinstance(vendor_id, dict):
214 try:
215 cbcd = vendor_id[vid][pid]
216 except KeyError:
217 # Vendor vid does not have product pid, pid
218 # exists for some other vendor in this
219 # device
220 continue
221 else:
222 cbcd = self.BCD
223 if self.test_bcd(bcd, cbcd):
224 if debug:
225 prints(dev)
226 if ch(dev, debug=debug):
227 return True, dev
228 return False, None
229
230 def detect_managed_devices(self, devices_on_system, force_refresh=False):
231 """
232 Called only if MANAGES_DEVICE_PRESENCE is True.
233
234 Scan for devices that this driver can handle. Should return a device
235 object if a device is found. This object will be passed to the open()
236 method as the connected_device. If no device is found, return None. The
237 returned object can be anything, calibre does not use it, it is only
238 passed to open().
239
240 This method is called periodically by the GUI, so make sure it is not
241 too resource intensive. Use a cache to avoid repeatedly scanning the
242 system.
243
244 :param devices_on_system: Set of USB devices found on the system.
245
246 :param force_refresh: If True and the driver uses a cache to prevent
247 repeated scanning, the cache must be flushed.
248
249 """
250 raise NotImplementedError()
251
252 def debug_managed_device_detection(self, devices_on_system, output):
253 """
254 Called only if MANAGES_DEVICE_PRESENCE is True.
255
256 Should write information about the devices detected on the system to
257 output, which is a file like object.
258
259 Should return True if a device was detected and successfully opened,
260 otherwise False.
261 """
262 raise NotImplementedError()
263
264 # }}}
265
266 def reset(self, key='-1', log_packets=False, report_progress=None, detected_device=None):
267 """
268 :param key: The key to unlock the device
269 :param log_packets: If true the packet stream to/from the device is logged
270 :param report_progress: Function that is called with a % progress
271 (number between 0 and 100) for various tasks.
272 If it is called with -1 that means that the
273 task does not have any progress information
274 :param detected_device: Device information from the device scanner
275
276 """
277 raise NotImplementedError()
278
279 def can_handle_windows(self, usbdevice, debug=False):
280 """
281 Optional method to perform further checks on a device to see if this driver
282 is capable of handling it. If it is not it should return False. This method
283 is only called after the vendor, product ids and the bcd have matched, so
284 it can do some relatively time intensive checks. The default implementation
285 returns True. This method is called only on Windows. See also
286 :meth:`can_handle`.
287
288 Note that for devices based on USBMS this method by default delegates
289 to :meth:`can_handle`. So you only need to override :meth:`can_handle`
290 in your subclass of USBMS.
291
292 :param usbdevice: A usbdevice as returned by :func:`calibre.devices.winusb.scan_usb_devices`
293 """
294 return True
295
296 def can_handle(self, device_info, debug=False):
297 """
298 Unix version of :meth:`can_handle_windows`.
299
300 :param device_info: Is a tuple of (vid, pid, bcd, manufacturer, product,
301 serial number)
302
303 """
304
305 return True
306
307 def open(self, connected_device, library_uuid):
308 """
309 Perform any device specific initialization. Called after the device is
310 detected but before any other functions that communicate with the device.
311 For example: For devices that present themselves as USB Mass storage
312 devices, this method would be responsible for mounting the device or
313 if the device has been automounted, for finding out where it has been
314 mounted. The method :meth:`calibre.devices.usbms.device.Device.open` has
315 an implementation of
316 this function that should serve as a good example for USB Mass storage
317 devices.
318
319 This method can raise an OpenFeedback exception to display a message to
320 the user.
321
322 :param connected_device: The device that we are trying to open. It is
323 a tuple of (vendor id, product id, bcd, manufacturer name, product
324 name, device serial number). However, some devices have no serial
325 number and on Windows only the first three fields are present, the
326 rest are None.
327
328 :param library_uuid: The UUID of the current calibre library. Can be
329 None if there is no library (for example when used from the command
330 line).
331
332 """
333 raise NotImplementedError()
334
335 def eject(self):
336 """
337 Un-mount / eject the device from the OS. This does not check if there
338 are pending GUI jobs that need to communicate with the device.
339
340 NOTE: That this method may not be called on the same thread as the rest
341 of the device methods.
342 """
343 raise NotImplementedError()
344
345 def post_yank_cleanup(self):
346 """
347 Called if the user yanks the device without ejecting it first.
348 """
349 raise NotImplementedError()
350
351 def set_progress_reporter(self, report_progress):
352 """
353 Set a function to report progress information.
354
355 :param report_progress: Function that is called with a % progress
356 (number between 0 and 100) for various tasks.
357 If it is called with -1 that means that the
358 task does not have any progress information
359
360 """
361 raise NotImplementedError()
362
363 def get_device_information(self, end_session=True):
364 """
365 Ask device for device information. See L{DeviceInfoQuery}.
366
367 :return: (device name, device version, software version on device, MIME type)
368 The tuple can optionally have a fifth element, which is a
369 drive information dictionary. See usbms.driver for an example.
370
371 """
372 raise NotImplementedError()
373
374 def get_driveinfo(self):
375 """
376 Return the driveinfo dictionary. Usually called from
377 get_device_information(), but if loading the driveinfo is slow for this
378 driver, then it should set SLOW_DRIVEINFO. In this case, this method
379 will be called by calibre after the book lists have been loaded. Note
380 that it is not called on the device thread, so the driver should cache
381 the drive info in the books() method and this function should return
382 the cached data.
383 """
384 return {}
385
386 def card_prefix(self, end_session=True):
387 """
388 Return a 2 element list of the prefix to paths on the cards.
389 If no card is present None is set for the card's prefix.
390 E.G.
391 ('/place', '/place2')
392 (None, 'place2')
393 ('place', None)
394 (None, None)
395 """
396 raise NotImplementedError()
397
398 def total_space(self, end_session=True):
399 """
400 Get total space available on the mountpoints:
401 1. Main memory
402 2. Memory Card A
403 3. Memory Card B
404
405 :return: A 3 element list with total space in bytes of (1, 2, 3). If a
406 particular device doesn't have any of these locations it should return 0.
407
408 """
409 raise NotImplementedError()
410
411 def free_space(self, end_session=True):
412 """
413 Get free space available on the mountpoints:
414 1. Main memory
415 2. Card A
416 3. Card B
417
418 :return: A 3 element list with free space in bytes of (1, 2, 3). If a
419 particular device doesn't have any of these locations it should return -1.
420
421 """
422 raise NotImplementedError()
423
424 def books(self, oncard=None, end_session=True):
425 """
426 Return a list of e-books on the device.
427
428 :param oncard: If 'carda' or 'cardb' return a list of e-books on the
429 specific storage card, otherwise return list of e-books
430 in main memory of device. If a card is specified and no
431 books are on the card return empty list.
432
433 :return: A BookList.
434
435 """
436 raise NotImplementedError()
437
438 def upload_books(self, files, names, on_card=None, end_session=True, metadata=None):
439 '''
440 Upload a list of books to the device. If a file already
441 exists on the device, it should be replaced.
442 This method should raise a :class:`FreeSpaceError` if there is not enough
443 free space on the device. The text of the FreeSpaceError must contain the
444 word "card" if ``on_card`` is not None otherwise it must contain the word "memory".
445
446 :param files: A list of paths
447 :param names: A list of file names that the books should have
448 once uploaded to the device. len(names) == len(files)
449 :param metadata: If not None, it is a list of :class:`Metadata` objects.
450 The idea is to use the metadata to determine where on the device to
451 put the book. len(metadata) == len(files). Apart from the regular
452 cover (path to cover), there may also be a thumbnail attribute, which should
453 be used in preference. The thumbnail attribute is of the form
454 (width, height, cover_data as jpeg).
455
456 :return: A list of 3-element tuples. The list is meant to be passed
457 to :meth:`add_books_to_metadata`.
458 '''
459 raise NotImplementedError()
460
461 @classmethod
462 def add_books_to_metadata(cls, locations, metadata, booklists):
463 """
464 Add locations to the booklists. This function must not communicate with
465 the device.
466
467 :param locations: Result of a call to L{upload_books}
468 :param metadata: List of :class:`Metadata` objects, same as for
469 :meth:`upload_books`.
470 :param booklists: A tuple containing the result of calls to
471 (:meth:`books(oncard=None)`,
472 :meth:`books(oncard='carda')`,
473 :meth`books(oncard='cardb')`).
474
475 """
476 raise NotImplementedError()
477
478 def delete_books(self, paths, end_session=True):
479 """
480 Delete books at paths on device.
481 """
482 raise NotImplementedError()
483
484 @classmethod
485 def remove_books_from_metadata(cls, paths, booklists):
486 """
487 Remove books from the metadata list. This function must not communicate
488 with the device.
489
490 :param paths: paths to books on the device.
491 :param booklists: A tuple containing the result of calls to
492 (:meth:`books(oncard=None)`,
493 :meth:`books(oncard='carda')`,
494 :meth`books(oncard='cardb')`).
495
496 """
497 raise NotImplementedError()
498
499 def sync_booklists(self, booklists, end_session=True):
500 """
501 Update metadata on device.
502
503 :param booklists: A tuple containing the result of calls to
504 (:meth:`books(oncard=None)`,
505 :meth:`books(oncard='carda')`,
506 :meth`books(oncard='cardb')`).
507
508 """
509 raise NotImplementedError()
510
511 def get_file(self, path, outfile, end_session=True):
512 """
513 Read the file at ``path`` on the device and write it to outfile.
514
515 :param outfile: file object like ``sys.stdout`` or the result of an
516 :func:`open` call.
517
518 """
519 raise NotImplementedError()
520
521 def config_widget(self):
522 """
523 Should return a QWidget. The QWidget contains the settings for the
524 device interface
525 """
526 raise NotImplementedError()
527
528 def save_settings(self, config_widget):
529 """
530 Should save settings to disk. Takes the widget created in
531 :meth:`config_widget` and saves all settings to disk.
532 """
533 raise NotImplementedError()
534
535 @classmethod
536 def settings(cls):
537 """
538 Should return an opts object. The opts object should have at least one
539 attribute `format_map` which is an ordered list of formats for the
540 device.
541 """
542 raise NotImplementedError()
543
544 def set_plugboards(self, plugboards, pb_func):
545 """
546 provide the driver the current set of plugboards and a function to
547 select a specific plugboard. This method is called immediately before
548 add_books and sync_booklists.
549
550 pb_func is a callable with the following signature::
551 def pb_func(device_name, format, plugboards)
552
553 You give it the current device name (either the class name or
554 DEVICE_PLUGBOARD_NAME), the format you are interested in (a 'real'
555 format or 'device_db'), and the plugboards (you were given those by
556 set_plugboards, the same place you got this method).
557
558 :return: None or a single plugboard instance.
559
560 """
561 pass
562
563 def set_driveinfo_name(self, location_code, name):
564 """
565 Set the device name in the driveinfo file to 'name'. This setting will
566 persist until the file is re-created or the name is changed again.
567
568 Non-disk devices should implement this method based on the location
569 codes returned by the get_device_information() method.
570 """
571 pass
572
573 def prepare_addable_books(self, paths):
574 """
575 Given a list of paths, returns another list of paths. These paths
576 point to addable versions of the books.
577
578 If there is an error preparing a book, then instead of a path, the
579 position in the returned list for that book should be a three tuple:
580 (original_path, the exception instance, traceback)
581 """
582 return paths
583
584 def startup(self):
585 """
586 Called when calibre is starting the device. Do any initialization
587 required. Note that multiple instances of the class can be instantiated,
588 and thus __init__ can be called multiple times, but only one instance
589 will have this method called. This method is called on the device
590 thread, not the GUI thread.
591 """
592 pass
593
594 def shutdown(self):
595 """
596 Called when calibre is shutting down, either for good or in preparation
597 to restart. Do any cleanup required. This method is called on the
598 device thread, not the GUI thread.
599 """
600 pass
601
602 def get_device_uid(self):
603 """
604 Must return a unique id for the currently connected device (this is
605 called immediately after a successful call to open()). You must
606 implement this method if you set ASK_TO_ALLOW_CONNECT = True
607 """
608 raise NotImplementedError()
609
610 def ignore_connected_device(self, uid):
611 """
612 Should ignore the device identified by uid (the result of a call to
613 get_device_uid()) in the future. You must implement this method if you
614 set ASK_TO_ALLOW_CONNECT = True. Note that this function is called
615 immediately after open(), so if open() caches some state, the driver
616 should reset that state.
617 """
618 raise NotImplementedError()
619
620 def get_user_blacklisted_devices(self):
621 """
622 Return map of device uid to friendly name for all devices that the user
623 has asked to be ignored.
624 """
625 return {}
626
627 def set_user_blacklisted_devices(self, devices):
628 """
629 Set the list of device uids that should be ignored by this driver.
630 """
631 pass
632
633 def specialize_global_preferences(self, device_prefs):
634 """
635 Implement this method if your device wants to override a particular
636 preference. You must ensure that all call sites that want a preference
637 that can be overridden use device_prefs['something'] instead
638 of prefs['something']. Your
639 method should call device_prefs.set_overrides(pref=val, pref=val, ...).
640 Currently used for:
641 metadata management (prefs['manage_device_metadata'])
642 """
643 device_prefs.set_overrides()
644
645 def set_library_info(self, library_name, library_uuid, field_metadata):
646 """
647 Implement this method if you want information about the current calibre
648 library. This method is called at startup and when the calibre library
649 changes while connected.
650 """
651 pass
652
653 # Dynamic control interface.
654 # The following methods are probably called on the GUI thread. Any driver
655 # that implements these methods must take pains to be thread safe, because
656 # the device_manager might be using the driver at the same time that one of
657 # these methods is called.
658
659 def is_dynamically_controllable(self):
660 """
661 Called by the device manager when starting plugins. If this method returns
662 a string, then a) it supports the device manager's dynamic control
663 interface, and b) that name is to be used when talking to the plugin.
664
665 This method can be called on the GUI thread. A driver that implements
666 this method must be thread safe.
667 """
668 return
669
670 def start_plugin(self):
671 """
672 This method is called to start the plugin. The plugin should begin
673 to accept device connections however it does that. If the plugin is
674 already accepting connections, then do nothing.
675
676 This method can be called on the GUI thread. A driver that implements
677 this method must be thread safe.
678 """
679 pass
680
681 def stop_plugin(self):
682 """
683 This method is called to stop the plugin. The plugin should no longer
684 accept connections, and should cleanup behind itself. It is likely that
685 this method should call shutdown. If the plugin is already not accepting
686 connections, then do nothing.
687
688 This method can be called on the GUI thread. A driver that implements
689 this method must be thread safe.
690 """
691 pass
692
693 def get_option(self, opt_string, default=None):
694 """
695 Return the value of the option indicated by opt_string. This method can
696 be called when the plugin is not started. Return None if the option does
697 not exist.
698
699 This method can be called on the GUI thread. A driver that implements
700 this method must be thread safe.
701 """
702 return default
703
704 def set_option(self, opt_string, opt_value):
705 """
706 Set the value of the option indicated by opt_string. This method can
707 be called when the plugin is not started.
708
709 This method can be called on the GUI thread. A driver that implements
710 this method must be thread safe.
711 """
712 pass
713
714 def is_running(self):
715 """
716 Return True if the plugin is started, otherwise false
717
718 This method can be called on the GUI thread. A driver that implements
719 this method must be thread safe.
720 """
721 return False
722
723 def synchronize_with_db(self, db, book_id, book_metadata, first_call):
724 """
725 Called during book matching when a book on the device is matched with
726 a book in calibre's db. The method is responsible for synchronizing
727 data from the device to calibre's db (if needed).
728
729 The method must return a two-value tuple. The first value is a set of
730 calibre book ids changed if calibre's database was changed or None if the
731 database was not changed. If the first value is an empty set then the
732 metadata for the book on the device is updated with calibre's metadata
733 and given back to the device, but no GUI refresh of that book is done.
734 This is useful when the calibre data is correct but must be sent to the
735 device.
736
737 The second value is itself a 2-value tuple. The first value in the tuple
738 specifies whether a book format should be sent to the device. The intent
739 is to permit verifying that the book on the device is the same as the
740 book in calibre. This value must be None if no book is to be sent,
741 otherwise return the base file name on the device (a string like
742 foobar.epub). Be sure to include the extension in the name. The device
743 subsystem will construct a send_books job for all books with not- None
744 returned values. Note: other than to later retrieve the extension, the
745 name is ignored in cases where the device uses a template to generate
746 the file name, which most do. The second value in the returned tuple
747 indicated whether the format is future-dated. Return True if it is,
748 otherwise return False. calibre will display a dialog to the user
749 listing all future dated books.
750
751 Extremely important: this method is called on the GUI thread. It must
752 be threadsafe with respect to the device manager's thread.
753
754 book_id: the calibre id for the book in the database.
755 book_metadata: the Metadata object for the book coming from the device.
756 first_call: True if this is the first call during a sync, False otherwise
757 """
758 return (None, (None, False))
759
760
761 class BookList(list):
762 """
763 A list of books. Each Book object must have the fields
764
765 #. title
766 #. authors
767 #. size (file size of the book)
768 #. datetime (a UTC time tuple)
769 #. path (path on the device to the book)
770 #. thumbnail (can be None) thumbnail is either a str/bytes object with the
771 image data or it should have an attribute image_path that stores an
772 absolute (platform native) path to the image
773 #. tags (a list of strings, can be empty).
774
775 """
776
777 __getslice__ = None
778 __setslice__ = None
779
780 def __init__(self, oncard=None, prefix=None, settings=None):
781 pass
782
783 def supports_collections(self):
784 """Return True if the device supports collections for this book list."""
785 raise NotImplementedError()
786
787 def add_book(self, book, replace_metadata):
788 """
789 Add the book to the booklist. Intent is to maintain any device-internal
790 metadata. Return True if booklists must be sync'ed
791 """
792 raise NotImplementedError()
793
794 def remove_book(self, book):
795 """
796 Remove a book from the booklist. Correct any device metadata at the
797 same time
798 """
799 raise NotImplementedError()
800
801 def get_collections(self, collection_attributes):
802 """
803 Return a dictionary of collections created from collection_attributes.
804 Each entry in the dictionary is of the form collection name:[list of
805 books]
806
807 The list of books is sorted by book title, except for collections
808 created from series, in which case series_index is used.
809
810 :param collection_attributes: A list of attributes of the Book object
811
812 """
813 raise NotImplementedError()
814
815
816 class CurrentlyConnectedDevice:
817 def __init__(self):
818 self._device = None
819
820 @property
821 def device(self):
822 return self._device
823
824
825 # A device driver can check if a device is currently connected to calibre using
826 # the following code::
827 # from calibre.device.interface import currently_connected_device
828 # if currently_connected_device.device is None:
829 # # no device connected
830 # The device attribute will be either None or the device driver object
831 # (DevicePlugin instance) for the currently connected device.
832 currently_connected_device = CurrentlyConnectedDevice()