Sulfur Programmers Guide
Prev	Chapter 2. Sulfur Plug-Ins	Next

Plug-In Objects

All plug-in objects are instances of a subclass of Sulfur.Plugin. As described above, each plug-in module contains a class definition for the plug-in; this class should inherit from Sulfur.Plugin. (In many cases, individual plug-ins inherit from a common superclass for their collection; for example, the Backup class might inherit from Conduit, which in turn inherits from Sulfur.Plugin.)

Class Attributes

Each plug-in has a number of class attributes, which are used to provide relatively static information about the plug-in to your application. Because these are class attributes, they are accessible even before a plug-in object is created; that way, you can obtain information about a plug-in without causing it to actually do anything.

The following class attributes are defined by all Sulfur plug-ins:

name (string): The name of the plug-in. Note that this is not necessarily the same name that your program will use to load the plug-in; sometimes, it will be a longer or more human-friendly name for the plug-in.
author (string): The author of the plug-in. The suggested format is like that found in an e-mail header, for example 'Rob Tillotson <robt@debian.org>'.
description (string): A description of the plug-in.
version (string): The plug-in version, in whatever format the developer prefers. Future versions of Sulfur will implement automatic version checking for plug-ins.
url (string): A URL pointing to further information about the plug-in, the package it came in, or something else of interest.
type (string): The type of the plug-in. Normally, this is equal to the name of the collection the plug-in is in.
type_name (string): A human-friendly representation of the plug-in's type, suitable for use in help text, configuration dialogs, and the like. For example, a plug-in with a type of 'ifilter' might have a type_name of 'Input Filter'.
properties (sequence): A set of values (normally strings) listing the properties of the plug-in.
options (list of Options): A list of Option objects describing the plug-in's configurable options. See INSERT REFERENCE HERE for more details on plug-in option handling.
is_plugin (always true): This attribute can be used to test whether a class defines a plug-in, or whether an object is a plug-in. (The obvious way of doing this, Python's isinstance and issubclass functions, don't seem to work in all situations.)

Methods

The following methods are available on all plug-in objects. Each plug-in (or each plug-in type) will probably provide additional methods which implement its unique behavior.

has_property (property): Returns true if the plug-in has the specified property.
has_option (name): Returns true if the plug-in has the named option.
get_option (name): Returns the current value of the named option. Raises KeyError if the plug-in does not have the named option.
set_option (name, value): Sets the value of a plug-in option. Raises KeyError if the plug-in does not have the option. If the given value is not appropriate for the specified option, ValidationError (see INSERT REFERENCE HERE) is raised, and the option keeps its previous value.
configure (options): Set all option values at once. The single parameter may be a dictionary (keyed by option name), or it may be a Registry object (see INSERT REFERENCE HERE).
log (string): Write a string to the plug-in's log file. (Normally, the log output goes to sys.stdout, but the plug-in developer may change that.)
__call__ (*, **): By convention, all plug-ins are callable; although the default behavior is to do nothing, plug-in developers will normally use this method as the primary entry point for the plug-in. Valid parameters depend on the application.