open_command: Register file openers and database fetch

class OpenerInfo

Bundles that can open 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 open() method of this class.

property in_file_history

Set this to False in the rare case that the file should not appear in the file history

open(session, data, file_name, **kw)

Experimental API . Return a (models, status message) tuple based on the input data. Data will be an opened stream unless the want_path="true" attribute was specified in this provider’s <Provider> tag, in which case it will be a path name instead. The file_name arg can be used in either case in error/status messages to identify the input source.

The kw dictionary will contain keywords specific to your type of open function. Their names and types are specified by the open_args() property below.

The returned models should not be added to the session by this function; that will occur later. The status message typically gives information about the models (e.g. a structure could report the number of atoms and bonds).

property open_args

Return a dictionary that maps Python keywords used by your open() 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.

class FetcherInfo

Bundles that can fetch 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 fetch() method of this class.

fetch(session, ident, format_name, ignore_cache, **kw)

Experimental API . Return a (models, status message) tuple based on the given ident and, if relevant, format_name. The ignore_cache argument is rarely used directly, but may be handed off to pertinent fetching utility functions (e.g. chimerax.core.fetch.fetch_file()).

The kw dictionary will contain keywords specific to your type of fetch function. Their names and types are specified by the fetch_args() method. The kw dictionary may also contain keywords specific to the function that opens the fetched file, so your underlying fetching function should allow for that and pass unrecognized keywords on to the function used to actually open the file [typically session.open_command.open_data().]

The returned models should not be added to the session by this function, that will occur later. The status message typically gives information about the models (as returned by the functon that opened the file) and/or info about the fetching.

property fetch_args

Return a dictionary that maps Python keywords used by your fetch() 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.

Note that if the data format supports both fetching and directly opening from the file system (i.e. there is an “open command” <Provider> whose type is “open”), then the keywords supported by direct opening will be combined with the keywords from this method, so in that case this method should only return keywords specific to the fetching itself.

property in_file_history

Set this to False in the rare case that the file should not appear in the file history.

class OpenManager(session, name)

Manager for open command

add_provider(bundle_info, name, *, type='open', want_path=False, check_path=True, batch=False, format_name=None, is_default=True, synopsis=None, example_ids=None, pregrouped_structures=False, group_multiple_models=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.

open_data(path, *, in_file_history=False, **kw)

Experimental API . Given a file path and possibly format-specific keywords, return a (models, status message) tuple. The models will not have been opened in the 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.

Since open_data() cannot know if you intend to add the returned models to the session later, by default it does not put them in the file history. If you do intend to add them to the session and want them in the file history then specify in_file_history=True.

The fact that the models have not been opened in the session can be an advantage if the models are essentially temporary or if you need to make modifications to the models before adding them to the session. In the former case, you will have to explicitly destroy the models after you are done with them by calling their destroy() method. You add models to a session by calling session.models.add(models).

property open_data_formats

The data formats for which an opener function has been registered.