toolshed: Manage installed and available tools¶
The Toolshed provides an interface for finding installed bundles as well as bundles available for installation from a remote server. The Toolshed can handle updating, installing and uninstalling bundles while taking care of inter-bundle dependencies.
Each Python distribution, a ChimeraX Bundle, may contain multiple tools, commands, data formats, and specifiers, with metadata entries for each deliverable.
In addition to the normal Python package metadta,
The ‘ChimeraX’ classifier entries give additional information.
Depending on the values of ‘ChimeraX’ metadata fields,
modules need to override methods of the BundleAPI
class.
Each bundle needs a ‘ChimeraX :: Bundle’ entry
that consists of the following fields separated by double colons (::
).
ChimeraX :: Bundle
str constantField identifying entry as bundle metadata.
categories
strComma-separated list of categories in which the bundle belongs.
session_versions
two comma-separated integersMinimum and maximum session version that the bundle can read.
supersedes
: str Comma-separated list of superseded bundle names.custom_init
strWhether bundle has initialization code that must be called when ChimeraX starts. Either ‘true’ or ‘false’. If ‘true’, the bundle must override the BundleAPI’s ‘initialize’ and ‘finish’ functions.
Bundles that provide tools need:
ChimeraX :: Tool
str constantField identifying entry as tool metadata.
tool_name
strThe globally unique name of the tool (also shown on title bar).
categories
strComma-separated list of categories in which the tool belongs. Should be a subset of the bundle’s categories.
synopsis
strA short description of the tool. It is here for uninstalled tools, so that users can get more than just a name for deciding whether they want the tool or not.
Tools are created via the bundle’s ‘start_tool’ function. Bundles may provide more than one tool.
Bundles that provide commands need:
ChimeraX :: Command
str constantField identifying entry as command metadata.
command name
strThe (sub)command name. Subcommand names have spaces in them.
categories
strComma-separated list of categories in which the command belongs. Should be a subset of the bundle’s categories.
synopsis
strA short description of the command. It is here for uninstalled commands, so that users can get more than just a name for deciding whether they want the command or not.
Commands are lazily registered, so the argument specification isn’t needed until the command is first used. Bundles may provide more than one command.
Bundles that provide selectors need:
ChimeraX :: Selector
str constantField identifying entry as command metadata.
selector name
strThe selector’s name.
synopsis
strA short description of the selector. It is here for uninstalled selectors, so that users can get more than just a name for deciding whether they want the selector or not.
atomic
strAn optional boolean specifying whether the selector applies to atoms and bonds. Defaults to ‘true’ and should be set to ‘false’ if selector should not appear in Basic Actions tool, e.g., showing/hiding selected items does nothing.
Commands are lazily registered, so the argument specification isn’t needed until the command is first used. Bundles may provide more than one command.
Bundles that provide data formats need:
ChimeraX :: DataFormat
str constantField identifying entry as data format metadata.
data_name
strThe name of the data format.
nicknames
strAn optional comma-separated list of alternative names. Often a short name is provided. If not provided, it defaults to the lowercase version of the data format name.
category
strThe toolshed category.
suffixes
strAn optional comma-separated list of strings with leading periods, e.g., ‘.pdb’.
mime_types
strAn optinal comma-separated list of strings, e.g., ‘chemical/x-pdb’.
url
strA string that has a URL that points to the data format’s documentation.
dangerous
strAn optional boolean and should be ‘true’ if the data format is insecure – defaults to true if a script.
icon
strAn optional string containing the filename of the icon – it defaults to the default icon for the category. The file should be ?TODO? – metadata dir? package dir?
synopsis
: str A short description of the data format. It is here because it needs to be part of the metadata available for uninstalled data format, so that users can get more than just a name for deciding whether they want the data format or not.
Bundles may provide more than one data format. The data format metadata includes everything needed for the Mac OS X application property list.
Data formats that can be fetched:
# ChimeraX :: Fetch :: database_name :: format_name :: prefixes :: example_id :: is_default
Data formats that can be opened:
# ChimeraX :: Open :: format_name :: tag :: is_default
Data formats that can be saved:
# ChimeraX :: Save :: format_name :: tag :: is_default
Bundles that have other data:
# ChimeraX :: DataDir :: dir_path # ChimeraX :: IncludeDir :: dir_path # ChimeraX :: LibraryDir :: dir_path
- TOOLSHED_BUNDLE_INFO_ADDED¶
Name of trigger fired when new bundle metadata is registered. The trigger data is a
BundleInfo
instance.- Type:
- TOOLSHED_BUNDLE_INSTALLED¶
Name of trigger fired when a new bundle is installed. The trigger data is a
BundleInfo
instance.- Type:
- TOOLSHED_BUNDLE_UNINSTALLED¶
Name of trigger fired when an installed bundle is removed. The trigger data is a
BundleInfo
instance.- Type:
- TOOLSHED_BUNDLE_INFO_RELOADED¶
Name of trigger fired when bundle metadata is reloaded. The trigger data is a
BundleInfo
instance.- Type:
- TOOLSHED_OUT_OF_DATE_BUNDLES¶
Name of trigger fired when out-of-date bundles are detected. The trigger data is None.
- Type:
Notes
The term ‘installed’ refers to bundles whose corresponding Python module or package is installed on the local machine. The term ‘available’ refers to bundles that are listed on a remote server but have not yet been installed on the local machine.
- class BundleAPI¶
Bases:
object
API for accessing bundles
The metadata for the bundle indicates which of the methods need to be implemented.
- static data_dir(bundle_info)¶
Supported API . Returns path to directory of bundle-specific data.
Used to get directory path to data included in the bundle.
- Parameters:
bundle_info (
BundleInfo
instance.)- Return type:
str or None
- static executable_dir(bundle_info)¶
Experimental API . Returns path to directory of compiled executables.
Used to get directory path to executables at run-time.
- Parameters:
bundle_info (
BundleInfo
instance.)- Return type:
str or None
- static finish(session, bundle_info)¶
Supported API . Called to deinitialize a bundle in a session.
Must be defined if the
custom_init
metadata field is set to ‘true’.finish
is called when the bundle is unloaded.- Parameters:
session (
Session
instance.)bundle_info (
BundleInfo
instance.)
- static get_class(name)¶
Supported API . Called to get named class from bundle.
Used when restoring sessions. Instances whose class can’t be found via ‘get_class’ can not be saved in sessions. And those classes must implement the
State
API.- Parameters:
name (str) – Name of class in bundle.
- static include_dir(bundle_info)¶
Experimental API . Returns path to directory of C++ header files.
Used to get directory path to C++ header files needed for compiling against libraries provided by the bundle.
- Parameters:
bundle_info (
BundleInfo
instance.)- Return type:
str or None
- static init_manager(session, bundle_info, name, **kw)¶
Supported API . Called to create a manager in a bundle at startup.
Must be defined if there is a
Manager
tag in the bundle, unless that tag has an autostart=”false” attribute, in which case the bundle is in charge of creating the manager as needed.init_manager
is called when bundles are first loaded. It is the responsibility ofinit_manager
to make the manager locatable, e.g., assign as an attribute of session.- Parameters:
session (
Session
instance.)bundle_info (
BundleInfo
instance.)name (str.) – Name of manager to initialize.
kw (keyword arguments.) – Keyword arguments listed in the bundle_info.xml.
- Returns:
The created manager.
- Return type:
ProviderManager
instance
- static initialize(session, bundle_info)¶
Supported API . Called to initialize a bundle in a session.
Must be defined if the
custom_init
metadata field is set to ‘true’.initialize
is called when the bundle is first loaded. To make ChimeraX start quickly, custom initialization is discouraged.- Parameters:
session (
Session
instance.)bundle_info (
BundleInfo
instance.)
- static library_dir(bundle_info)¶
Experimental API . Returns path to directory of compiled libraries.
Used to get directory path to libraries (shared objects, DLLs) for linking against libraries provided by the bundle.
- Parameters:
bundle_info (
BundleInfo
instance.)- Return type:
str or None
- static register_command(*args)¶
Supported API . When ChimeraX starts, it registers placeholders for commands from all bundles. When a command from this bundle is actually used, ChimeraX calls this method to register the function that implements the command functionality, and then calls the command function. On subsequent uses of the command, ChimeraX will call the command function directly instead of calling this method. The API version for this method is defined by the
api_version
class variable and defaults to 0.- Parameters:
bundle_info (
BundleInfo
instance.)command_info (
CommandInfo
instance.)logger (
Logger
instance.) – Version 1 of the API passes in information for both the command to be registered and the bundle where it was defined.command (str)
logger – Version 0 of the API only passes in the name of the command to be registered.
- static register_selector(*args)¶
Supported API . This method is called the first time when the selector is used.
- Parameters:
bundle_info (
BundleInfo
instance.)selector_info (
SelectorInfo
instance.)logger (
chimerax.core.logger.Logger
instance.) – Version 1 of the API passes in information about both the selector to be registered and the bundle where it is defined.selector_name (str)
logger – Version 0 of the API only passes in the name of the selector to be registered.
- static run_provider(session, name, mgr, **kw)¶
Supported API . Called to invoke a provider in a bundle.
Must be defined if there is a
Provider
tag in the bundle.run_provider
is called by the associated manager to perform the corresponding task.- Parameters:
session (
Session
instance.)name (str.) – Name of provider to initialize.
mgr (str.) – Name of manager for this provider.
kw (keyword arguments.) – Keyword arguments, if any, provided by the calling manager. Such keywords are specific to the manager and would be documented by the manager.
- static start_tool(*args)¶
Supported API . This method is called when the tool is invoked, typically from the application menu. Errors should be reported via exceptions.
- Parameters:
session (
chimerax.core.session.Session
instance.)bundle_info (
BundleInfo
instance.)tool_info (
ToolInfo
instance.) – Version 1 of the API passes in information for both the tool to be started and the bundle where it was defined.session
tool_name (str.) – Version 0 of the API only passes in the name of the tool to be started.
- Returns:
The created tool.
- Return type:
ToolInstance
instance
- class NewerVersionQuery(session)¶
Bases:
Task
- on_finish()¶
Experimental API . Callback method executed after task thread terminates.
This callback is executed in the UI thread after the
run()
method returns. By default, it does nothing.
- classmethod restore_snapshot(session, data)¶
Experimental API . Create object using snapshot data.
- run(service_name, params, blocking=False)¶
Experimental API . Run the task.
This method must be overridden to implement actual functionality.
terminating()
should be checked regularly to see whether user has requested termination.
- take_snapshot(session, flags)¶
Experimental API . Return snapshot of current state of instance.
The semantics of the data is unknown to the caller. Returns None if should be skipped. The default implementation is for non-core classes and returns a copy of the instance dictionary (a deep copy of lists/dicts/etc., but shallow copy of named objects). Named objects are later converted to unique names.
- Return type:
dict
[any
,any
]
- class ProviderManager(manager_name)¶
Bases:
object
API for managers created by bundles
- abstract add_provider(bundle_info, provider_name, **kw)¶
Experimental API . Callback invoked to add provider to this manager.
- Parameters:
session (
chimerax.core.session.Session
instance.)bundle_info (
BundleInfo
instance.)provider_name (str.)
- end_providers()¶
Experimental API . Callback invoked after all providers have been added.
- class Toolshed(logger, rebuild_cache=False, check_remote=False, remote_url=None, check_available=True, session=None)¶
Bases:
object
Toolshed keeps track of the list of bundle metadata, aka
BundleInfo
.Tool metadata may be for “installed” bundles, where their code is already downloaded from the remote server and installed locally, or “available” bundles, where their code is not locally installed.
- triggers¶
Where to register handlers for toolshed triggers
- Type:
TriggerSet
instance
- bootstrap_bundles(session, safe_mode)¶
Supported API . Do custom initialization for installed bundles
After adding the
Toolshed
singleton to a session, allow bundles need to install themselves into the session, (For symmetry, there should be a way to uninstall all bundles before a session is discarded, but we don’t do that yet.)
- bundle_info(logger, installed=True, available=False)¶
Supported API . Return list of bundle info.
- Parameters:
installed (boolean) – True to include installed bundle metadata in return value; False otherwise
available (boolean) – True to include available bundle metadata in return value; False otherwise
- Returns:
Combined list of all selected types of bundle metadata.
- Return type:
list of
BundleInfo
instances
- find_bundle(name, logger, installed=True, version=None)¶
Supported API . Return a
BundleInfo
instance with the given name.- Parameters:
name (str) – Name (internal or display name) of the bundle of interest.
logger (
Logger
instance) – Logging object where warning and error messages are sent.installed (boolean) – True to check only for installed bundles; False otherwise.
version (str) – None to find any version; specific string to check for one particular version.
- find_bundle_for_class(cls)¶
Supported API . Find bundle that has given class
- find_bundle_for_command(cmd)¶
Supported API . Find bundle registering given command
cmd must be the full command name, not an abbreviation.
- find_bundle_for_tool(name, prefix_okay=False)¶
Supported API . Find named tool and its bundle
Return the bundle it is in and its true name.
- Parameters:
name (str) – Name or prefix of the tool of interest.
prefix_okay (boolean) – Whether name only needs to be a prefix of a tool name or must be an exact match.
- import_bundle(bundle_name, logger, install='ask', session=None)¶
Supported API . Return the module for the bundle with the given name.
- Parameters:
bundle_name (str) – Name (internal or display name) of the bundle of interest.
logger (
Logger
instance) – Logging object where warning and error messages are sent.install (str) – Action to take if bundle is uninstalled but available. “ask” (default) means to ask user, if session is not None; “never” means not to install; and “always” means always install.
session (
chimerax.core.session.Session
instance.) – Session that is requesting the module. Defaults to None.
- Raises:
ImportError – Raised if a module for the bundle cannot be found.
- install_bundle(bundle, logger, *, per_user=True, reinstall=False, session=None, no_deps=False)¶
Supported API . Install the bundle by retrieving it from the remote shed.
- Parameters:
bundle (string or
BundleInfo
instance or sequence of them) – If string, path to wheel installer. If instance, should be from the available bundle list.per_user (boolean) – True to install bundle only for the current user (default); False to install for everyone.
reinstall (boolean) – True to force reinstall package.
logger (
Logger
instance) – Logging object where warning and error messages are sent.
- Raises:
ToolshedInstalledError – Raised if the bundle is already installed.
Notes
A
TOOLSHED_BUNDLE_INSTALLED
trigger is fired after installation.
- reload(logger, *, session=None, reread_cache=True, rebuild_cache=False, check_remote=False, report=False, _session=None)¶
Supported API . Discard and reread bundle 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 bundle 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
- uninstall_bundle(bundle, logger, *, session=None, force_remove=False)¶
Supported API . Uninstall bundle by removing the corresponding Python distribution.
- Parameters:
bundle (string or
BundleInfo
instance or sequence of them) – If string, path to wheel installer. If instance, should be from the available bundle list.logger (
Logger
instance) – Logging object where warning and error messages are sent.
- Raises:
ToolshedInstalledError – Raised if the bundle is not installed.
Notes
A
TOOLSHED_BUNDLE_UNINSTALLED
trigger is fired after package removal.
- exception ToolshedInitializationError¶
Bases:
ToolshedError
Initialization error.
This exception derives from ToolshedError and is usually raised when doing manager, provider or custom initialization.
- exception ToolshedInstalledError¶
Bases:
ToolshedError
Bundle-already-installed error.
This exception derives from
ToolshedError
and is usually raised when trying to install a bundle that is already installed or to uninstall a bundle that is not installed yet.
Bases:
ToolshedError
Bundle-not-found error.
This exception derives from ToolshedError and is usually raised when no Python distribution can be found for a bundle.
- get_toolshed()¶
Supported API . Return current toolshed.
- Returns:
Toolshed
instance – The toolshed singleton.The toolshed singleton will be None if py:func:init hasn’t been called yet.
- init(*args, debug=None, **kw)¶
Supported API . 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.
arguments (other) – All other arguments are passed to the Toolshed initializer.
- class BundleInfo(name, installed, version=None, api_package_name=None, categories=(), synopsis=None, description='Unknown', session_versions=range(1, 2), custom_init=False, data_dir=None, include_dir=None, library_dir=None, executable_dir=None, managers=None, providers=None, inits=None, packages=None, supersedes=None)¶
Bases:
object
Supported API. Metadata about a bundle, whether installed or available.
A
BundleInfo
instance stores the properties about a bundle and can create a tool instance.- commands¶
list of
CommandInfo
List of commands registered for this bundle.
- installed¶
boolean True if this bundle is installed locally; False otherwise.
- session_versions¶
range Given as the minimum and maximum session versions that this bundle can read.
- session_write_version¶
integer The session version that bundle data is written in. Defaults to maximum of ‘session_versions’.
- custom_init¶
boolean Whether bundle has custom initialization code
- cache_data()¶
Supported API . Return state data that can be used to recreate the instance.
- Returns:
List and dictionary suitable for passing to
BundleInfo
.- Return type:
- data_dir()¶
-
- Returns:
Path (relative to the bundle root) of the bundle’s data directory.
- dependents(logger)¶
Supported API . Return set of bundles that directly depends on this one.
- Parameters:
logger (
Logger
instance) – Where to log error messages.- Returns:
Dependent bundles.
- Return type:
set of
BundleInfo
instances
- deregister(logger)¶
Supported API . Deregister bundle commands, tools, data formats, selectors, etc.
- Parameters:
logger (
Logger
instance) – Where to log error messages.
- distribution()¶
Supported API . Return distribution information.
- executable_dir()¶
Supported API . Returns: Path (relative to bundle root) of the bundle’s directory of executables.
- finish(session)¶
Supported API . Deinitialize bundle by calling custom finish code if needed.
This method is only called when a bundle is explicitly unloaded. In particular, it is not called when ChimeraX exits normally.
- classmethod from_cache_data(data)¶
Supported API . Class method for reconstructing instance from cache data. :rtype: instance of BundleInfo
- get_class(class_name, logger)¶
Supported API . Return bundle’s class with given name.
- get_module(force_import=True)¶
Supported API . Return module that has bundle’s code
- include_dir()¶
-
Returns: Path (relative to bundle root) of the bundle’s directory of compilation include files.
- init_manager(session, name, **kw)¶
Supported API . Initialize bundle manager if needed.
- initialize(session)¶
Supported API . Initialize bundle by calling custom initialization code if needed.
- library_dir()¶
-
Returns: Path (relative to bundle root) of the bundle’s directory of link libraries.
- property name¶
Supported API.
Returns: Internal name of the bundle.
- newer_than(bi)¶
Supported API . Return whether this
BundleInfo
instance is newer than given one- Parameters:
bi (
BundleInfo
instance) – The instance to compare against- Returns:
True if this instance is newer; False if ‘bi’ is newer.
- Return type:
Boolean
- register(logger)¶
Supported API . Register bundle commands, tools, data formats, selectors, etc.
- Parameters:
logger (
Logger
instance) – Where to log error messages.
- run_provider(session, name, mgr, **kw)¶
Supported API . Called by manager to invoke bundle provider.
- property short_name¶
Supported API.
- Returns:
A short name for the bundle. Typically the same as ‘name’ with ‘ChimeraX-’ omitted.
- start_tool(session, tool_name, *args, **kw)¶
Supported API . 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:
The registered running tool instance.
- Return type:
ToolInstance
instance- Raises:
ToolshedError – If the tool is not installed or cannot be started.
- property synopsis¶
Supported API.
- Returns:
Bundle synopsis; a short description of this bundle.
- unload(logger)¶
Supported API . Unload bundle modules (as best as we can).
- property version¶
Supported API.
- Returns:
Bundle version (which is actually the same as the distribution version, so all bundles from the same distribution share the same version).
- class CommandInfo(name, categories, synopsis=None)¶
Bases:
ToolInfo
Metadata about a command