Contents
Kupfer is a Python program that allows loading extension modules at runtime. A plugin is equivalent to one Python module implemented as one .py file or as a Python package.
The kupfer package is organized as follows:
kupfer/
obj/
ui/
core/
plugin/
core/__init__.py
applications.py
...
...
Plugins live in the package kupfer.plugin. Kupfer also includes directories called kupfer/plugins from $XDG_DATA_DIRS, which typically means /usr/share/kupfer/plugins and $HOME/.local/share/kupfer/plugins. These directories are transparently included into the kupfer package, so the user has multiple choices of where to install plugins.
A kupfer plugin is a .py file with some special attributes.
It starts like this (an imagined example):
__kupfer_name__ = _("Cool X-Documents")
__kupfer_sources__ = ("DocumentSource", )
__kupfer_text_sources__ = ()
__kupfer_actions__ = ("Open", )
__description__ = _("Documents from the X program")
__version__ = "1"
__author__ = "Tom Author"
All these special variables must be defined before any other code in the module (even imports). For a plugin, the following attributes are required:
__kupfer_name__ (Localized name of plugin) __description__ (Localized description of plugin) __version__ __author__
For the plugin to do anything, the following attributes may be defined:
__kupfer_sources__ = () __kupfer_text_sources__ = () __kupfer_actions__ = () __kupfer_action_generators__ = () __kupfer_contents__ = ()
They should be tuples of names of classes in the module:
all sources have to be subclasses of kupfer.objects.Source
all text sources have to be subclasses of kupfer.objects.TextSource
all actions have to be subclasses of kupfer.objects.Action
If an example plugin declares:
__kupfer_sources__ = ("DocumentSource", )
it will later in the file define the class DocumentSource:
from kupfer.objects import Source
class DocumentSource (Source):
def __init__(self):
Source.__init__(self, _("Cool X-Documents"))
def get_items(self):
...
# later we will see what we can do here!
Ok, this looks simple. So what are Leaves, Sources and Actions?
A Leaf is an object, it represents a program or a file, or a text or something else. Every type of Leaf has different possibilities, and you can define new Leaves. Example: a FileLeaf represents a file on the disk.
A Source produces a collection of Leaves, so it makes Kupfer know about new objects. For example, it can provide all the FileLeaves for a particular folder.
An Action is the part where something happens, an action is applied to a Leaf, and something happens. For example, Open can be an action that works with all FileLeaf.
The very simplest thing we can do is to provide an action on objects that already exist in Kupfer. These actions appear in the right-hand actions pane in kupfer, when an object of the right type is selected.
The complete python code for the plugin:
__kupfer_name__ = _("Image Viewer")
__kupfer_actions__ = ("View", )
__description__ = _("View images quickly")
__version__ = ""
__author__ = "Tom Author"
from gi.repository import Gtk
from kupfer.objects import Action, FileLeaf
class View (Action):
def __init__(self):
super().__init__(_("View"))
def item_types(self):
yield FileLeaf
def valid_for_item(self, fileobj):
return fileobj.object.endswith(".jpg")
def activate(self, fileobj):
image_widget = Gtk.Image.new_from_file(fileobj.object)
image_widget.show()
window = Gtk.Window()
window.add(image_widget)
window.present()That is all. What we did was the following:
Declare a plugin called "Image Viewer" with an action class View.
Every string inside _("") is translatable
View declares that it works with FileLeaf
View only accepts FileLeaf that end with '.jpg'
View defines a method activate that when called, will use gtk to show the file in a window
Note
Kupfer uses a simplified programming style of composition and cooperative superclasses.
You normally never call a superclass implementation inside a method that you define, with the exception of __init__.
On the other hand, there are superclass methods that should not be overridden. For example, KupferObject.get_pixbuf is never overridden, instead you implement KupferObject.get_icon_name.
Below follows a complete summary. To accompany this reference, you can read kupfer's inline module documentation with pydoc, by doing the following in the source directory:
$ pydoc kupfer.obj.base
or equivalently:
$ python
>>> help("kupfer.obj.base")
class KupferObject implements the things that are common to all objects: name, description, icon, thumbnail and name aliases.
This is called when you call Leaf.__init__, or Source.__init__, and so on in your object's __init__ method.
The name parameter must be a unicode string. An object can not change name after it has called __init__.
Return a longer user-visible unicode string that describes the object.
Return a string of one icon name for the object.
The icon name should preferably be in the Icon Naming Specification
Return a GIcon (GIO icon) object. This takes precedence over the icon name, if it is defined.
Implement get_thumbnail to return a GdkPixbuf object of the requested size that is a thumbnail of the object. If applicable.
This should not be redefined. Define get_icon_name and/or get_gicon instead.
This should not be redefined. Define get_icon_name and/or get_gicon instead.
Return an object whose str() will be used in the __repr__, self is returned by default. This value is used to differentiate and recognize objects. Override this if the objects type and name is not enough to differentiate it from other objects.
This should not be redefined. Define repr_key instead.
This should not be redefined, but can be called by the object to add an alternate name to the object.
A number to adjust the ranking of a certain object. Should only be used on Actions. Should be set in the range -10 to -1 for actions that apply to many objects but not default for any.
Used as a the class' fallback for icon name. Do not change this.
class Leaf inherits from KupferObject.
A Leaf represents an object that the user will want to act on. Examples are a file, an application or a free-text query (TextLeaf).
This defines, in addition to KupferObject:
The default implementation of __init__ stores the parameter obj into self.object and passes name up to KupferObject.__init__.
obj can be any data that the Leaf represents. name must be a unicode string.
Leaf.object is the represented object, which is the implementation-specific internal data.
Return a sequence of Actions that always apply to the Leaf. These are "built-in" actions.
Leaves are hashable, can be members in a set, and duplicates are recognized (and removed); this is essential so that equivalent Leaves from different sources are recognized.
These methods need normally not be overridden.
By default leaves are equal if both the name and the Leaf.object attribute are the same.
A leaf can contain something, like a folder contains files or a music album songs.
If the Leaf should have content, it should override has_content to return True and define content_source() to return an instance of a Source.
A Leaf may decide dynamically if it has content or not.
class Action inherits from KupferObject.
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.
An action is either a Subject + Verb action: It needs one object, this is the direct object.
Or it is a Subject + Verb + Object action: It needs two objects, one direct object ("obj") and one indirect object ("iobj").
Action defines, in addition to KupferObject:
Called to perform the action if the action is a normal Subject + Verb action.
Called to perform the action if the action is a three-way Subject + Verb + Object action. (That is, requires_object returns True)
If implemented, activate_multiple is called with preference over activate(self, obj, iobj) or activate(self, obj) as appropriate.
Implement activate_multiple to handle multiple objects on either side in a smart way.
You should implement activate_multiple if it is possible to do something better than the equivalent of repeating activate n times for n objects.
activate and activate_multiple also receive a keyword argument called ctx if the action defines wants_context(self) to return True. See wants_context below for more information.
This method should return a sequence of all Leaf types that the action can apply to (direct object).
This method is called for each potential direct object of the correct type. Return True if the object is compatible with the action.
By default always returns True.
Return True if the action is a Subject + Verb + Object action and requires both a direct and an indirect object.
If requires_object returns True, then you must must also define (at least) object_types.
Return a sequence of all Leaf types that are valid for the action's indirect object.
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. for_item is the direct object.
If the action has an object source, by default only that source is used for indirect objects. Return True here to use both the custom source and the whole catalog.
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. Return True if it can be used.
Return True if activate should receive an ExecutionToken as the keyword argument ctx. This allows posting late (after-the-fact) results and errors, as well as allowing access to the GUI environment.
wants_context defaults to False which corresponds to the old protocol without ctx.
So instead of activate(self, obj), the method should be implemented as activate(self, obj, ctx).
The object passed as ctx has the following interface:
Register the result_object as a late result. It must be a Leaf or a Source.
Register an asynchronous error. (For synchronous errors, simply raise an OperationError inside activate.)
For asynchronous errors, call register_late_error. If exc_info is None, the current exception is used. If exc_info is an OperationError instance, then it is used as error. Otherwise, a tuple like sys.exc_info() can be passed.
The environment object, which has the following methods:
Return the current event timestamp
Make and return a startup notification id
Return the display name (i.e :0.0)
Present window (a Gtk.Window) on the current workspace and monitor using the current event time.
Some auxiliary methods tell Kupfer about how to handle the action:
Return True if the return value of activate is a source that should be displayed immediately.
Return True if the action's return value in activate should be selected.
Return True if the action returns a Task object conforming to kupfer.task.Task from activate. The task will be executed asynchronously in Kupfer's task queue.
Override this to define a unique key for the action, if you need to differentiate between different instances of the same Action class.
The attribute action_accelerator is None by default but can be a single letter string to suggest a default accelerator for this action. Actions that act like the default open should use "o".
class Source inherits from KupferObject.
A Source understands specific data and delivers Leaves for it.
A Source subclass must at a minimum implement __init__, get_items and provides.
Source defines, in addition to KupferObject:
You must call this method with a unicode name in the subclass __init__(self).
Your source should define get_items to return a sequence of leaves which are its items; the return value is cached and used until mark_for_update is called.
Often, implementing get_items in the style of a generator (using yield) is the most convenient.
The Leaves shall be returned in natural order (most relevant first), or if sorting is required, return in any order and define should_sort_lexically.
get_leaves must not be overridden, define get_items instead.
Return a sequence of all precise Leaf types the Source may contain.
Often, the Source contains Leaves of only one type, in that case the implementation is written simply as yield ThatLeafType.
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).
This method is called when the source should be made ready to use. This is where it should register for external change callbacks, for example.
This method is called before the Source is disabled (shutdown or plugin deactivated).
Return a Leaf that represents the Source, if applicable; for example the DirectorySource is represented by a FileLeaf for the directory.
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.
Like get_items, called when a refresh is forced. By default it just calls get_items.
Should not be overridden. Call mark_for_update in the source to mark it so that it is refreshed by calling get_items.
Define to a unique key if you need to differentiate between sources of the same class. Normally only used with Sources from factory actions or from decorator sources.
If applicable, the source can return a different source to represent it and its objects in the top level of the catalog. The default implementation returns self which is normally what you want.
Return True if the Source should not be cached. This is almost never used.
These methods are must be implemented if the Source needs to save user-produced configuration data.
Return the name key to save the data under. This should almost always be literally return __name__
Implement this to return a datastructure that succintly but perfectly represents the configuration data. The returned value must be a composition of simple types, that is, nested compositions of dict, list, str etc.
This is called after finalize is called on the source.
The state parameter is passed in as the saved return value of config_save. config_restore is called before initialize is called on the Source.
A content-decorating source provides content to a Leaf, where it does not control the Leaf. An example is the recent documents content decorator, that provides document collections as content to applications.
A normal Source listed in __kupfer_sources__ will be eligible for content decoration as well if it implements the needed methods. Otherwise content-only sources are listed in __kupfer_contents__.
Return the type of Leaf that can be decorated. You must also implement decorate_item.
Return an instance of a Source (normally of the same type as the content decorator itself) that is the content for the object leaf. Return None if not applicable.
Sources returned from decorate_item go into the common Source pool. The new source instance will not be used if the returned instance is equivalent (as defined by class and reepr_key above).
Set to True if the source should have a user-visible Rescan action. Normally you much prefer to use change notifications so that this is not necessary.
Set to True to not export its objects to the top level by default. Normally you don't wan't to change this
If True, the source can be pickled to disk to save its cached items until the next time the launcher is started.
Internal number that is 1 by default. Update this number in __init__ to invalidate old versions of cache files.
TextSource inherits from KupferObject.
A text source returns items for a given text string, it is much like a simplified version of Source. At a minimum, a TextSource subclass must implement get_text_items and provides.
Override as __init__(self) to provide a unicode name for the source.
Return a sequence of Leaves for the unicode string text.
Return a sequence of the Leaf types it may contain
Return a static rank score for text output of this source.
ActionGenerator inherits from object.
ActionGenerator is a helper object that can be declared in __kupfer_action_generators__. It allows generating action objects dynamically.
Return a sequence of Action objects appropriate for this Leaf
Note
The ActionGenerator should not perform any expensive computation, and not access any slow media (files, network) when returning actions. Such expensive checks must postponed and be performed in each Action's valid_for_item method.
How a plugin is activated
The plugin module is imported into Kupfer.
If an error occurs, the loading fails and the plugin is disabled. If the error raised is an ImportError then Kupfer report it as a dependency problem.
Kupfer will initialize a kupfer.plugin_support.PluginSettings object if it exists (see next section)
Kupfer will call the module-level function initialize_plugin(name) if it exists.
Kupfer instantiates the declared sources and actions and insert sources, actions, content decorators, action generators and text sources into the catalog.
When a plugin is deactivated
When the plugin is disabled, the module-level function finalize_plugin(name) is called if it exists. [It is not yet final whether this function is called at shutdown or only when hot-unplugging plugins.]
This module provides important API for several plugin features.
To use user-settable configuration parameters, use:
__kupfer_settings__ = plugin_support.PluginSettings(
{
"key" : "frobbers",
"label": _("Number of frobbers"),
"type": int,
"value": 9,
},
)Where PluginSettings takes a variable argument list of config parameter descriptions. The configuration values are accessed with __kupfer_settings__[key] where key is from the parameter description. Notice that __kupfer_settings__ is not updated with the user values until the plugin is properly initialized.
PluginSettings is read-only but supports the GObject signal plugin-setting-changed (key, value) when values change.
plugin_support provides the convenience functions check_dbus_support() and check_keyring_support() that raise the appropriate error if a dependency is missing.
Alternatives are mutually exclusive features where the user must select which to use. Each category permits one choice.
Categories of Alternatives
the terminal used for running programs that require terminal
method used to look up icon names
Each category has a specific format of required data that is defined in kupfer/plugin_support.py. A plugin should use the function kupfer.plugin_support.register_alternative(caller, category_key, id_, **kwargs) to register their implementations of new alternatives. The arguments are:
register_alternative(caller, category_key, id_, ** kwargs)
the name of the calling plugin, is always __name__
one of the above categories
the plugin's identifier for the alternative
key-value pairs defining the alternative
register_alternative is normally called in the plugin's initialize_plugin(..) function.
Fields requried for the category terminal
unicode visible name
argument list: list of byte strings
the execute-flag as a byte string ("" when N/A)
the likely application id as a byte string
whether to use startup notification as boolean
Fields required for the category icon_renderer
unicode visible name
an object with an interface just like kupfer.icons.IconRenderer
A plugin is a Python module–either a single python file or a folder with an __init__.py file (a package module). In the latter case, the whole of the plugin can be defined inside __init__.py, or it can be split into several modules. Kupfer will look for all the description variables (like __kupfer_name__) in __init__.py.
Plugin-installed custom icons
A package module may include custom icons as .svg files. The icon files must be declared in a file inside the python package called icon-list.
Each line is a tab-separated field list, with the icon name in the first column and the filename (relative to the plugin package) in the second column.
Lines can be commented with a leading #
If a literal !override appears in the third column, the icon is installed even if it overrides the currently used GTK icon theme.
Plugins may be installed into any of the kupfer/plugins data directories. Package modules can also be installed and used as .zip files, so they too can be distributed as single files.
I want to specifically highlight certain files in Kupfer that are good to read as examples.
Custom Leaf and Action: the common case of creating a custom Leaf type and defining its default Open action, see kupfer/plugin/notes.py
Content decoration: making content for objects, see kupfer/plugin/archiveinside.py (Deep Archives plugin)
Asynchronous error reporting: see kupfer/plugin/volumes.py, action Unmount
There are several modules inside the kupfer package that a plugin can reuse.
kupfer.commandexec
kupfer.commandexec is not used by plugins anymore after version v204. See Auxiliary Method wants_context(self) above instead.
kupfer.config
kupfer.interface
This module does not need to be imported just to implement the interface it defines.
If a Leaf has a text representation (used for copy-to-clipboard), it should implement this method and return a unicode string.
kupfer.kupferstring
A byte string (Python str) is just a stream of data. When you handle byte strings that is text, you must convert it to unicode as soon as possible. You only know the encoding depending on the source of the byte string.
decode UTF-8 or unicode object into unicode.
coerce unicode ustr into a locale-encoded bytestring.
decode locale-encoded bytestring lstr to a unicode object.
kupfer.objects
kupfer.objects includes the basic objects from the package kupfer.obj, such as Leaf, Action, Source etc.
The basic re-usable types live here
Exception type for user-visible errors in action execution. Raise OperationError with a unicode localized error message inside Action.activate to notify the user of a serious error.
Specialized versions exist: Such as NotAvailableError(toolname), NoMultiError()
kupfer.pretty
kupfer.runtimehelper
kupfer.textutils
kupfer.uiutils
Show a notification. If a previous return value is passed as nid , try to replace that previous notification.
Returns a notification identifier, or None if notifications are not supported.
kupfer.utils
Spawn a child process, returning True if successfully started.
Display with default viewer for path or url.
File paths are bytestrings (and are not text). get_display_path_for_bytestring returns a user-displayable text representation as a unicode object.
kupfer.task
kupfer.weaklib
kupfer.core
The module kupfer.core can not be used by plugins.