Bundle Information XML Tags¶
ChimeraX bundle information is stored in bundle_info.xml. XML elements in the file typically have attributes and either (a) child elements, or (b) element text. An attribute is used for a value that may be represented as a simple string, such as an identifiers or a version numbers. The element text is used for a more complex value, such as a file name which may contain spaces. Child elements are used for multi-valued data, such as a list of file names, one element per value.
The supported elements are listed below in alphabetical order. The root document element is BundleInfo, which contains all the information needed to build the bundle.
NB: All elements except BundleInfo may have a platform
attribute. If the platform attribute is present and its
value does not matches the build platform, then the element and
all its children are ignored. Supported values for platform
are: mac
, windows
, and linux
. An example use for the
platform attribute is to support the Space Navigator device.
On macOS, ChimeraX relies on a compiled C module, while on Windows
and Linux, it uses pure Python with the ctypes
module;
in this case, the CModule element has a platform attribute
of mac
.
AdditionalPackages
List of additional packages to include in bundle in bundle
Child elements:
Package (one or more)
Author
Element text:
Name of bundle author
BundleInfo:
Root element containing all information needed to build the bundle.
Attributes:
name: bundle name (must start with
ChimeraX-
for now)customInit: set to
true
if bundle has custom initialization function; omit otherwiseinstalledDataDir: name of directory containing data files, relative to the bundle Python package directory
installedIncludeDir: name of directory containing C/C++ header files, relative to the bundle Python package directory
installedLibraryDir: name of directory containing DLLs (Windows), shared objects (Mac OS X), or shared libraries (Linux), relative to the bundle Python package directory
installedDataDir: name of directory containing data files, relative to the bundle Python package directory
limitedAPI: set to Python stable ABI version; omit otherwise. Typicaly used by binary bundles to declare that they can work with older versions of Python via Python’s Stable Application Binary Interface but can also be used by pure-Python bundles that are using very new language features to declare that they can’t work with older Python versions. In either case, the value is the oldest version that the bundle works with, and is of the form “3.x” (e.g. 3.7).
minSessionVersion: for session data saved from this bundle, the oldest version that the bundle currently supports (an integer).
maxSessionVersion: the newest version of this bundle’s session data. Presumably the bundle currently writes this version. The version number should only be increased if the change is not backwards compatible with old readers, because the session-restore code checks these version numbers in order to decide if a session will be able to be restored by the currently installed bundles.
package: Python package name corresponding to bundle
purePython: set to
false
if bundle should be treated as binary, i.e., includes a compiled module; omit otherwiseversion: bundle version
Child elements:
Author (one)
Categories (one)
Classifiers (one)
CModule (zero or more)
DataFiles (zero or more)
Dependencies (zero or more)
Description (one)
ExtraFiles (zero or more)
Email (one)
ExtraFiles (zero or more)
Synopsis (one)
URL (one)
Categories
List of categories where bundle may appear, e.g., in menus
Child elements:
Category (one or more)
Category
Attribute:
name: name of category (see Tools menu in ChimeraX for a list of well-known category names)
CExecutable
Compiled executable in the current bundle
Attribute:
name: name of executable file
Child elements:
CompileArgument (zero or more)
Define (zero or more)
FrameworkDir (zero or more)
IncludeDir (zero or more)
Library (zero or more)
LibraryDir (zero or more)
LinkArgument (zero or more)
Requires (zero or more)
SourceFile (one or more)
Undefine (zero or more)
ChimeraXClassifier
Lines similar to Python classifiers but containing ChimeraX-specific information about the bundle. See ChimeraX Metadata Classifiers below for detailed description of ChimeraX
Element text:
Lines with
::
-separated fields.
Classifiers
Child elements:
ChimeraXClassifier (zero or more)
PythonClassifier (zero or more)
CLibrary
Compile library or shared object in the current bundle
Attribute:
name: name of library or shared object
usesNumpy: whether library requires
numpy
headers. If set totrue
,numpy
header directories (folders) are included on the compilation command.static: whether to build a static (
true
) or dynamic (false
) library
Child elements:
CompileArgument (zero or more)
Define (zero or more)
FrameworkDir (zero or more)
IncludeDir (zero or more)
Library (zero or more)
LibraryDir (zero or more)
LinkArgument (zero or more)
Requires (zero or more)
SourceFile (one or more)
Undefine (zero or more)
CModule
List of compiled modules in the current bundle.
Attribute:
major: major version number for compiled module.
minor: minor version number for compiled module.
name: name of compiled module. This should not include file suffixes, as they vary across platforms. The compiled module will appear as a submodule of the Python package corresponding to the bundle.
usesNumpy: whether module requires
numpy
headers. If set totrue
,numpy
header directories (folders) are included on the compilation command.
Child elements:
CompileArgument (zero or more)
Define (zero or more)
FrameworkDir (zero or more)
IncludeDir (zero or more)
Library (zero or more)
LibraryDir (zero or more)
LinkArgument (zero or more)
Requires (zero or more)
SourceFile (one or more)
Undefine (zero or more)
CompileArgument
Element text
Additional argument to provide to the compiler when compiling.
DataDir
Element text
Data directory name (no wildcard characters) relative to package source. For example, because current package source is expected to be in folder src, a data directory datadir in the same folder is referenced as
datadir
, notsrc/datafile
. All files and subdirectories in the specified directory are included in the bundle.
DataFile
Element text
Data file name (or wildcard pattern) relative to package source. For example, because current package source is expected to be in folder src, a data file datafile in the same folder is referenced as
datafile
, notsrc/datafile
.
Define
Element text
Symbolic name to be defined during compilation. Can just be the symbolic name itself, or the symbolic name plus =value, as needed.
DataFiles
List of data files in package source tree that should be included in bundle
Attribute:
package: name of package that has the extra data files. If omitted, the current bundle package is used.
Child elements:
DataDir (zero or more)
DataFile (zero or more)
Dependencies
List of all ChimeraX bundles and Python packages that the current bundle depends on. For building bundles containing C/C++ source code, include and library directories of bundles in the dependency lists are automatically incorporated in compilation options. (This implies that bundles on the dependency list must alreay be installed.)
Child elements:
Dependency (one or more)
Dependency
Attributes:
name: name of ChimeraX bundle or Python package that current bundle depends on.
version: version of bundle of package that current bundle depends on.
Description
Element text:
Full description of bundle. May be multiple lines.
Email
Element text:
Contact address for bundle maintainer.
ExtraDir
Extra directory in the bundle that is copied from elsewhere in the source tree.
Element text
Directory name (no wildcard characters) relative to package source. For example, because current package source is expected to be in folder src, a directory extradir in the same folder is referenced as
extradir
, notsrc/extradir
. All files and subdirectories in the specified directory are included in the bundle.
Attributes:
source: Directory name relative to bundle source directory. The source directory will be copied into the
src
directory with the directory name given in the element text.
ExtraFile
Element text
Extra file name (or wildcard pattern) relative to package source. For example, because current package source is expected to be in folder src, a data file datafile in the same folder is referenced as
datafile
, notsrc/datafile
.
Attributes:
source: File name relative to bundle source directory. The source file will be copied into the
src
directory with the file name given in the element text.
ExtraFiles
List of extra files in package source tree that should be included in bundle. The extra files, e.g., C++ header files, are copied from elsewhere in the source tree into the
src
directory for inclusion in the bundle. Files listed under ExtraFiles do not need to be listed under DataFiles.Attribute:
package: name of package that has the extra data files. If omitted, the current bundle package is used.
Child elements:
ExtraDir (zero or more)
ExtraFile (zero or more)
Framework
Child element of CModule, applicable only for macOS.
Element text:
Name of a macOS framework required to compile the current module.
FrameworkDir
Child element of CModule.
Element text:
Name of a directory (folder) containing frameworks required to compile the current module.
IncludeDir
Child element of CModule.
Element text:
Name of a directory (folder) containing header files required to compile the current module. Standard C/C++ and ChimeraX header directories are automatically supplied by the build process.
Initializations
List of bundles that must be initialized before this one.
Currently, the supported types of initializations are: manager and custom. Managers across all bundles are initialized first; then custom initialization across all bundles.
Child elements:
InitAfter (one or more)
InitAfter
Attribute:
type: type of initialization. Currently supported values are manager and custom.
bundle: name of bundle that must be initialized before this one.
There should be one InitAfter tag for each bundle that must be initialized first. There is no way to specify the exact initialization order for these bundles; the relative dependencies will be computed from the initialization information of the bundles.
Library
Child element of CModule.
Element text:
Name of a link library required to compile the current module. Standard C/C++ libraries are automatically supplied by the build process. Additional libraries, such as those included in ChimeraX.app, must be listed if used in the compiled module. For example, to use atomic structure functionality, a Library directive for
atomstruct
should be included.
LibraryDir
Child element of CModule.
Element text:
Name of a directory (folder) containing link libraries required to compile the current module. Standard C/C++ and ChimeraX library directories are automatically supplied by the build process.
LinkArgument
Element text
Additional argument to provide to the linker when linking.
Managers
List of managers that bundle provides
Child elements:
Manager (one or more)
Manager
Attribute:
name: name of manager. If autostart is true (see below), the bundle must implement the
init_manager
method. The two positional arguments toinit_manager
are the session instance and the manager name.guiOnly: set to
true
if manager should only be created when the graphical user interface is being used; omit otherwiseautostart: If true, the manager is started during Chimera startup. Defaults to true.
Other attributes listed in the Manager tag are passed as keyword arguments to
init_manager
.init_manager
should create an instance of a subclass ofchimerax.core.toolshed.ProviderManager
. The ProviderManager constructor must be passed the name of the manager. The subclass must implement at least one method:add_provider(bundle_info, provider_name, **kw)
which is called once for each Provider tag whose manager name matches this manager (whether the bundle with the provider is installed or not). To distinguish between installed and uninstalled providers checkbundle_info.installed
. A second method:end_providers()
is optional.end_providers
is called after all calls toadd_provider
have been made and is useful for finishing manager initialization.
Package
Attributes:
name: name of Python package to be added.
folder: folder containing source files in package.
Providers
List of providers that bundle provides
Attribute:
manager: optional default manager for nested Provider elements
Child elements:
Provider (one or more)
Provider
Attribute:
manager: name of the manager with which this provider will be registered. Optional if manager is given in parent Providers element.
name: name of provider.
Other attributes listed in the Provider tag are passed as keyword arguments to the manager’s
add_provider
method.Bundles that supply providers should implement the method:
run_provider(session, provider_name, manager, **kw)
which may be used by the manager to invoke provider functionality.
PythonClassifier
Element text:
Standard Python classifier with
::
-separated fields.
Requires
Child element of CModule.
Element text:
Full path name of a system file that must be present in order to compile the current module.
SourceFile
Child element of CExecutable, CLibrary, or CModule.
Element text:
Name of source file in a compiled module. The path should be relative to bundle_info.xml.
Synopsis
Element text:
One line description of bundle (e.g., as tool tip text)
Undefine
Element text
Symbolic name to be explictly undefined during compilation.
URL
Element text:
URL containing additional information about bundle
ChimeraX Metadata Classifiers¶
ChimeraX gathers metadata from Python-wheel-style classifiers listed in the bundle. The only required classifier is for overall bundle metadata; additional classifiers provide information about tools (graphical interfaces), commands, data formats, and selectors.
Bundle Metadata
Bundle
:: categories :: session_versions :: api_module_name :: supercedes :: custom_init
categories is a comma separated list of category names. (Category names are the names that appear under the
Tools
menu.) This value is currently unused but are intended for constructing “toolboxes” in the future.session_versions is a comma-separated two-tuple of integers, representing the minimum and maximum session versions that this tool can read.
api_module_name is a string with the name of the module that has the bundle_api in it.
supercedes is an optional comma separated list of names that under which the bundle was previously released.
custom_init is a string. If not set to
true
, the bundle is not imported until actually invoked. If set totrue
, thebundle_api.initialize
method for the bundle is called after the main session has been created.For example:
Bundle :: Volume data :: 1,1 ::This classifier is automatically generated when using the
devel
command and bundle_info.xml.
Tool Metadata
Tool
:: tool_name :: categories :: synopsis
tool_name is a string that uniquely identifies the tool.
categories is a comma separated list of category names under which the tool will appear.
synopsis is a 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.
For example:
Tool :: Help Viewer :: General :: Show helpNotes:
Tool instances are created via the
bundle_api.start_tool
method.Bundles may provide more than one tool.
Command Metadata
Command
:: name :: categories :: synopsis
name is a string and may have spaces in it.
categories should be a subset of the bundle’s categories.
synopsis is a 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.
For example:
Command :: exit :: General :: terminate ChimeraXNotes:
Commands are lazily registered, so the argument specification isn’t needed until the command is first used.
Command registration is done via the
bundle_api.register_command
method.Bundles may provide more than one command.
Before deciding on your command name and syntax, you should peruse the command style guide.
- Data Format Metadata
The old
DataFormat
,Open
, andSave
tags have been replaced with a manager/provider mechanism, as described in the Opening/Saving/Fetching Files section below.
Selector Metadata
Selector
:: name :: synopsis
name is a string and may have spaces in it.
synopsis is a 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.
For example:
Selector :: helix :: Helical regions in proteinsNotes:
Bundles may provide more than one selector.
Many commands take optional keywords before atom and object specifiers. If a selector name is the same as the optional keyword, the command will interpret it as the keyword rather than the selector. The bottom line is “choose your selector names carefully.”
Opening/Saving/Fetching Files¶
For a bundle to hook into the open
or save
commands
it must have a Providers section in its bundle_info.xml
to provide the relevant information to the “open command” or
“save command” manager via Provider tags.
The bundle also typically defines the file/data format via a
Provider tag for the “data formats” manager, though in
some cases the data format is defined in another bundle.
As per normal XML, Provider attributes are strings
(e.g. name="Chimera BILD object"
)
and for attributes that can accept multiple values, those
values are comma separated
(e.g. suffixes=".bld,.bild"
).
Defining a File/Data Format¶
To define a data(/file) format, you supply a Provider tag in the
Providers section of your bundle_info.xml file. The value of
the manager
of the tag or section should be “data formats”. The
information supplied by the Provider tag will be all that is
required for the format definition – i.e. the data-formats manager
will never call the BundleAPI
’s
run_provider()
method, so that method does not need to be customized
for this manager.
These are the possible Provider attributes:
Mandatory Attributes
- name
The full official name of the format, typically omitting the word “format” though, since all such names are formats. The name attribute must be unique across all format definitions.
Frequently-Used Attributes
- category
The general kind of information that the format provides, used to organize formats in some interfaces. Commonly used categories are: Generic 3D objects, Molecular structure, Molecular trajectory, Volume data, Image, Higher-order structure, Sequence, and Command script. The default is the catchall category “General”.
- encoding
If the format is textual, the encoding for that text. Binary formats should omit this attribute. The most common encoding for text formats is “utf-8”. If the encoding is declared as “utf-8” and a file reader for the format throws UnicodeDecodeError, then utf-16 and utf-32 will also be tried.
- nicknames
A short, easy-to-type name for the format, typically used in conjunction with the
format
keyword of theopen
/save
commands. Still needs to be verbose enough to not easily conflict with nicknames of other formats. Also typically all lower case. Default is an all-lower-case version of name.- reference_url
If there is a web page describing the format, the URL to that page.
- suffixes
The file-name suffixes (starting with a ‘.’) that are used by files in this format. If no suffixes are specified, then files in this format will only be able to be opened/saved by supplying the
format
keyword to theopen
/save
commands. Also, formats that can only be fetched from the web frequently don’t specify suffixes.- synopsis
The description of the format used by user-interface widgets that list formats (e.g. the Open-File dialog), so typically shorter than name but more verbose than the nicknames. The first word should be capitalized unless that word is mixed case (e.g. mmCIF). Like name, synopsis should typically omit the word “format”. Defaults to name.
Infrequently-Used Attributes
- allow_directory
If this is specified as “true”, then the data for this format can be organized as a folder rather than a single file. Regardless of the value of suffixes, such a folder can only be opened/saved by providing the
format
keyword to the corresponding command. Specifying allow_directory as “true” does not preclude also possibly opening this format from individual files (in which case suffixes would matter). The default is “false”.
- default_for
Declares that this format should be considered the default when opening files with the given suffix(es). Therefore has to be the same as or a subset of the suffixes attribute. This attribute is not normally specified because the file opening/saving machinery will query the user when there is more than one format that corresponds to a particular file suffix, and allow the user to designate a format as the default. It is typically used as a convenience when it seems likely that a large majority of users will intend to open/save one specific format despite there being multiple possibilities. For instance, the main PDB open/save bundle declares PDB format as default for .pdb (but not .ent, etc.) despite SwissDock and ZDOCK formats also using the .pdb suffix. Users having SwissDock/ZDOCK PDB files would have to use the
format
open/save keyword.- insecure
If opening this format’s data could cause arbitrary code to execute, then insecure should be specified as “true”. Formats in the “Command script” category default to “true” and others to “false”.
- mime_types
If the data for this format may be obtained by the user providing an URL to the
open
command, and the URL might not end in one of the suffixes (e.g. it’s a CGI script), but the web server does provide a format-specific Content-Type header for the data, then mime_types lists Content-Type header values that the server or servers could possibly provide. Only relevant to the user providing an URL, not to the “fetching” of database identifiers outlined in the Fetching Files section. If the data format has a Wikipedia page, the “mime type” will frequently be specified there (as “Internet media type”).
For example:
<Providers manager="data formats">
<Provider name="Sybyl Mol2" suffixes=".mol2" nicknames="mol2"
category="Molecular structure" synopsis="Mol2" encoding="utf-8" />
</Providers>
A detailed example of defining a data format can be found in Bundle Example: Read a New File Format.
Opening Files¶
For your bundle to open a file, it needs to provide information to the “open command” manager
about what data format it can open, what arguments it needs, what function to call, etc..
Some of that info is provided as attributes in the Provider tag, but the lion’s share is
provided when the open-command manager calls your bundle’s
run_provider()
method.
That call will only occur when ChimeraX tries to open the kind of data that your Provider
tag says you can open.
To specify that your bundle can open a data format, you supply a Provider tag in the
Providers section of your bundle_info.xml file. The value of
the manager
attribute in the tag or section should be “open command”.
The other possible Provider attributes are:
Mandatory Attributes
- name
The name of the data format you can open. Can also be one of the format’s nicknames instead.
Infrequently-Used Attributes
- batch
If your provider can open multiple files of its format as one combined model, then it should specify batch as “true” and it will be called with a list of path names instead of an open file stream.
- check_path
If the user can type something other than an existing file name, and your provider will expand that into a real file name or names (e.g. there is some kind of substitution the provider does with the text), then specify check_path as “false” (which implies want_path=”true”, you don’t have to explicitly specify that).
- is_default
Obsolete. Use default_for instead. If your data format has suffixes that are the same as another format’s suffixes, is_default will determine which format will be used when the open command’s
format
keyword is omitted. is_default defaults to “true”, so therefore typically lesser known/used formats supply this attribute with a value of “false”.- pregrouped_structures
If a provider returns multiple models, the open command will automatically group them (see
group_multiple_models
attribute, next) so that the entire set of models can be referenced with one model number (the individual models can be referenced with submodel numbers). The provider could pre-group them in order to give the group a name other the default (which is based on the file name; the user can still override that with thename
keyword of the open command). In the specific case where the provider is pre-grouping atomic structures, it should specify pregrouped_structures as “true” so the the open command’s return value can be the actual list of structures rather than a grouping model. This greatly simplifies scripts trying to handle return values from various kinds of structure-opening commands.- group_multiple_models
By default, if a provider returns multiple models they will be grouped for ease of reference in commands. If it is desired that the returned models each be separate top-level models, specify a value of “false” for this attribute.
- type
If you are providing information about opening a file rather than fetching from a database, type should be “open”, and otherwise “fetch”. Since the default value for type is “open”, providers that open files typically skip specifying type.
- want_path
The provider is normally called with an open file stream rather than a file name, which allows ChimeraX to handle compressed files automatically for you. If your file reader must be able to open/read the file itself instead, then specify want_path as “true” and you will receive a file path instead of a stream, and attempting to open a compressed version of your file type will result in an error before your provider is even called.
For example:
<Providers manager="open command">
<Provider name="AutoDock PDBQT" want_path="true" />
<Provider name="Sybyl Mol2" want_path="true" />
</Providers>
The remainder of the information the bundle provides about how to open a file comes from the
return value of the bundle’s
run_provider()
method, which must return
an instance of the
chimerax.open_command.OpenerInfo
class.
The doc strings of that class discuss its methods in detail, but briefly:
You must override the
open()
method to take the input provided and return a (models, status message) tuple.If your format has format-specific keywords that the
open
command should accept, you must override theopen_args()
property to return a dictionary that maps Python keywords of your opener-function to corresponding Annotation subclasses (such classes convert user-typed text into corresponding Python values).
A detailed example for opening a file type can be found in Bundle Example: Read a New File Format.
Saving Files¶
For your bundle to save a file, it needs to provide information to the “save command” manager
about what data format it can save, what arguments it needs, what function to call, etc..
Some of that info is provided as attributes in the Provider tag, but the lion’s share is
provided when the save-command manager calls your bundle’s
run_provider()
method.
That call will only occur when ChimeraX tries to save the kind of data that your Provider
tag says you can save.
To specify that your bundle can save a data format, you supply a Provider tag in the
Providers section of your bundle_info.xml file. The value of
the manager
attribute in the tag or section should be “save command”.
The other possible Provider attributes are:
Mandatory Attributes
- name
The name of the data format you can save. Can also be one of the format’s nicknames instead.
Infrequently-Used Attributes
- compression_okay
compression_okay controls whether your format will be able to save directly as a compressed file as implied by the user adding an additional compression suffix (e.g. “.gz”) to your file name. There are two main reasons that you would change compression_okay from its default value of “true” to “false”:
1. For whatever reason your bundle cannot use
open_output()
to open the file, which is the routine that handles the automatic compression. This frequently happens for bundles where compiled code opens the file and cannot handle being passed a Python stream.2. If the data you are writing out is already compressed and therefore it would probably be bad to compress it again (likely slower with no space savings).
- is_default
Obsolete. Use default_for instead. If your data format has suffixes that are the same as another format’s suffixes, is_default will determine which format will be used when the save command’s
format
keyword is omitted. is_default defaults to “true”, so therefore typically lesser known/used formats supply this attribute with a value of “false”. For example, ChimeraX can save both image TIFF files and ImageJ TIFF stacks, which both use the suffixes .tif and .tiff. The ImageJ TIFF stack usesis_default="false"
so that the commandsave image.tif
produces the more commonly desired image file. To get an ImageJ stack, the user would have to addformat imagej
to the save command .
For example:
<Providers manager="save command">
<Provider name="Sybyl Mol2" />
</Providers>
The remainder of the information the bundle provides about how to save a file comes from the
return value of the bundle’s
run_provider()
method, which must return
an instance of the
chimerax.save_command.SaverInfo
class.
The doc strings of that class discuss its methods in detail, but briefly:
You must override the
save()
method to take the input provided and save the file.If your format has format-specific keywords that the
save
command should accept, you must override thesave_args()
property to return a dictionary that maps Python keywords of your saver-function to corresponding Annotation subclasses (such classes convert user-typed text into corresponding Python values).If you have format-specific options and wish to show a user interface to some or all of those options in the ChimeraX Save dialog, you must override the
save_args_widget()
method and return a widget containing your interface (typically a subclass of QFrame). Conversely, you must also overridesave_args_string_from_widget()
that takes your widget and returns a string containing the corresponding options and values that could be added to asave
command.
A detailed example for saving a file type can be found in Bundle Example: Save a New File Format.
Fetching Files¶
For your bundle to fetch a file from a web database, it needs to provide information to the
“open command” manager about what data format it can open, what arguments it needs,
what function to call, etc..
Some of that info is provided as attributes in the Provider tag, but the lion’s share is
provided when the open-command manager calls your bundle’s
run_provider()
method.
That call will only occur when ChimeraX tries to fetch the kind of data that your Provider
tag says you can fetch.
To specify that your bundle can fetch from a database, you supply a Provider tag in the
Providers section of your bundle_info.xml file. The value of
the manager
attribute in the tag or section should be “open command”.
The other possible Provider attributes are:
Mandatory Attributes
- format_name
The name of the data format for the data that is fetched. Can also be one of the format’s nicknames instead.
- name
The name of the database that the data is fetched from, typically an easily typed lowercase string, since this name will be used directly in the
open
command as either the value for thefromDatabase
keyword or as the prefix in the from_database:identifier form of fetch arguments. So “pdb” is better then “Protein Databank”. Note that single-character database names are disallowed to avoid confusion with Windows single-character drive names.- type
type should be “fetch” to indicate that your bundle fetches data from the web (as opposed to opening local files). The default is “open”.
Frequently-Used Attributes
- synopsis
The description of the fetcher used by user-interface widgets that list fetchers (such as the Fetch By ID dialog), so typically somewhat more verbose than name. Words should be capitalized unless that word is mixed case (e.g. mmCIF). Omitting synopsis means that the fetcher will not be listed in user-interface widgets. The ‘;’ character can be used to separate lines of a multi-line description.
- example_ids
A list of one or more valid example identifiers for your database. For use in graphical user interfaces (see synopsis attribute). The ‘;’ character can be used to separate multiple example IDs.
Infrequently-Used Attributes
- is_default
If a database can be fetched from using different data formats, the one that should be used when the user omits the
format
keyword should have is_default as “true”, and the others should have it as “false”. is_default defaults to “true”, so since most databases only have one format this attribute is in most cases omitted.- pregrouped_structures
If a provider returns multiple models, the open command will automatically group them (see
group_multiple_models
attribute, next) so that the entire set of models can be referenced with one model number (the individual models can be referenced with submodel numbers). The provider could pre-group them in order to give the group a name other the default (which is based on the database entry ID; the user can still override that with thename
keyword of the open command). In the specific case where the provider is pre-grouping atomic structures, it should specify pregrouped_structures as “true” so the the open command’s return value can be the actual list of structures rather than a grouping model. This greatly simplifies scripts trying to handle return values from various kinds of structure-opening commands.- group_multiple_models
By default, if a provider returns multiple models they will be grouped for ease of reference in commands. If it is desired that the returned models each be separate top-level models, specify a value of “false” for this attribute.
For example:
<Providers manager="open command">
<Provider name="pubchem" type="fetch" format_name="sdf" synopsis="PubChem" example_ids="12123" />
</Providers>
The remainder of the information the bundle provides about how to fetch from a database comes
from the return value of the bundle’s
run_provider()
method, which must return
an instance of the
chimerax.open_command.FetcherInfo
class.
The doc strings of that class discuss its methods in detail, but briefly:
You must override the
fetch()
method to take the input provided and return a (models, status message) tuple.If your format has database-specific keywords that the
open
command should accept, you must override thefetch_args()
property to return a dictionary that maps Python keywords of your fetcher-function to corresponding Annotation subclasses (such classes convert user-typed text into corresponding Python values).If the data format being fetched can also be opened directly from a file (i.e. there’s an “open command” Provider with type=”open”), then
fetch_args()
should only return keywords applicable just to fetching. The “opening” keywords will be automatically combined with those.
A detailed example for saving a file type can be found in Bundle Example: Fetch from Network Database.
Defining Presets¶
For a bundle to define new presets,
it must have a Providers section in its bundle_info.xml
to provide the relevant information to the “presets” manager via one or more Provider tags.
The Provider tags are nested within the Providers section.
If your bundle only offers Provider tags for the “presets” manager, then you can put
the manager="presets"
attribute in your Providers tag and that will apply to all the Provider tags
within the Providers section. If your bundle offers Provider tags for multiple managers,
then you can either specify the manager within each Provider tag, or you can have
multiple Providers sections, each with their own manager
attribute.
As per normal XML, Provider and Providers attributes are strings
(e.g. name="sticks"
). Aside from “manager”, the other possible Provider tags are:
Mandatory Attributes
- name
The name of the preset as shown in the Presets menu and as used by the
preset
command. Case does not matter.
Frequently-Used Attributes
- category
The category that the preset should be grouped into, as shown in the Presets menu and as used in the
preset
command. Case does not matter. Default is “General”.- order
Controls the placement of the preset within its category in the Presets menu. Must be an integer (e.g.
order="1"
). Default is to arrange presets in alphabetical order.
For example:
<Providers manager="presets">
<Provider category="fun looks" name="shiny balls" />
<Provider category="fun looks" name="thin sticks" />
</Providers>
When the execution of a preset from your bundle is requested, the preset manager will run the
run_provider()
method (with name
and mgr
arguments),
which should in turn execute the named preset.
So that the appropriate information about the preset gets logged,
your code implementing the preset should call mgr.execute(info)
where info
is
either a function that takes no arguments (if your preset is implemented in Python) or a list of commands.