toolshed: Manage installed and available tools

The Toolshed provides an interface for finding installed tool distributions as well as distributions available for installation from a remote server. The Toolshed can handle updating, installing and uninstalling distributions while taking care of inter-distribution dependencies.

The Toolshed interface uses distlib heavily. For example, Distribution instances from distlib are tracked for both available and installed tools; the distlib.locators.Locator class is used for finding an installed distlib.database.Distribution.

Each Python distribution (Chimera uses distlib.wheel.Wheel) may contain multiple tools. Metadata blocks in each distribution contain descriptions for tools. Each tool is described by a ‘Chimera-Tool’ entry that consists of seven fields separated by double colons (::).

  1. Chimera-Tools : str constant

    Field identifying entry as tool metadata.

  2. name : str

    Internal name of tool. This must be unique across all tools.

  3. module_name : str

    Name of module or package that implements the tool.

  4. display_name : str

    Name of tool to display to users.

  5. commands : str

    Comma-separated list of cli commands that the tool provides.

  6. menu_categories : str

    Comma-separated list of menu categories in which the tool belong.

  7. synopsis : str

    A short description of the tool.

Modules referenced in distribution metadata must define:

register_command(command_name)
Called when delayed command line registration occurs. command_name is a string of the command to be registered.
start_tool(session, ti, *args, **kw)
Called to create a tool instance. session is a Session instance for the current session. ti is a ToolInfo instance for the tool to be started.

Attributes

TOOLSHED_TOOL_INFO_ADDED : str
Name of trigger fired when new tool metadata is registered. The trigger data is a ToolInfo instance.
TOOLSHED_TOOL_INSTALLED : str
Name of trigger fired when a new tool is installed. The trigger data is a ToolInfo instance.
TOOLSHED_TOOL_UNINSTALLED : str
Name of trigger fired when an installed tool is removed. The trigger data is a ToolInfo instance.

Notes

The term ‘installed’ refers to tools whose corresponding Python module or package is installed on the local machine. The term ‘available’ refers to tools that are listed on a remote server but have not yet been installed on the local machine.

class ToolInfo(name, installed, distribution_name=None, distribution_version=None, display_name=None, module_name=None, synopsis=None, menu_categories=(), command_names=())

Bases: object

Metadata about a tool, whether installed or available.

A ToolInfo instance stores the properties about a tool and can create a tool instance.

Attributes

command_names (list of str) List of cli command name registered for this tool.
display_name (str) The tool name to display in user interfaces.
installed (boolean) True if this tool is installed locally; False otherwise.
menu_categories (list of str) List of categories in which this tool belong.
name (readonly str) The internal name of the tool.
synopsis (readonly str) Short description of this tool.
version (readonly str) Tool version (which is actually the same as the distribution version, so all tools from the same distribution share the same version).
cache_data()

Return state data that can be used to recreate the instance.

Returns:

2-tuple of (list, dict)

List and dictionary suitable for passing to ToolInfo.

deregister_commands()

Deregister commands with cli.

distribution()

Return distribution information.

Returns:

2-tuple of (str, str).

Distribution name and version.

get_class(class_name)

Return tool’s class with given name.

newer_than(ti)

Return whether this ToolInfo instance is newer than given one

Parameters:

ti : ToolInfo instance

The instance to compare against

Returns:

Boolean

True if this instance is newer; False if ‘ti’ is newer.

register_commands()

Register commands with cli.

start(session, *args, **kw)

Create and return a tool instance.

Parameters:

session : Session instance

The session in which the tool will run.

args : any

Positional arguments to pass to tool instance initializer.

kw : any

Keyword arguments to pass to tool instance initializer.

Returns:

ToolInstance instance

The registered running tool instance.

Raises:

ToolshedUninstalledError

If the tool is not installed.

ToolshedError

If the tool cannot be started.

class Toolshed(logger, appdirs, rebuild_cache=False, check_remote=False, remote_url=None)

Bases: object

Toolshed keeps track of the list of tool metadata, aka ToolInfo.

Tool metadata may be for “installed” tools, where their code is already downloaded from the remote server and installed locally, or “available” tools, where their code is not locally installed.

Attributes

triggers (TriggerSet instance) Where to register handlers for toolshed triggers
add_tool_info(ti)

Add metadata for a tool.

Parameters:

ti : ToolInfo instance

Must be a constructed instance, i.e., not an existing instance returned by tool_info().

Notes

A TOOLSHED_TOOL_INFO_ADDED trigger is fired after the addition.

check_remote(logger)

Check remote shed for updated tool info.

Parameters:

logger : Logger instance

Logging object where warning and error messages are sent.

Returns:

list of ToolInfo instances

List of tool metadata from remote server.

find_tool(name, installed=True, version=None)

Return a tool with the given name.

Parameters:

name : str

Name (internal or display name) of the tool of interest.

installed : boolean

True to check only for installed tools; False otherwise.

version : str

None to find any version; specific string to check for one particular version.

install_tool(ti, logger, system=False)

Install the tool by retrieving it from the remote shed.

Parameters:

ti : ToolInfo instance

Should be from the available tool list.

system : boolean

False to install tool only for the current user (default); True to install for everyone.

logger : Logger instance

Logging object where warning and error messages are sent.

Raises:

ToolshedInstalledError

Raised if the tool is already installed.

Notes

A TOOLSHED_TOOL_INSTALLED trigger is fired after installation.

reload(logger, rebuild_cache=False, check_remote=False)

Discard and reread tool info.

Parameters:

logger : Logger instance

A logging object where warning and error messages are sent.

rebuild_cache : boolean

True to ignore local cache of installed tool information and rebuild it by scanning Python directories; False otherwise.

check_remote : boolean

True to check remote server for updated information; False to ignore remote server; None to use setting from user preferences.

tool_info(installed=True, available=False)

Return list of tool info.

Parameters:

installed : boolean

True to include installed tool metadata in return value; False otherwise

available : boolean

True to include available tool metadata in return value; False otherwise

Returns:

list of ToolInfo instances

Combined list of all selected types of tool metadata.

uninstall_tool(ti, logger)

Uninstall tool by removing the corresponding Python distribution.

Parameters:

ti : ToolInfo instance

Should be from the installed tool list.

logger : Logger instance

Logging object where warning and error messages are sent.

Raises:

ToolshedInstalledError

Raised if the tool is not installed.

Notes

A TOOLSHED_TOOL_UNINSTALLED trigger is fired after package removal.

exception ToolshedError

Bases: Exception

Generic Toolshed error.

exception ToolshedInstalledError

Bases: chimera.core.toolshed.ToolshedError

Tool-already-installed error.

This exception derives from ToolshedError and is usually raised when trying to install a tool that is already installed.

exception ToolshedUnavailableError

Bases: chimera.core.toolshed.ToolshedError

Tool-not-found error.

This exception derives from ToolshedError and is usually raised when no Python distribution can be found for a tool.

exception ToolshedUninstalledError

Bases: chimera.core.toolshed.ToolshedError

Uninstalled-tool error.

This exception derives from ToolshedError and is usually raised when trying to uninstall a tool that has not been installed.

init(*args, debug=False, **kw)

Initialize toolshed.

The toolshed instance is a singleton across all sessions. The first call creates the instance and all subsequent calls return the same instance. The toolshed debugging state is updated at each call.

Parameters:

debug : boolean

If true, debugging messages are sent to standard output. Default value is false.

other arguments : any

All other arguments are passed to the Toolshed initializer.

Returns:

Toolshed instance

The toolshed singleton.