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 ...


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.


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.


class kurt.plugin.KurtPlugin[source]

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 a project from a file with this format.

Project.path will be set later. 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.
save(fp, project)[source]

Save a project to a file with this format.

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


class kurt.plugin.Kurt[source]

Bases: object

The Kurt file format loader.

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

classmethod register(plugin)[source]

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)[source]

Returns the first format plugin whose attributes match kwargs.

For example:


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

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

Raises:ValueError if the format doesn’t exist.
classmethod block_by_command(command)[source]

Return the block with the given command.

Returns None if the block is not found.

classmethod blocks_by_text(text)[source]

Return a list of blocks matching the given text.

Capitalisation and spaces are ignored.