save_command: Register file saving

class SaverInfo

Bundles that can save files must implement a subclass of this class, and return it as the value of the bundle’s run_provider() method. The subclass must override the save() method of this class.

property hidden_args

Return a list of Python keyword argument names that should not be shown in the command’s “usage” information. Sometimes used to hide debugging or obsolete options.

property in_file_history

Set this to False in the rare case that the file should not appear in the file history. Note that saved files that ChimeraX does not know how to open are automatically excluded from the file history, so only files that are in a format that ChimeraX knows how to open but that would not be appropriate to open need to be excluded by setting this to False.

save(session, path, **kw)

Experimental API . Save a file to the given file-system path.

The ‘kw’ dictionary will contain keywords specific to your type of save function. Their names and types are specified by the save_args() property.

property save_args

Return a dictionary that maps Python keywords used by your save() function to corresponding Annotation subclasses. Annotations are used to convert command-line text typed by the user into appropriate Python values, e.g. BoolArg would convert ‘t’ to True. Some bundles also provide relevant Annotations, e.g. chimerax.atomic.AtomsArg.

If your bundle includes a “models” keyword in the returned dictionary, it is handled specially in that the user can not only specify it normally in the save command (e.g. save out.pdb models #1) but as a convenience it can instead be specified as the second positional argument (e.g. save out.pdb #1).

save_args_string_from_widget(widget)

Experimental API . This method must be overidden if the save_args_widget() method returns a widget (rather than None). Given that widget, this method should return the corresponding arguments string to add to the save command. The string should only include the text for the arguments. The entire command text, including “save”, filename, format, etc. will be generated by the calling function.

The conversion of a Python value to a string can be accomplished by using the corresponding Annotation’s unparse() method. This will handle things like putting quotes around a space-containg string, generating a text representation of a color, etc., and generally avoids you having to re-invent the wheel.

If your bundle does not implement save_args_widget() (i.e. that method returns None), then you do not need to implement this method either.

save_args_widget(session)

Experimental API . Return a Qt widget that can be displayed in ChimeraX’s Save dialog to provide control over options generated for the resulting save command. This is frequently a subclass of QFrame. Not all possible option need be provided for by the widget – infrequently used or obscure options are often omitted (the command version of save can still be used to get to those options). The argument string corresponding to the final widget settings is generated by the save_args_string_from_widget() method.

If this method returns None, then no options will be displayed for this format.

class SaveManager(session, name)

Manager for save command

add_provider(bundle_info, format_name, compression_okay=True, is_default=True, **kw)

Experimental API . Callback invoked to add provider to this manager.

Parameters
end_providers()

Experimental API . Callback invoked after all providers have been added.

save_data(path, **kw)

Experimental API . Given a file path and possibly format-specific keywords, save a data file based on the current session.

The format name can be provided with the ‘format’ keyword if the filename suffix of the path does not correspond to those for the desired format.

property save_data_formats

The names of data formats for which an saver function has been registered.