KindleUnpack the calibre Plugin

Open KindleBooks in Sigil

A calibre plugin based/wrapped around the KindleUnpack software. (python based software to unpack Amazon / Kindlegen generated ebooks)

Building

First, clone the repo:

$ git clone https://github.com/dougmassay/kindleunpack-calibre-plugin.git

Then you need to prepare the source by downloading some core files from the KindleUnpack project. I'm not going to track those files here since they're already maintained in another Git repository. There's a script in the 'setup_tools' folder that will download/patch what you need. Just cd into the 'setup_tools' folder and run the getkucore.py script with Python 2.7+ or 3.4+ (don't try to run the script from outside the 'setup_tools' folder).

$ cd ./kindleunpack-calibre-plugin/setup_tools
$ python getkucore.py
$ cd ..

This will create a kindleunpackcore folder. You only need to prepare this folder once -- unless KindleUnpack is updated and you want to use the latest. In that case, just repeat those last 3 steps whenever you want to update the kindleunpackcore files. It will delete the folder and recreate it as necessary.

To create the plugin zip file, run the setup.py script (root of the repository tree) with Python

$python setup.py

You can also add a -d (or --debug) option to setup.py. If calibre is installed and on your path and you add the '-d' option, setup.py will attempt to:

1) close calibre if it's open
2) install the plugin using calibre-customize
3) relaunch calibre in debug-mode

If all goes well, the plugin can now be run and any debug print statements/errors should print to the terminal. If you have a complex calibre setup (or it's not on you path), you may need to install the plugin manually to debug.

** Note if you're not using the debug option with setup.py, you can use Python2 or Python3 to build the plugin. But if if you're using the -d option to install the plugin and launch calibre, you must use Python2.

Contributing / Modifying

From here on out, a proficiency with developing / creating calibre plugins is assumed. If you need a crash-course, an introduction to creating calibre plugins is available at http://manual.calibre-ebook.com/creating_plugins.html.

Any changes to files in the kindleunpackcore folder will be ignored. The repository is setup to ignore this folder (meaning git won't track changes to them). If you have modifications to suggest for those files, do so upstream at https://github.com/kevinhendricks/KindleUnpack.

Any changes there can be pulled into this repository by running the getkucore.py script in the 'setup_tools' folder at any time.

The core plugin files (this is where most contributors will spend their time) are:

> images/explode3.png
> __init__.py
> action.py
> plugin-import-name-kindleunpack_plugin.txt
> config.py
> dialogs.py
> mobi_stuff.py
> utilities.py

It's important to note that any import statements in the above files that look like:

from calibre_plugins.kindleunpack_plugin.kindleunpackcore.blah import blah

are actually referring to a 'blah' module / script in the kindleunpackcore directory. These imports will only "work" in the context of a calibre plugin's structure and the calibre environment. If you need to refer to or call those modules that's where they'll be. But as mentioned above ... go upstream if you have patches or pull requests for those files.

For example, if you need to import something from the kindleunpackcore/ directory (for example: compatibility_utils.py), you would use:

from calibre_plugins.kindleunpack_plugin.kindleunpackcore.compatibility_utils import PY2

The rest of the scripts above (dialogs.py, etc...) can be imported using the prefix of:

calibre_plugins.kindleunpack_plugin.

Files used for building/maintaining the plugin:

> setup.py  -- this is used to build the plugin.
> setup.cfg -- used for flake8 style checking. Use it to see if your code complies.
> setup_tools/getkucore.py  -- used to retrieve/prepare upstream KindleUnpack files.
> setup_tools/pythonpatch.py  -- used by setup.py to apply patches to upstream files if necessary.
> setup_tools/kindleunpack.patch  -- patch that will be applied to kindleunpackcore/kindleunpack.py
> setup_tools/mobi_nav.patch  -- patch that will be applied to kindleunpackcore/mobi_nav.py

License Information