Plugin Development

[Doitsu]

Originally Posted by HaPeSchu

Still the problem remains that I have no access to the saved searches

Saved searches are stored in

sigil_searches.ini

in the Sigil preferences directory. It'd trivial to parse this file with the standard configparser Python library.

[wrCisco]

I'm writing here just in case some plugin developers would be interested in implementing an automated test suite for a Sigil plugin (also, suggestions for improvement are always welcome).

I understand that for most plugins an automated test suite would be an overkill, but for a plugin of medium or high complexity I think that would be a plus.

Until two weeks ago, I had no idea if such an implementation would be feasible without too much headache. Turned out it's not too complex, at least for my needs.

All the source code of the implementation for my last plugin is on github (is it ok to link it here?).

What I did in summary:

- I created a python3.8 virtual environment and installed via pip all the necessary dependencies (you can find which they are in the various Building_Sigil_on_* docs in the Sigil documentation on github. Probably a global installation or the bundled python interpreter shipped with Sigil installers would work the same, I didn't try it).

- I tweaked with a shell script the PYTHONPATH environment variable to include the /path/to/sigil/plugin_launchers/python and the path to my plugin files (which are obviously platform and installation dependent). That's not exactly the same as in the real Sigil environment, since the paths added to PYTHONPATH are appended to sys.path, so there is the risk of name clashes (but for small projects that's very unlikely).

- In the same script I set the environment variable SigilGumboLibPath to make it point to the shared library of sigilgumbo (this is platform dependent too, and I think it's needed only if the plugin uses the sigil's gumbo adapter for sigil_bs4).

- After that, in the tests, I just needed to create a mock to use instead of the BookContainer object.

And that's it. I don't know if there are simpler or better ways to simulate enough of Sigil environment to test the plugins, that's just what I put together in the last few days.
If you have any questions or advice, I'm all ears...

[KevinH]

Sounds interesting! For larger projects, I typically unzip an epub into a "root" folder inside a new project folder, then copy all the plugin code itself and add the very minimum python code to invoke the launcher.py script properly.

For small projects, I just change the plugin.py final "return 0" with "return -1" so that a full debug log is always created and nothing will ever get changed in Sigil by my plugin, then add a bunch of print statements, fire up Sigil and can launch my plugin again and again tweaking the plugin code as needed inside where it gets unpacked to in the Sigil Prefs folder. There is no need to delete or reinstall the plugin itself, and no need to even relaunch Sigil. Just a quick edit, run cycle.


I can easily see that a more rigorous test set-up outside Sigil itself might be valuable. The entire plugin interface is meant to be launched in a subprocess from within Sigil via the command line so it can be isolated away from Sigil. Just passing in the correct inputs and config file, setting paths, etc should be enough given an appropriate python3 setup is available.
.

Thanks!

[wrCisco]

Originally Posted by KevinH

For small projects, I just change the plugin.py final "return 0" with "return -1" so that a full debug log is always created and nothing will ever get changed in Sigil by my plugin, then add a bunch of print statements, fire up Sigil and can launch my plugin again and again tweaking the plugin code as needed inside where it gets unpacked to in the Sigil Prefs folder. There is no need to delete or reinstall the plugin itself, and no need to even relaunch Sigil. Just a quick edit, run cycle.

Yes, that's mostly what I do myself during development!
Obviously, while the project grows, it becomes less and less rigorous.

Originally Posted by KevinH

Sounds interesting! For larger projects, I typically unzip an epub into a "root" folder inside a new project folder, then copy all the plugin code itself and add the very minimum python code to invoke the launcher.py script properly.

I can easily see that a more rigorous test set-up outside Sigil itself might be valuable. The entire plugin interface is meant to be launched in a subprocess from within Sigil via the command line so it can be isolated away from Sigil. Just passing in the correct inputs and config file, setting paths, etc should be enough given an appropriate python3 setup is available.
.

Thanks!

So, by putting an unpacked epub in a folder, a properly filled 'sigil.cfg' file in another and then calling with appropriate arguments the function 'main' of the launcher.py module, I can launch a plugin outside of Sigil with a fully operational BookContainer object? That's very good to know!

The main rigidity with this approach is that you need to launch the whole plugin every time (unless you launch a different wrapper module every time, I guess...).

It sounds like if you put yours and my approach side by side, with some minor tweaks you could have both unit and functional testing capabilities at your disposal.

[DiapDealer]

GUI stuff always drives me bonkers when trying to debug inside of Sigil. So I usually create a method for launching the GUIs outside of Sigil -- dummying up any objects necessary from the launcher code to get things going. But yeah, sometimes a full-blown, separate plugin launcher environment is the only way to get any really good debug output.

[nir34]

Hi all,i am a python beginner,when i attach my python code to sigil,breakpoint will not hit,what's wrong is it?How to debug during developing a sigil plugin?Any help please.I use vs2019 as IDE.

[DiapDealer]

I don't use an IDE for debugging Python, so I probably won't be much help. In fact, I'm not even sure you CAN attach a debugger to the Sigil-launched python process that starts a Sigil plugin. Not without more work than it would probably be worth anyway.

[Doitsu]

Originally Posted by nir34

Hi all,i am a python beginner,when i attach my python code to sigil,breakpoint will not hit,what's wrong is it?How to debug during developing a sigil plugin?Any help please.I use vs2019 as IDE.

I simply print the value of variables to the Plugin Runner window and add a return -1 statement, when I want to check something:

def run(bk):
    # your code
    print(your_variable)
    return -1

[KevinH]

I think I will add a plugin SDK to my to-do items for the future. Given the design of the plugin interface is all file and path based and returns xml, a standalone system is doable. That way a separate debugger could easily be used.

I will look into it more after this next release.

[dowobeha]

Hi,

I'm potentially interested in developing a new plugin. Where should I look for documentation describing how to do so?

Thanks,
Lane

[Doitsu]

Here's the Framework Guide Github link.

[AxaRu]

Hi,

Can I read/write selected text block from plugin?

Thanks,
Alexey.

[KevinH]

The plugin interface is file based. It does get a list of the files selected in BookBrowser when the plugin is launched.

So preselecting a specific text block requires you to insert a marker of some sort or add a span with an known id to your xhtml before launching the the plugin, then tweak your plugin to look for it and process it. If you want to you can copy text to clipboard and have the plugin work with that.

[AxaRu]

KevinH, Thank for possible solution. Very difficult to use.

[KevinH]

In my own plugins I use Sigil's Clips tool to specify a clip I made, then select the text I want and apply the clip. That makes it a single click to mark text the way my plugin needs. Simple and works well.

To be more specific, my clip inserts xhtml comments both immediately before and after the selected text with a unique comment identifier. The plugin itself finds and removes them when running.

Setting id attributes or setting a specific class attribute for the text also works. Clips make these tasks quite easy.