Plugin API

Writing plugins

To add support for a new file format, write a new KurtPlugin subclass:

import kurt
from kurt.plugin import Kurt, KurtPlugin

class MyScratchModPlugin(KurtPlugin):
    def load(self, fp):
        kurt_project = kurt.Project()
        # ... set kurt_project attributes ... #
        return kurt_project

    def save(self, fp, kurt_project):
        # ... save kurt_project attributes to file ...

Kurt.register(MyScratchModPlugin())

Take a look at kurt.scratch20 for a more detailed example.

List available plugins

To get a list of the plugins registered with Kurt:

>>> kurt.plugin.Kurt.plugins.keys()
['scratch20', 'scratch14']

You should see your plugin in the output, unless you forgot to register it.

Notes

Some things to keep in mind:

• Most Scratch file formats have the stage as the base object – so project attributes, such as the notes and the list of sprites, are stored on the stage object.
• For Scratch, which doesn’t support stage-specific variables, global variables and lists are stored on the Project, not the Stage.
• If your plugin contains obsolete blocks, they should be at the end of the blocks list. Otherwise things might not work properly.

---

KurtPlugin

class kurt.plugin.KurtPlugin

Bases: object

Handles a specific file format.

Loading and saving converts between a Project, kurt’s internal representation, and a file of this format.

name = 'scratch14'

Short name of this file format, Python identifier style. Used internally by kurt.

Examples: "scratch14", "scratch20.sprite", "byob3", "snap"

display_name = 'Scratch 2.0 Sprite'

Human-readable name of this file format. May be displayed to the user. Should not contain “Project” or “File”.

Examples: "Scratch 1.4", "Scratch 2.0 Sprite", "BYOB 3.1"

extension = '.sb'

The extension used by this format, with leading dot.

Used by Project.load to recognise its files.

features = []

A list of the Features that the plugin supports.

blocks = []

The list of PluginBlockType objects supported by this plugin, in the order they appear in the program’s interface.

load(fp)

Load a project from a file with this format.

Project.path will be set later. Project.name will be set to the filename of the path to the file if unset.

Parameters:fp – A file pointer to the file, opened in binary mode. Returns:Project

save(fp, project)

Save a project to a file with this format.

Parameters:

• path – A file pointer to the file, opened in binary mode.
• project – a Project

Kurt

class kurt.plugin.Kurt

Bases: object

The Kurt file format loader.

This class manages the registering and selection of file formats. Used by Project.

classmethod register(plugin)

Register a new KurtPlugin.

Once registered, the plugin can be used by Project, when:

• Project.load sees a file with the right extension
• Project.convert is called with the format as a parameter

classmethod get_plugin(name=None, **kwargs)

Returns the first format plugin whose attributes match kwargs.

For example:

get_plugin(extension="scratch14")

Will return the KurtPlugin whose extension attribute is "scratch14".

The name is used as the format parameter to Project.load and Project.save.

Raises:ValueError if the format doesn’t exist. Returns:KurtPlugin

classmethod block_by_command(command)

Return the block with the given command.

Returns None if the block is not found.

classmethod blocks_by_text(text)

Return a list of blocks matching the given text.

Capitalisation and spaces are ignored.