.. include:: global.rst

.. currentmodule:: calibre.customize.__init__

.. _customize:

Customizing |app|
==================================

|app| has a highly modular design. Various parts of it can be customized. You can learn how to create
*recipes* to add new sources of online content to |app| in the Section :ref:`news`. Here, you will learn how to
use *plugins* to customize and control various aspects of |app|'s behavior. 

Theer are different kinds of plugins, corresponding to different aspects of |app|. As more and more aspects of |app|
are modularized, new plugin types will be added.

.. contents::
    :depth: 2
    :local:

A Hello World plugin
------------------------

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:

.. code-block:: python

  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.kovidgoyal.net/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...

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. 
