Plugin Development

[KevinH]

Updated the Plugin Documentation post near the front of this thread with Sigil_Plugin_Framework_rev5.epub which has information/documentation for the new plugin features that will be available in Sigil 0.8.900

I left up rev4 of the docs just in case as it is valid for the stable 0.8.5, 0.8.6, and 0.8.7 releases of Sigil.

Hope this helps,

KevinH

[Doitsu]

I had a quick look at the examples and noticed that you used sigil_bs4 in conjunction with the gumbo parser. Does this mean that sigil_bs4 will only work with the gumbo parser or could I import sigil_bs4 like the vanilla version?

For example, would I only have to change:

from bs4 import BeautifulSoup

to:

from sigil_bs4 import BeautifulSoup

to make existing plugins compatible with the next Sigil version?

[KevinH]

Hi Doitsu,

We have our own version of BeautifulSoup4 we call sigil_bs4. It will always be available to both Python 2.7 plugins and Python 3.4 plugins once Sigil 0.8.900 is out.

To use it in place of any local or system specific version of official BS4, you do exactly what you noted:

change "import bs4" to "import sigil_bs4" or use the changes you stated below.

And go from there. This will give you the Sigil version of bs4 which runs on both python 2.7 and 3.4 with the same codebase and which has prettyprint_xhtml() and serialize_xhtml() methods as well as bug fixes for using lxml with bs4.

It will work just like bs4 does for other projects, it is just that our gumbo interface requires it.

Hope that explains things.

KevinH

Originally Posted by Doitsu

I had a quick look at the examples and noticed that you used sigil_bs4 in conjunction with the gumbo parser. Does this mean that sigil_bs4 will only work with the gumbo parser or could I import sigil_bs4 like the vanilla version?

For example, would I only have to change:

from bs4 import BeautifulSoup

to:

from sigil_bs4 import BeautifulSoup

to make existing plugins compatible with the next Sigil version?

[KevinH]

And yes, there was test code mistakenly left in the docs (thank you Doitsu!), so a new version has now been uploaded to the earlier post in this thread.

Sigil_Plugin_Framework_rev5a.epub

[KevinH]

Hi All,

This is just a head's up. In the upcoming release of Sigil 0.8.901, we have added in some new plugin interface routines that are needed to work with ePub3's via plugin.

These new routines provide support for adding/manipulating properties on manifest items and for adding/manipulating properties on spine itemrefs.

The new ("edit" plugin) bookcontainer.py routines are:

    # New for epub3
    def getspine_epub3(self):
        # spine is an ordered list of tuples (id, linear, properties)
        return self._w.getspine_epub3()

    # New for epub3
    def setspine_epub3(self, new_spine):
        # new_spine must be an ordered list of tuples (id, linear, properties (or None))
        self._w.setspine_epub3(new_spine)

    # Modified for epub3
    def spine_insert_before(self, pos, spid, linear, properties=None):
        self._w.spine_insert_before(pos, spid, linear, properties)

    # New for epub3
    def setspine_idref_epub3_attributes(idref, linear, properties):
        self._w.setspine_idref_attributes(idref, linear, properties)


    # Modified for epub3
    def addfile(self, uniqueid, basename, data, mime=None, properties=None):
        # creates a new file in the manifest with unique manifest id, basename, data, and mimetype
        self._w.addfile(uniqueid, basename, data, mime, properties)

    # New for epub3
    def set_manifest_epub3_properties(self, id, properties):
        # sets the epub3 manifest property for this manifest id
        self._w.set_manifest_epub3_property(id, properties)

    # New for epub3
    def manifest_epub3_iter(self):
        # yields manifest id, href, mimetype, and properties
        for id in sorted(self._w.id_to_mime):
            mime = self._w.id_to_mime[id]
            href = self._w.id_to_href[id]
            properties = self._w.id_to_props[id]
            yield id, href, mime, properties

    # New for epub3
    def spine_epub3_iter(self):
        # yields spine idref, linear(yes,no,None), properties, href in spine order
        for (id , linear, properties) in self._w.spine:
            href = self._w.id_to_href[id]
            yield id, linear, properties, href

    # New for epub3
    def id_to_properties(self, id, ow=None):
        return self._w.map_id_to_props(id, ow)

The new launcher version will report 20151001.

Note that these changes are versioned with "epub3", and the older interface routines are still there and still work. There should be no breakage of current plugins.

Also note, with these latest changes, it should now be possible for plugin developers to add epub3 features via python plugins even before we get a chance to add them to Sigil. I am thinking here of epub3 metadata editing or conversion, and autogeneration of a nav as some thigns that would certainly be doable with plugins.

Hope this helps,

KevinH

[rubeus]

What i'm supposed to do if i want to create plugins running with the built in python interpreter?

It must run under 3.4?

What do i have to enter in the preference? leave the path to the interpreter blank?

I gues there will be a mixter of plugins where i need to have the 2.7 still installed due to already available plugins, will there be a problem with the built in one? How does the decison wrok in Sigil what interpreter is to be used?

And at least: are there example available on how to huse the built in libraries?

So many questions...

//rubeus

[Doitsu]

Originally Posted by rubeus

What i'm supposed to do if i want to create plugins running with the built in python interpreter?

1. Install Python 2.7 or 3.4 (only required for Sigil 0.8.7)

2. In the Manage Plugins dialog box, click the Auto button(s).

3. Download the Sigil Plugin Guide, which contains many examples.
(Note that validation plugins require Sigil 0.8.7 or higher and hunspell plugins Sigil 0.8.9 or higher.)

4. Locate the plugin folder. If you have a Windows machine, press +R, enter the following path and press Enter:

%LOCALAPPDATA%\sigil-ebook\sigil\plugins

Create a test folder with two text files in it

plugin.py
plugin.xml

(The folder must be named test.)

5. Paste the following text into plugin.xml:

<?xml version="1.0" encoding="UTF-8"?>
<plugin>
<name>test</name>
<type>edit</type>
<author>test</author>
<description>test</description>
<engine>python2.7</engine>
<engine>python3.4</engine>
<version>0.1</version>
<oslist>unx,win,osx</oslist>
</plugin>

6. Paste the following sample code into plugin.py:

#!/usr/bin/env python
# -*- coding: utf-8 -*-
from __future__ import unicode_literals, division, absolute_import, print_function
import platform
    
# main routine
def run(bk):
    print('Python Laucher Version:', bk.launcher_version())
    print('Python Version:', platform.python_version())
        
    print('\nDone.\n\nPlease click OK to close the Plugin Runner window.')
    return 0

def main():
    print('I reached main when I should not have\n')
    return -1

if __name__ == "__main__":
    sys.exit(main())

7. Restart Sigil and select Plugins > Manage Plugins > Edit > test.
If the plugin works, replace the code in Magenta with your own code.

Originally Posted by rubeus

It must run under 3.4?

Since Sigil 0.8.9 comes with a bundled Python 3.4 interpreter, Python 3.4 is recommended.

Originally Posted by rubeus

I guess there will be a mixture of plugins where i need to have the 2.7 still installed due to already available plugins, will there be a problem with the built in one?

Some older plugins require Python 2.7, but all plugins written by KevinH and DiapDealer support both Python versions.

Originally Posted by rubeus

How does the decision work in Sigil what interpreter is to be used?

Sigil will use the interpreters in the order in which they're defined in plugin.xml.

[rubeus]

Thx for the details. Especially 2) was very helpful as i had a wrong imagination about "built in python" and i was wondering that nothing worked as i didnt installed a python interpreter in my VM. I wasnt aware that there is a python interpreter as exe coming along with sigil which needs to be brought in here by the Auto button.

So i will see to change my plugins to be able to run without having the need to install a seperate python interpreter

Unfortunetly, the sigil-python3.exe cant run alone so i as a deverloper needs to have it installed and due the already existing 2.7 plugin i need to have the 2.7 interpreter installed as well.

Not an ideal sitiuation...

Nevertheless

[KevinH]

I am happy to help any plugin developer convert their existing plugins from python 2.7 only to code that will work with both python 2.7 and python 3 at the same time.

Also, I am unsure what you mean by "sigil-python3.exe can't run alone". On Mac OSX the embedded python can certainly run alone and on Windows you should be able to use it to run your plugins as well. There will in fact be a new checkbox in Preferences for it.

So please explain what isn't working to use the embedded python to run plugins.

Thanks,

KevinH

[rubeus]

Thx for the offer, but i will take the opportunity to do that by my own - learning by doing. Bit for sure i will come back if i encounter problems

I just tried to execute sigil-python3.exe outside sigil on a CLI and got the error

[C:\Program Files\Sigil\python3]sigil-python3.exe
Fatal Python error: Py_Initialize: unable to load the file system codec
LookupError: no codec search functions registered: can't find encoding

If i wont to try out things first by playing around a little bit i still need a "full" python interpreter

[Doitsu]

Originally Posted by rubeus

I just tried to execute sigil-python3.exe outside sigil on a CLI and got the error

You're not supposed to run sigil-python3.exe directly. It'll be run by Sigil with special command line parameters.

[rubeus]

To be honest i would have been surpised if it worked but i just gave it a try to see if i can skip the installation of a separate python interpreter as i dislike to have things in double on my computer.

[KevinH]

On a Mac it does work. The error sounds like python3 can not find its own standard library. Be careful that you do not have some Python environment variable set that points to Python 2.7 when trying to run Python 3.4.

KevinH

[rubeus]

In the VM i'm playing around is no other Python installation

[KevinH]

Okay, I will take a look at this and get back to you.

KevinH