API Documentation for plugins

Defines various abstract base classes that can be subclassed to create powerful plugins. The useful classes are:

Plugin

class calibre.customize.__init__.Plugin

Abstract base class that contains a number of members and methods to create your plugin. All plugins must inherit from this class or a subclass of it.

The members and methods are:

Plugin.name

The name of this plugin. You must set it something other than Trivial Plugin for it to work.

Default: 'Trivial Plugin'

Plugin.author

The author of this plugin

Default: u'Unknown'

Plugin.description

A short string describing what this plugin does

Default: u'Does absolutely nothing'

Plugin.version

The version of this plugin as a 3-tuple (major, minor, revision)

Default: (1, 0, 0)

Plugin.supported_platforms

List of platforms this plugin works on For example: ``[‘windows’, ‘osx’, ‘linux’]

Default: []

Plugin.priority

When more than one plugin exists for a filetype, the plugins are run in order of decreasing priority i.e. plugins with higher priority will be run first. The highest possible priority is sys.maxint. Default priority is 1.

Default: 1

Plugin.minimum_calibre_version

The earliest version of calibre this plugin requires

Default: (0, 4, 118)

Plugin.can_be_disabled

If False, the user will not be able to disable this plugin. Use with care.

Default: True

Plugin.initialize()

Called once when calibre plugins are initialized. Plugins are re-initialized every time a new plugin is added.

Perform any plugin specific initialization here, such as extracting resources from the plugin zip file. The path to the zip file is available as self.plugin_path.

Note that self.site_customization is not available at this point.

Plugin.customization_help(gui=False)

Return a string giving help on how to customize this plugin. By default raise a NotImplementedError, which indicates that the plugin does not require customization.

If you re-implement this method in your subclass, the user will be asked to enter a string as customization for this plugin. The customization string will be available as self.site_customization.

Site customization could be anything, for example, the path to a needed binary on the user’s computer.

Parameter:gui – If True return HTML help, otherwise return plain text help.

Plugin.temporary_file(suffix)

Return a file-like object that is a temporary file on the file system. This file will remain available even after being closed and will only be removed on interpreter shutdown. Use the name member of the returned object to access the full path to the created temporary file.

Parameter:suffix – The suffix that the temporary file will have.

FileTypePlugin

class calibre.customize.__init__.Plugin

Abstract base class that contains a number of members and methods to create your file type plugin. All file type plugins must inherit from this class or a subclass of it.

The members and methods are:

FileTypePlugin.file_types

Set of file types for which this plugin should be run For example: set(['lit', 'mobi', 'prc'])

Default: set([])

FileTypePlugin.on_import

If True, this plugin is run when books are added to the database

Default: False

FileTypePlugin.on_preprocess

If True, this plugin is run just before a conversion

Default: False

FileTypePlugin.on_postprocess

If True, this plugin is run after conversion on the final file produced by the conversion output plugin.

Default: False

FileTypePlugin.run(path_to_ebook)

Run the plugin. Must be implemented in subclasses. It should perform whatever modifications are required on the ebook and return the absolute path to the modified ebook. If no modifications are needed, it should return the path to the original ebook. If an error is encountered it should raise an Exception. The default implementation simply return the path to the original ebook.

The modified ebook file should be created with the temporary_file() method.

Parameter:path_to_ebook – Absolute path to the ebook. Returns:Absolute path to the modified ebook.

Metadata plugins

class calibre.customize.__init__.MetadataReaderPlugin

Abstract base class that contains a number of members and methods to create your metadata reader plugin. All metadata reader plugins must inherit from this class or a subclass of it.

The members and methods are:

MetadataReaderPlugin.file_types

Set of file types for which this plugin should be run For example: set(['lit', 'mobi', 'prc'])

Default: set([])

MetadataReaderPlugin.get_metadata(stream, type)

Return metadata for the file represented by stream (a file like object that supports reading). Raise an exception when there is an error with the input data.

Parameter:type – The type of file. Guaranteed to be one of the entries

in file_types.

Returns:A calibre.ebooks.metadata.MetaInformation object

class calibre.customize.__init__.MetadataWriterPlugin

Abstract base class that contains a number of members and methods to create your metadata writer plugin. All metadata writer plugins must inherit from this class or a subclass of it.

The members and methods are:

MetadataWriterPlugin.file_types

Set of file types for which this plugin should be run For example: set(['lit', 'mobi', 'prc'])

Default: set([])

MetadataWriterPlugin.set_metadata(stream, mi, type)

Set metadata for the file represented by stream (a file like object that supports reading). Raise an exception when there is an error with the input data.

Parameter:type – The type of file. Guaranteed to be one of the entries

in file_types. :param mi: A calibre.ebooks.metadata.MetaInformation object

Metadata download plugins

class calibre.ebooks.metadata.fetch.MetadataSource

Represents a source to query for metadata. Subclasses must implement at least the fetch method.

When fetch() is called, the self object will have the following useful attributes (each of which may be None):

title, author, publisher, isbn, log, verbose and extra

Use these attributes to construct the search query. extra is reserved for future use.

The fetch method must store the results in self.results as a list of MetaInformation objects. If there is an error, it should be stored in self.exception and self.tb (for the traceback).

MetadataSource.metadata_type

The type of metadata fetched. ‘basic’ means basic metadata like title/author/isbn/etc. ‘social’ means social metadata like tags/rating/reviews/etc.

Default: 'basic'

MetadataSource.string_customization_help

If not None, the customization dialog will allow for string based customization as well the default customization. The string customization will be saved in the site_customization member.

Default: None

MetadataSource.fetch()

All the actual work is done here.