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 (::
).
Chimera-Tools
: str constantField identifying entry as tool metadata.
name
: strInternal name of tool. This must be unique across all tools.
module_name
: strName of module or package that implements the tool.
display_name
: strName of tool to display to users.
commands
: strComma-separated list of cli commands that the tool provides.
menu_categories
: strComma-separated list of menu categories in which the tool belong.
synopsis
: strA 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 aSession
instance for the current session.ti
is aToolInfo
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 oneParameters: ti :
ToolInfo
instanceThe 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
instanceThe 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
instanceThe 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
instanceMust 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
instanceLogging object where warning and error messages are sent.
Returns: list of
ToolInfo
instancesList 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
instanceShould 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
instanceLogging 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
instanceA 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
instancesCombined list of all selected types of tool metadata.
-
uninstall_tool
(ti, logger)¶ Uninstall tool by removing the corresponding Python distribution.
Parameters: ti :
ToolInfo
instanceShould be from the installed tool list.
logger :
Logger
instanceLogging 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.
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
instanceThe toolshed singleton.