KupferObject

base class for basic user-visible constructs, this defines:

• A way to get the object's name
• A way to get the object's description
• A way to get the object's icon

This is the base object for the following four very important base classes:

• Leaf
• Action
• Source
• TextSource

Below follows a summary. For complete information, you should read kupfer's python interface documentation: go to the directory containing the kupfer module and do:

$ python
>>> from kupfer import main, objects
>>> help(objects.KupferObject)
>>> help(objects.Leaf)
>>> help(objects.Action)
>>> help(objects.Source)

Leaf

A Leaf represents an object that the user will want to summon and act on. An example is a file, an application, a window or a Free-text query (TextLeaf).

This defines, in addition to KupferObject:

Leaf.object

Leaf.object is the represented object, which is the implementation-specific internal data.

get_actions()

Returns the builtin Actions for a Leaf; builtin Actions are such that do not apply generally, but only to Leaves defined in a particular module or Plugin.

__hash__ and __eq__

Leaves are hashable, can be members in a set, and duplicates are recognized (and removed); this is essensial so that equivalent Leaves from different sources are recognized. By default duplicates are recognized if both the name and the Leaf.object property are the same.

has_content() and content_source()

These methods are used to find out if the object contain anything, like a folder contains files or a music album songs.

Action

An Action represents a command using a direct object and an optional indirect object. One example is objects.Show that will open its direct object (which must be a file), with its default viewer.

Actions are the most versatile parts of Kupfer, since they can define ways to use objects together. They also have to decide, which types of Leaves they apply to, and if they apply to a given Leaf.

Action defines, in addition to KupferObject:

activate(leaf, obj)

Called to perform its effect on a Leaf, where obj is the (optional) indirect object.

item_types()

This method returns all the types of Leaves that the action applies to (direct object).

valid_for_item(item)

Return whether action applies to item or not, which is of one of the types returned by item_type.

requires_object()

Whether this action uses an indirect object or not. If the Action requires an indirect object, it must also define (at least) object_types.

object_types()

Return all the types of Leaves that are valid for the action's indirect object.

object_source(for_item)

If the action's indirect objects should not be picked from the full catalog, but from a defined source, return an instance of the Source here, else return None.

valid_object(obj, for_item)

This method, if defined, will be called for each indirect object (with the direct object as for_item), to decide if it can be used.

Some auxiliary methods tell Kupfer about how to handle the action:

is_factory()

If the action returns content, return a collection of new items.

has_result()

If the action's return value in activate should treated as the new selection.

is_async()

If the action returns a Task object conforming to kupfer.task.Task. The task will be executed asynchronously in Kupfer's task queue.

Source

A Source understands specific data and delivers Leaves for it. For example DirectorySource, that will give FileLeaves for contents of a directory.

This defines, in addition to KupferObject:

get_items()

Source subclasses should define get_items to return its items; the items are cached automatically until mark_for_update is called.

is_dynamic()

Return True if the Source should not be cached. A source should almost never be dynamic.

should_sort_lexically()

Return True if the Source's leaves should be sorted alphabethically. If not sorted lexically, get_items should yield leaves in order of the most relevant object first (for example the most recently used).

provides()

Return a sequence of all precise Leaf types the Source may contain

get_leaf_repr()

Return a Leaf that represents the Source, if applicable; for example the DirectorySource is represented by a FileLeaf for the directory.

__hash__ and __eq__

Sources are hashable, and equivalents are recognized just like Leaves, and the central SourceController manages them so that there are no duplicates in the application.

TextSource

A text source returns items for a given text string, it is much like a simplified version of Source.

get_item(text)

Return items for the given query.

provides()

Return a sequence of the Leaf types it may contain

Living and learning

Most of kupfer plugin code uses super statements such as:

super(RecentsSource, self).__init__(_("Recent items"))

when writing new code, you should however use the following style:

Source.__init__(self, _("Recent items"))

Why? Because the second version is easier to copy! If you copy the whole class and rename it, which you often do to create new plugins, the second version does not need to be updated -- you are probably using the same superclass.