Writing a first plugin

[chaley]

Originally Posted by Agama

Due to my lack of knowledge I saw:

and I wrongly assumed that this refered to gui2/dialogs/tweak_epub_ui.py, which I couldn't find!
Kovid confirmed that this actually refers to gui2/dialogs/tweak_epub.ui which I do have.
(I don't know exactly how these .ui files work but I guess there is a help document somewhere.)

The latest source does not contain gui2/dialogs/tweak_epub*

The .ui files are built by the Qt tool "designer", a fairly vanilla graphical gui builder tool. In some cases they are built by hand when "designer" doesn't do what one wants or when it is easier to modify an existing file.

When calibre starts, the dates on the .ui files are compared to those of the _ui.py files. If the .ui file is newer, it is "compiled" into python that is stored in the _ui.py file, which is imported by the code that needs to manipulate the resulting gui.

I downloaded calibre source some months ago so I'm not sure which version it is. How do I find out and should I update it? I am not running from source but simply using it as a means of learning calibre/Python programming.

src/calibre/constants.py. Look for "numeric_version". The latest is
numeric_version = (0, 8, 56)

[kiwidude]

This all being a perfect example to agama's other question about whether to update or not - calibre changes very frequently, and you are looking at code that Kovid rewrote recently to support tweaking things other than ePub. So you are tiptoeing on quicksand in this case

Re the .ui files thing - from a calibre plugin perspective I have always avoided them. When I first started writing plugins there were question marks over compiling code in plugins etc that were never completely answered at the time. The Qt designer is not sufficiently more productive to have ever got me bothered about revisiting it. So every plugin dialog I have written just has handwritten dialog code, similar to the net effect of using the designer, then compiling the code, then including that in your plugin, I find it faster for my purposes anyways.

In the calibre code you will find a mixture - some dialogs are handcoded in the same way, whereas the majority of the calibre gui uses those UI files. My advice would be to not bother with adding another learning curve of the Qt Designer especially given your plugin doesn't even really need a UI from what you have described, but that's just my opinion

[Agama]

My source is (0, 8, 10).

How often is it a good idea to update and how do I do it? (or is this a "How long is a piece of string" question?). Does it require another full download? (This took nearly 2 hours first time round).

My plugin just needs a simple configuration item so I won't be delving into UI code just yet.

[chaley]

Originally Posted by Agama

How often is it a good idea to update and how do I do it? (or is this a "How long is a piece of string" question?). Does it require another full download? (This took nearly 2 hours first time round).

I update before looking at code or changing anything, often more than once per day. Reasons:
- I don't want to be confused by something that behaves differently from what the code says it should do.
- I want to see bug fixes.
- Looking at changes, and especially the refactoring changes, is a good way to learn.
- I don't want to change code that is no longer in calibre.

I always update before submitting code to be sure that I am not submitting something that won't work or that conflicts with some other change. Of course, if you are not doing development on calibre's trunk (as I do) and are not depending on the code you are looking at being correct (as I am), then there is no requirement to upgrade. In the end, the decision is yours.

As for how to upgrade, running "bzr pull" from inside the source tree will get all the changes from the last time you did a pull/download. This will work only if you have not made any changes to a file under version control. If you have made changes, then you can toss the changes into the trash can using "bzr revert". You might (or might not) want to use the --no-backup option. If you have made changes you want to keep, then things are more complicated.

In your case, the first "pull" will take a while because it must download so many versions, but it will take less time than a full download. I find that daily pulls run in seconds. The exception is Friday after a release when all the translations are downloaded, in which case it can sometimes take nearly a minute but usually run in around 30 seconds. I have a very fast internet connection (100 Mbit), so your mileage could easily be worse than mine.

[Agama]

The source update only took about 30 mins and Tweak ePub had indeed changed. I finally got version 1 of my plugin working and it was a satisfying moment , so thanks for all the help.

I then decided to play with the interface_demo plugin to increase my understanding of plugins and python. I broke it a few times and learned from the experience, then I removed some code which I expected would break it – but didn't! At the top of each .py file there is:

from __future__ import (unicode_literals, division, absolute_import,
 print_function)

I expected to get an error which would give me a module and line number to look at, but the plugin still worked. So what does this code do?

Also there are couple of comment lines at the top:

#!/usr/bin/env python
# vim:fileencoding=UTF-8:ts=4:sw=4:sta:et:sts=4:ai

Are these used by any process or just for information?

[kovidgoyal]

http://docs.python.org/library/__future__.html

The first two lines are just boilerplate so unix shells know how to execute the file and so that vim knows how to set itself up when editing the file.

[Agama]

I did have a look at the Python docs first, but I'm still not quite sure why the plugin didn't fail when I removed the __future__ imports. Does this indicate that it simply isn't required in that particular plugin? Is it just a standard import to use in plugins because it's generally useful?

[kovidgoyal]

__future__ changes the way the interpreter interprets certain things. This is to allow you to write code that will work with later releases of python. In this case python 3. So yes, you should have it in all your plugin files.

[Agama]

OK, I've put the __future__ imports back in.

Is there any reason why some from module import x, y, z statements put the x, y, z list in brackets but some don't? Is this significant or just personal preference?

Also sometimes we see code like:

action_spec = ('Normalise ePub', None, 'Normalise ePub after markdown conversion', None)

but sometimes action_spec parameters are coded like:

action_spec = (_('Normalise ePub'), None, _('Normalise ePub after calibre conversion'), None)

What to the _( ) brackets indicate?

[kiwidude]

The brackets on import just means you don't have to put a line continuation character of \ at the end of each line when you do multiline importing.

The _() indicate a language translation lookup. Since plugins that aren't bundled with calibre aren't hooked into calibre's translation mechanism, there isn't much point in using that syntax, unless you are using some text that you know exists inside calibre itself and hence will get translated.

[Agama]

Can I refer to my plugin's InterfaceActionBase properties from other .py files within the same plugin? For example in main.py I want to refer to the version tuple defined in __init__.py.

[kovidgoyal]

You can import anything from one file into another, with the only caveat being to avoid circular imports at the global level. That means if you import something from file X into file Y, do not also import something else from file Y into file X.

[kiwidude]

@agama - another way if the import is an issue is that your InterfaceAction class has a property on it called .interface_action_base_plugin which refers to that class.

So either:
- you are in the interface action class, in which case you can use:

self.interface_action_base_plugin.version

- you are in some other class. You can either pass through your plugin action instance to it to do the above trick, or get the interface action by passing the "self.gui" to that class and then:

plugin_action = gui.iactions['My Plugin Name']
plugin_action.interface_action_base_plugin.version

[Agama]

Good stuff! The straight-forward import worked as there was no circular reference, but these additional options look good too.

I've been working back through several plugins to broaden my knowledge and sometimes there are imports without a from. For example:

import tempfile, os, atexit

How do I locate these in the calibre source tree? I've searched for these filenames but without success.

[chaley]

Those are imports from base python. They will be documented at http://docs.python.org/library/