Newcomer's thoughts about writing calibre plugins

Marco77 · 01-01-2017, 11:32 AM

Hello,

Here are a recollection of thoughts I had while developing a calibre plugin. I hope it doesn't sound like an endless flow of complaints~, and apologize if it reads like so.

As an end user, you don't quite realize how large the software is. You give more appreciation to Kovid's work over the years when you realize the volume and relative complexity of the ensemble
I felt it lacked a bit of guidance, especially at the beginning. (Something that looks like good practice: Wordpress developer handbook) There are the 3 manual articles linked in the plugins sticky, and then you're on your own. At this point a good grepping tool is a must. Questions that popped up include:
what's a spine item vs a manifest item?
there are primitives and boss methods that seem to clash, e.g. rewind_savepoint vs self.boss.revert_requested; add_file vs. self.boss.do_add_file. Since the developer can import anything, which is the 'correct' one?
lxml is a pain (especially: the docs & working with namespaces), but alternatives are probably worse
print testing is a PITA, especially if you need to inspect a collection of an object. Wasn't aware of the ipython method, ugh that would have helped a ton.
calibre's built-in reporting dialogs saved a lot of time
would have loved to learn how to unit-test plugin components. Are you supposed to mock the whole framework (calibre)?
I use the github hosting to provide zips for release, unfortunately for us, calibre only supports zip with __init__.py at the top level of the archive (also reported in another thread). Would it be possible to support zips with a single folder at top-level at some point in the future? without having to register at launchpad if possible.

kovidgoyal · 01-01-2017, 09:13 PM

Certainly plugin writing could use more tutorials -- unfortunately I am not the person to write them, as I am too familiar with the codebase, so I cannot put myself in a plugin developers shoes -- contributions are welcome.

As for what the external API of the Boss class is, it is documented here: https://manual.calibre-ebook.com/pol...book.boss.Boss
which is linked to from the tutorial on writing editor plugins.

You can run any python script you like in the full calibre environment using calibre-debug file.py
which can be used for unit testing your plugins.

I'm not particularly inclined to make the plugin loading code more complex/slower just to support github's inability to create top-level zip files. As far as distributing plugins using github is concerned, I suggest you simply distribute them as source, a user installing a plugin from source simply has to run (to install plugin)

git clone https://.../whatever && calibre-customize -b whatever

and to update plugin
cd whatever && git pull && calibre-customize -b .

01-01-2017, 11:32 AM	#1
Marco77 Connoisseur Posts: 55 Karma: 8430 Join Date: Mar 2016 Device: PW3, Clara HD, PB740	Newcomer's thoughts about writing calibre plugins Hello, Here are a recollection of thoughts I had while developing a calibre plugin. I hope it doesn't sound like an endless flow of complaints~, and apologize if it reads like so. As an end user, you don't quite realize how large the software is. You give more appreciation to Kovid's work over the years when you realize the volume and relative complexity of the ensemble I felt it lacked a bit of guidance, especially at the beginning. (Something that looks like good practice: Wordpress developer handbook) There are the 3 manual articles linked in the plugins sticky, and then you're on your own. At this point a good grepping tool is a must. Questions that popped up include: what's a spine item vs a manifest item? there are primitives and boss methods that seem to clash, e.g. rewind_savepoint vs self.boss.revert_requested; add_file vs. self.boss.do_add_file. Since the developer can import anything, which is the 'correct' one? lxml is a pain (especially: the docs & working with namespaces), but alternatives are probably worse print testing is a PITA, especially if you need to inspect a collection of an object. Wasn't aware of the ipython method, ugh that would have helped a ton. calibre's built-in reporting dialogs saved a lot of time would have loved to learn how to unit-test plugin components. Are you supposed to mock the whole framework (calibre)? I use the github hosting to provide zips for release, unfortunately for us, calibre only supports zip with __init__.py at the top level of the archive (also reported in another thread). Would it be possible to support zips with a single folder at top-level at some point in the future? without having to register at launchpad if possible.

Similar Threads
Thread	Thread Starter	Forum	Replies	Last Post
Thoughts on writing	crich70	Writers' Corner	10	03-19-2015 12:26 PM
Getting PyCharm code completion while writing Calibre plugins	trying	Development	6	03-30-2014 05:47 AM
Any Thoughts on Scheduling Teaching and Writing	bmcox	Writers' Corner	2	01-14-2014 12:59 AM
Thoughts from P.D. James about writing...	HarryT	Writers' Corner	9	11-10-2013 03:04 PM
Calibre Portable like the Calibre on PC (espec. settings and plugins)?	manawydan	Devices	6	01-23-2013 06:45 AM

01-01-2017, 09:13 PM	#2
kovidgoyal creator of calibre Posts: 43,853 Karma: 22666666 Join Date: Oct 2006 Location: Mumbai, India Device: Various	Certainly plugin writing could use more tutorials -- unfortunately I am not the person to write them, as I am too familiar with the codebase, so I cannot put myself in a plugin developers shoes -- contributions are welcome. As for what the external API of the Boss class is, it is documented here: https://manual.calibre-ebook.com/pol...book.boss.Boss which is linked to from the tutorial on writing editor plugins. You can run any python script you like in the full calibre environment using calibre-debug file.py which can be used for unit testing your plugins. I'm not particularly inclined to make the plugin loading code more complex/slower just to support github's inability to create top-level zip files. As far as distributing plugins using github is concerned, I suggest you simply distribute them as source, a user installing a plugin from source simply has to run (to install plugin) git clone https://.../whatever && calibre-customize -b whatever and to update plugin cd whatever && git pull && calibre-customize -b .

Advert