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 theopen()
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 thefetch()
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 [typicallysession.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:
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.
- 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 callingsession.models.add(models)
.
- property open_data_formats¶
The data formats for which an opener function has been registered.