session: Application session support¶
A session provides access to most of the application’s state. At a minimum, it does not include the operating system state, like the current directory, nor the environment, nor any Python interpreter state – e.g., the exception hook, module globals, etc.
Code should be designed to support multiple sessions per process since it is easier to start with that assumption rather than add it later. Possible uses of multiple sessions include: one session per tabbed graphics window, or for comparing two sessions.
Session data, ie., data that is archived, uses the
- SESSION_SUFFIX = '.cxs'¶
session file suffix
- class Session(app_name, *, debug=False, silent=False, minimal=False, offscreen_rendering=False)¶
Supported API. Session management
The metadata attribute should be a dictionary with information about the session, e.g., a thumbnail, a description, the author, etc. See
Attributes that support the
StateManagerAPI are automatically added as state managers (e.g. the session’s add_state_manager method is called with the ‘tag’ argument the same as the attribute name). Conversely, deleting the attribute will call remove_state_manager. If a session attribute is not desired, the add/remove_state_manager methods can be called directly.
An instance of
Experimental API . For session saving objects that do not have a State base class. Methods is a dictionary matching the class to be saved in sessions to another class with static methods take_snapshot(instance, session, flags) and restore_snapshot(session, data).
- restore(stream, path=None, resize_window=None, restore_camera=True, clear_log=True, metadata_only=False)¶
Experimental API . Deserialize session from binary stream.
- snapshot_methods(obj, instance=True, base_type=<class 'chimerax.core.state.State'>)¶
Experimental API . Return an object having take_snapshot(), restore_snapshot(), and reset_state() methods for the given object. Can return None if no save/restore methods are available, for instance for primitive types.
- class UserAliases¶
- 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.
- save(session, path, version=3, compress='lz4', include_maps=False)¶
Experimental API . Command line version of saving a session.
Option compress can be lz4 (default), gzip, or None. Tests saving 3j3z show lz4 is as fast as uncompressed and 4x smaller file size, and gzip is 2.5 times slower with 7x smaller file size.
- sdump(session, session_file, output=None)¶
Experimental API . dump contents of session for debugging
Experimental API . Fill in standard metadata for created files
previous_metadata – dict Optional dictionary of previous metadata.
The standard metadata consists of:
generator – Application that created file in HTML User Agent format (app name version (os))
created – Date first created
modified – Date last modified after being created
creator – User name(s)
dateCopyrighted – Copyright(s)
creator and dateCopyrighted can be lists if there is previous metadata with different values.
Dates are in ISO 8601 UTC time. Also see <http://www.w3.org/TR/NOTE-datetime>.
Metadata names are inspired by the HTML5 metadata, https://www.w3.org/TR/html5/document-metadata.html.