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:

$ pydoc2.6 kupfer.obj.base

or equivalently:

>>> import kupfer.obj.base
>>> help(kupfer.obj.base.KupferObject)
>>> help(kupfer.obj.base)

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 kupfer.obj.fileactions.Open 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

initialize()

Called when the source should be made ready to use. This is where it should register for external change callbacks, for example.

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_text_items(text)

Return items for the given query.

provides()

Return a sequence of the Leaf types it may contain

Using rank_adjust

A declaration like this can modify the ranking of an object:

class MyAction (Action):
    rank_adjust = -5
    ...

1. Often, this is useless. Don't use it, let Kupfer learn which actions are important.
2. If the action is destructive, the adjust should be negative. Never positive. For example Move to Trash has a negative 10 rank_adjust.
3. If the action is very general, and applies to almost everything but still should never be the default for anything, the adjust should be negative.

Using super(..)

Many of kupfer plugin code uses super statements such as:

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

We have learnt that it is not so practical. Therefore, 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.

Text and Encodings

Care must be taken with all input and output text and its encoding! Internally, kupfer must use unicode for all internal text. The module kupfer.kupferstring has functions for the most important text conversions.

Two good resources for unicode in Python are to be found here:

Always find out what encoding you must expect for externally read text (from files or command output). If you must guess, use the locale encoding. Text received from PyGTK is either already unicode or in the UTF-8 encoding, so this text can be passed to kupferstring.tounicode.

Note that the gettext function _() always returns a unicode string.