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

Start work on an example plugin demonstrating the new plugin loader

Browse Source
This commit is contained in:
Kovid Goyal 2011-03-27 07:53:17 -06:00
parent a18b3ad33d
commit ae1c331d3c
11 changed files with 265 additions and 149 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
setup/upload.py
View File

@ -1,14 +1,14 @@
#!/usr/bin/env python
# vim:fileencoding=UTF-8:ts=4:sw=4:sta:et:sts=4:ai
from __future__ import with_statement
__license__ = 'GPL v3'
__copyright__ = '2009, Kovid Goyal <kovid@kovidgoyal.net>'
__docformat__ = 'restructuredtext en'
import os, re, cStringIO, base64, httplib, subprocess, hashlib, shutil, time
import os, re, cStringIO, base64, httplib, subprocess, hashlib, shutil, time, glob
from subprocess import check_call
from tempfile import NamedTemporaryFile, mkdtemp
from zipfile import ZipFile
from setup import Command, __version__, installer_name, __appname__
@ -341,7 +341,22 @@ class UploadUserManual(Command): # {{{
description = 'Build and upload the User Manual'
sub_commands = ['manual']
def build_plugin_example(self, path):
from calibre import CurrentDir
with NamedTemporaryFile(suffix='.zip') as f:
with CurrentDir(self.d(path)):
with ZipFile(f, 'w') as zf:
for x in os.listdir('.'):
zf.write(x)
bname = self.b(path) + '_plugin.zip'
subprocess.check_call(['scp', f.name, 'divok:%s/%s'%(DOWNLOADS,
bname)])
def run(self, opts):
path = self.j(self.SRC, 'calibre', 'manual', 'plugin_examples')
for x in glob.glob(self.j(path, '*')):
self.build_plugin_example(x)
check_call(' '.join(['scp', '-r', 'src/calibre/manual/.build/html/*',
'divok:%s'%USER_MANUAL]), shell=True)
# }}}

84
src/calibre/customize/zipplugin.py
View File

@ -10,6 +10,7 @@ __docformat__ = 'restructuredtext en'
import os, zipfile, posixpath, importlib, threading, re, imp, sys
from collections import OrderedDict
from functools import partial
from calibre.customize import (Plugin, numeric_version, platform,
InvalidPlugin, PluginNotFound)
@ -18,6 +19,65 @@ from calibre.customize import (Plugin, numeric_version, platform,
# python 2.x that prevents importing from zip files in locations whose paths
# have non ASCII characters
def get_resources(zfp, name_or_list_of_names):
'''
Load resources from the plugin zip file
:param name_or_list_of_names: List of paths to resources in the zip file using / as
separator, or a single path
:return: A dictionary of the form ``{name : file_contents}``. Any names
that were not found in the zip file will not be present in the
dictionary. If a single path is passed in the return value will
be just the bytes of the resource or None if it wasn't found.
'''
names = name_or_list_of_names
if isinstance(names, basestring):
names = [names]
ans = {}
with zipfile.ZipFile(zfp) as zf:
for name in names:
try:
ans[name] = zf.read(name)
except:
pass
if len(names) == 1:
ans = ans.pop(names[0], None)
return ans
def get_icons(zfp, name_or_list_of_names):
'''
Load icons from the plugin zip file
:param name_or_list_of_names: List of paths to resources in the zip file using / as
separator, or a single path
:return: A dictionary of the form ``{name : QIcon}``. Any names
that were not found in the zip file will be null QIcons.
If a single path is passed in the return value will
be A QIcon.
'''
from PyQt4.Qt import QIcon, QPixmap
names = name_or_list_of_names
ans = get_resources(zfp, names)
if isinstance(names, basestring):
names = [names]
if ans is None:
ans = {}
if isinstance(ans, basestring):
ans = dict([(names[0], ans)])
ians = {}
for name in names:
p = QPixmap()
raw = ans.get('name', None)
if raw:
p.loadFromData(raw)
ians[name] = QIcon(p)
if len(names) == 1:
ians = ians.pop(names[0])
return ians
class PluginLoader(object):
@ -33,9 +93,10 @@ class PluginLoader(object):
return parts[0], None
plugin_name = parts[1]
with self._lock:
names = self.loaded_plugins.get(plugin_name, None)[1]
names = self.loaded_plugins.get(plugin_name, None)
if names is None:
raise ImportError('No plugin named %r loaded'%plugin_name)
names = names[1]
fullname = '.'.join(parts[2:])
if not fullname:
fullname = '__init__'
@ -77,6 +138,8 @@ class PluginLoader(object):
with zipfile.ZipFile(zfp) as zf:
code = zf.read(zinfo)
compiled = compile(code, 'import_name', 'exec', dont_inherit=True)
mod.__dict__['get_resources'] = partial(get_resources, zfp)
mod.__dict__['get_icons'] = partial(get_icons, zfp)
exec compiled in mod.__dict__
return mod
@ -139,10 +202,6 @@ class PluginLoader(object):
if plugin_name not in self.loaded_plugins:
break
else:
if plugin_name in self.loaded_plugins:
raise InvalidPlugin((
'The plugin in %r uses an import name %r that is already'
' used by another plugin') % (path_to_zip_file, plugin_name))
if self._identifier_pat.match(plugin_name) is None:
raise InvalidPlugin((
'The plugin at %r uses an invalid import name: %r' %
@ -194,3 +253,18 @@ loader = PluginLoader()
sys.meta_path.insert(0, loader)
if __name__ == '__main__':
from tempfile import NamedTemporaryFile
from calibre.customize.ui import add_plugin
from calibre import CurrentDir
path = sys.argv[-1]
with NamedTemporaryFile(suffix='.zip') as f:
with zipfile.ZipFile(f, 'w') as zf:
with CurrentDir(path):
for x in os.listdir('.'):
if x[0] != '.':
print ('Adding', x)
zf.write(x)
add_plugin(f.name)
print ('Added plugin from', sys.argv[-1])

3
src/calibre/gui2/ui.py
View File

@ -382,6 +382,9 @@ class Main(MainWindow, MainWindowMixin, DeviceMixin, EmailMixin, # {{{
error_dialog(self, _('Failed to start content server'),
unicode(self.content_server.exception)).exec_()
@property
def current_db(self):
return self.library_view.model().db
def another_instance_wants_to_talk(self):
try:

60
src/calibre/manual/creating_plugins.rst Normal file
View File

@ -0,0 +1,60 @@
.. include:: global.rst
.. _pluginstutorial:
Writing your own plugins to extend |app|'s functionality
====================================================================
|app| has a very modular design. Almost all functionality in |app| comes in the form of plugins. Plugins are used for conversion, for downloading news (though these are called recipes), for various components of the user interface, to connect to different devices, to process files when adding them to |app| and so on. You can get a complete list of all the builtin plugins in |app| by going to :guilabel:`Preferences->Plugins`.
Here, we will teach you how to create your own plugins to add new features to |app|.
.. contents:: Contents
:depth: 2
:local:
.. note:: This only applies to calibre releases >= 0.7.52
Anatomy of a |app| plugin
---------------------------
A |app| plugin is very simple, it's just a zip file that contains some python code
and any other resources like image files needed by the plugin. Without further ado,
let's see a basic example.
Suppose you have an installation of |app| that you are using to self publish various e-documents in EPUB and MOBI
formats. You would like all files generated by |app| to have their publisher set as "Hello world", here's how to do it.
Create a file named :file:`__init__.py` (this is a special name and must always be used for the main file of your plugin)
and enter the following Python code into it:
.. literalinclude:: plugin_examples/helloworld/__init__.py
:lines: 10-
That's all. To add this code to |app| as a plugin, simply create a zip file with::
zip plugin.zip __init__.py
Add this plugin to |app| via :guilabel:`Preferences->Plugins`.
You can download the Hello World plugin from
`helloworld_plugin.zip <http://calibre-ebook.com/downloads/helloworld_plugin.zip>`_.
Every time you use calibre to convert a book, the plugin's :meth:`run` method will be called and the
converted book will have its publisher set to "Hello World". This is a trivial plugin, lets move on to
a more complex example that actually adds a component to the user interface.
A User Interface plugin
-------------------------
This plugin will be spread over a couple of files (to keep the code clean). It will show you how to get resources
(images or data files) from the plugin zip file, how to create elements in the |app| user interface and how to access
and query the books database in |app|.
The different types of plugins
--------------------------------
As you may have noticed above, a plugin in |app| is a class. There are different classes for the different types of plugins in |app|.
Details on each class, including the base class of all plugins can be found in :ref:`plugins`.

151
src/calibre/manual/customize.rst
View File

@ -17,6 +17,11 @@ use *plugins* to add functionality to |app|.
:depth: 2
:local:
.. toctree::
:hidden:
plugins
Environment variables
-----------------------
@ -53,148 +58,10 @@ You should not change the files in this resources folder, as your changes will g
For example, if you wanted to change the icon for the :guilabel:`Remove books` action, you would first look in the builtin resources folder and see that the relevant file is
:file:`resources/images/trash.svg`. Assuming you have an alternate icon in svg format called :file:`mytrash.svg` you would save it in the configuration directory as :file:`resources/images/trash.svg`. All the icons used by the calibre user interface are in :file:`resources/images` and its sub-folders.
A Hello World plugin
------------------------
Customizing |app| with plugins
--------------------------------
Suppose you have an installation of |app| that you are using to self publish various e-documents in EPUB and LRF
format. You would like all file generated by |app| to have their publisher set as "Hello world", here's how to do it.
Create a file name :file:`my_plugin.py` (the file name must end with plugin.py) and enter the following Python code into it:
|app| has a very modular design. Almost all functionality in |app| comes in the form of plugins. Plugins are used for conversion, for downloading news (though these are called recipes), for various components of the user interface, to connect to different devices, to process files when adding them to |app| and so on. You can get a complete list of all the builtin plugins in |app| by going to :guilabel:`Preferences->Plugins`.
.. code-block:: python
You can write your own plugins to customize and extend the behavior of |app|. The plugin architecture in |app| is very simple, see the tutorial :ref:`pluginstutorial`.
import os
from calibre.customize import FileTypePlugin
class HelloWorld(FileTypePlugin):
name = 'Hello World Plugin' # Name of the plugin
description = 'Set the publisher to Hello World for all new conversions'
supported_platforms = ['windows', 'osx', 'linux'] # Platforms this plugin will run on
author = 'Acme Inc.' # The author of this plugin
version = (1, 0, 0) # The version number of this plugin
file_types = set(['epub', 'lrf']) # The file types that this plugin will be applied to
on_postprocess = True # Run this plugin after conversion is complete
def run(self, path_to_ebook):
from calibre.ebooks.metadata.meta import get_metadata, set_metadata
file = open(path_to_ebook, 'r+b')
ext = os.path.splitext(path_to_ebook)[-1][1:].lower()
mi = get_metadata(file, ext)
mi.publisher = 'Hello World'
set_metadata(file, mi, ext)
return path_to_ebook
That's all. To add this code to |app| as a plugin, simply create a zip file with::
zip plugin.zip my_plugin.py
You can download the Hello World plugin from
`helloworld_plugin.zip <http://calibre-ebook.com/downloads/helloworld_plugin.zip>`_.
Now either use the configuration dialog in |app| GUI to add this zip file as a plugin, or
use the command::
calibre-customize -a plugin.zip
Every time you use calibre to convert a book, the plugin's :meth:`run` method will be called and the
converted book will have its publisher set to "Hello World". For more information about
|app|'s plugin system, read on...
A Hello World GUI plugin
---------------------------
Here's a simple Hello World plugin for the |app| GUI. It will cause a box to popup with the message "Hellooo World!" when you press Ctrl+Shift+H
.. note:: Only available in calibre versions ``>= 0.7.32``.
.. code-block:: python
from calibre.customize import InterfaceActionBase
class HelloWorldBase(InterfaceActionBase):
name = 'Hello World GUI'
author = 'The little green man'
def load_actual_plugin(self, gui):
from calibre.gui2.actions import InterfaceAction
class HelloWorld(InterfaceAction):
name = 'Hello World GUI'
action_spec = ('Hello World!', 'add_book.png', None,
_('Ctrl+Shift+H'))
def genesis(self):
self.qaction.triggered.connect(self.hello_world)
def hello_world(self, *args):
from calibre.gui2 import info_dialog
info_dialog(self.gui, 'Hello World!', 'Hellooo World!',
show=True)
return HelloWorld(gui, self.site_customization)
You can also have it show up in the toolbars/context menu by going to Preferences->Toolbars and adding this plugin to the locations you want it to be in.
While this plugin is utterly useless, note that all calibre GUI actions like adding/saving/removing/viewing/etc. are implemented as plugins, so there is no limit to what you can achieve. The key thing to remember is that the plugin has access to the full |app| GUI via ``self.gui``.
The Plugin base class
------------------------
As you may have noticed above, all |app| plugins are classes. The Plugin classes are organized in a hierarchy at the top of which
is :class:`calibre.customize.Plugin`. The has excellent in source documentation for its various features, here I will discuss a
few of the important ones.
First, all plugins must supply a list of platforms they have been tested on by setting the ``supported_platforms`` member as in the
example above.
If the plugin needs to do any initialization, it should implement the :meth:`initialize` method. The path to the plugin zip file
is available as ``self.plugin_path``. The initialization method could be used to load any needed resources from the zip file.
If the plugin needs to be customized (i.e. it needs some information from the user), it should implement the :meth:`customization_help`
method, to indicate to |app| that it needs user input. This can be useful, for example, to ask the user to input the path to a needed system
binary or the URL of a website, etc. When |app| asks the user for the customization information, the string retuned by the :meth:`customization_help`
method is used as help text to le thte user know what information is needed.
Another useful method is :meth:`temporary_file`, which returns a file handle to an opened temporary file. If your plugin needs to make use
of temporary files, it should use this method. Temporary file cleanup is then taken care of automatically.
In addition, whenever plugins are run, their zip files are automatically added to the start of ``sys.path``, so you can directly import
any python files you bundle in the zip files. Note that this is not available when the plugin is being initialized, only when it is being run.
Finally, plugins can have a priority (a positive integer). Higher priority plugins are run in preference tolower priority ones in a given context.
By default all plugins have priority 1. You can change that by setting the member :attr:'priority` in your subclass.
See :ref:`pluginsPlugin` for details.
File type plugins
-------------------
File type plugins are intended to be associated with specific file types (as identified by extension). They can be run on several different occassions.
* When books/formats are added ot the |app| database (if :attr:`on_import` is set to True).
* Just before an any2whatever converter is run on an input file (if :attr:`on_preprocess` is set to True).
* After an any2whatever converter has run, on the output file (if :attr:`on_postprocess` is set to True).
File type plugins specify which file types they are associated with by specifying the :attr:`file_types` member as in the above example.
the actual work should be done in the :meth:`run` method, which must return the path to the modified ebook (it can be the same as the original
if the modifcations are done in place).
See :ref:`pluginsFTPlugin` for details.
Metadata plugins
-------------------
Metadata plugins add the ability to read/write metadata from ebook files to |app|. See :ref:`pluginsMetadataPlugin` for details.
.. toctree::
:hidden:
plugins
Metadata download plugins
----------------------------
Metadata download plugins add various sources that |app| uses to download metadata based on title/author/isbn etc. See :ref:`pluginsMetadataSource`
for details.

33
src/calibre/manual/plugin_examples/helloworld/__init__.py Normal file
View File

@ -0,0 +1,33 @@
#!/usr/bin/env python
# vim:fileencoding=UTF-8:ts=4:sw=4:sta:et:sts=4:ai
from __future__ import (unicode_literals, division, absolute_import,
print_function)
__license__ = 'GPL v3'
__copyright__ = '2011, Kovid Goyal <kovid@kovidgoyal.net>'
__docformat__ = 'restructuredtext en'
import os
from calibre.customize import FileTypePlugin
class HelloWorld(FileTypePlugin):
name = 'Hello World Plugin' # Name of the plugin
description = 'Set the publisher to Hello World for all new conversions'
supported_platforms = ['windows', 'osx', 'linux'] # Platforms this plugin will run on
author = 'Acme Inc.' # The author of this plugin
version = (1, 0, 0) # The version number of this plugin
file_types = set(['epub', 'mobi']) # The file types that this plugin will be applied to
on_postprocess = True # Run this plugin after conversion is complete
minimum_calibre_version = (0, 7, 51)
def run(self, path_to_ebook):
from calibre.ebooks.metadata.meta import get_metadata, set_metadata
file = open(path_to_ebook, 'r+b')
ext = os.path.splitext(path_to_ebook)[-1][1:].lower()
mi = get_metadata(file, ext)
mi.publisher = 'Hello World'
set_metadata(file, mi, ext)
return path_to_ebook

33
src/calibre/manual/plugin_examples/interface/__init__.py Normal file
View File

@ -0,0 +1,33 @@
#!/usr/bin/env python
# vim:fileencoding=UTF-8:ts=4:sw=4:sta:et:sts=4:ai
from __future__ import (unicode_literals, division, absolute_import,
print_function)
__license__ = 'GPL v3'
__copyright__ = '2011, Kovid Goyal <kovid@kovidgoyal.net>'
__docformat__ = 'restructuredtext en'
# The class that all Interface Action plugin wrappers must inherit from
from calibre.customize import InterfaceActionBase
class InterfacePluginDemo(InterfaceActionBase):
'''
This class is a simple wrapper that provides information about the actual
plugin class. The actual interface plugin class is called InterfacePlugin
and is defined in the ui.py file, as specified in the actual_plugin field
below.
The reason for having two classes is that it allows the command line
calibre utilities to run without needing to load the GUI libraries.
'''
name = 'Interface Plugin Demo'
description = 'An advanced plugin demo'
supported_platforms = ['windows', 'osx', 'linux']
author = 'Kovid Goyal'
version = (1, 0, 0)
minimum_calibre_version = (0, 7, 51)
#: This field defines the plugin class that contains all the code
#: that actually does something.
actual_plugin = 'calibre_plugins.interface.ui:InterfacePlugin'

BIN
src/calibre/manual/plugin_examples/interface/images/icon.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.6 KiB

0
src/calibre/manual/plugin_examples/interface/plugin-import-name-interface.txt Normal file
View File

30
src/calibre/manual/plugin_examples/interface/ui.py Normal file
View File

@ -0,0 +1,30 @@
#!/usr/bin/env python
# vim:fileencoding=UTF-8:ts=4:sw=4:sta:et:sts=4:ai
from __future__ import (unicode_literals, division, absolute_import,
print_function)
__license__ = 'GPL v3'
__copyright__ = '2011, Kovid Goyal <kovid@kovidgoyal.net>'
__docformat__ = 'restructuredtext en'
# The class that all interface action plugins must inherit from
from calibre.gui2.actions import InterfaceAction
if False:
# This is here to keep my python error checker from complaining about
# the builtins that will be defined by the plugin loading system
get_icons = None
class InterfacePlugin(InterfaceAction):
name = 'Interface Plugin Demo'
action_spec = ('Interface Plugin Demo', None,
'Run the Interface Plugin Demo', 'Ctrl+Shift+F1')
def genesis(self):
# This method is called once per plugin, do initial setup here
print (1111, get_icons('icon.png'))
self.qaction.setIcon(get_icons('icon.png'))

1
src/calibre/manual/tutorials.rst
View File

@ -18,4 +18,5 @@ Here you will find tutorials to get you started using |app|'s more advanced feat
regexp
portable
server
creating_plugins