Add examples showing how to access ebook files in the calibre database to the plugin tutorial

src/calibre/manual/faq.rst

@@ -650,7 +650,7 @@ I want some feature added to |app|. What can I do?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 You have two choices:
  1. Create a patch by hacking on |app| and send it to me for review and inclusion. See `Development <http://calibre-ebook.com/get-involved>`_.
- 2. `Open a bug requesting the feature <http://calibre-ebook.com/bugs>`_ . Remember that |app| development is done by volunteers, so if you get no response to your feature request, it means no one feels like implementing it.
+ 2. `Open a bug requesting the feature <http://calibre-ebook.com/bugs>`_ . Remember that while you may think your feature request is extremely important/essential, |app| developers might not agree. Fortunately, |app| is open source, which means you always have the option of implementing your feature yourself, or hiring someone to do it for you. Furthermore, |app| has a comprehensive plugin architecture, so you might be able to develop your feature as a plugin, see :ref:`pluginstutorial`.
 
 Why doesn't |app| have an automatic update?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

src/calibre/manual/plugin_examples/interface_demo/main.py

@@ -53,6 +53,11 @@ class DemoDialog(QDialog):
         self.view_button.clicked.connect(self.view)
         self.l.addWidget(self.view_button)
 
+        self.update_metadata_button = QPushButton(
+            'Update metadata in a book\'s files', self)
+        self.update_metadata_button.clicked.connect(self.update_metadata)
+        self.l.addWidget(self.update_metadata_button)
+
         self.conf_button = QPushButton(
                 'Configure this plugin', self)
         self.conf_button.clicked.connect(self.config)
@@ -75,6 +80,7 @@ class DemoDialog(QDialog):
                 text.decode('utf-8'))
 
     def marked(self):
+        ''' Show books with only one format '''
         fmt_idx = self.db.FIELD_MAP['formats']
         matched_ids = set()
         for record in self.db.data.iterall():
@@ -91,6 +97,7 @@ class DemoDialog(QDialog):
         self.gui.search.do_search()
 
     def view(self):
+        ''' View the most recently added book '''
         most_recent = most_recent_id = None
         timestamp_idx = self.db.FIELD_MAP['timestamp']
 
@@ -109,6 +116,48 @@ class DemoDialog(QDialog):
             # Ask the view plugin to launch the viewer for row_number
             view_plugin._view_books([row_number])
 
+    def update_metadata(self):
+        '''
+        Set the metadata in the files in the selected book's record to
+        match the current metadata in the database.
+        '''
+        from calibre.ebooks.metadata.meta import set_metadata
+        from calibre.gui2 import error_dialog, info_dialog
+
+        # Get currently selected books
+        rows = self.gui.library_view.selectionModel().selectedRows()
+        if not rows or len(rows) == 0:
+            return error_dialog(self.gui, 'Cannot update metadata',
+                             'No books selected', show=True)
+        # Map the rows to book ids
+        ids = list(map(self.gui.library_view.model().id, rows))
+        for book_id in ids:
+            # Get the current metadata for this book from the db
+            mi = self.db.get_metadata(book_id, index_is_id=True,
+                    get_cover=True, cover_as_data=True)
+            fmts = self.db.formats(book_id, index_is_id=True)
+            if not fmts: continue
+            for fmt in fmts.split(','):
+                fmt = fmt.lower()
+                # Get a python file object for the format. This will be either
+                # an in memory file or a temporary on disk file
+                ffile = self.db.format(book_id, fmt, index_is_id=True,
+                        as_file=True)
+                # Set metadata in the format
+                set_metadata(ffile, mi, fmt)
+                ffile.seek(0)
+                # Now replace the file in the calibre library with the updated
+                # file. We dont use add_format_with_hooks as the hooks were
+                # already run when the file was first added to calibre.
+                ffile.name = 'xxx' # add_format() will not work if the file
+                                   # path of the file being added is the same
+                                   # as the path of the file being replaced
+                self.db.add_format(book_id, fmt, ffile, index_is_id=True)
+
+        info_dialog(self, 'Updated files',
+                'Updated the metadata in the files of %d book(s)'%len(ids),
+                show=True)
+
     def config(self):
         self.do_user_config(parent=self)
         # Apply the changes