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 State API.


session file suffix

class Session(app_name, *, debug=False, silent=False, minimal=False)

Bases: object

Session management

The metadata attribute should be a dictionary with information about the session, e.g., a thumbnail, a description, the author, etc. See standard_metadata().

Attributes that support the State API 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.


logger (An instance of Logger) Use to log information, warning, errors.
metadata (dict) Information kept at beginning of session file, eg., a thumbnail
models (Instance of Models.)
triggers (An instance of TriggerSet) Starts with session triggers.
metadata = None

session metadata


Reset session to data-less state

restore(stream, metadata_only=False)

Deserialize session from binary stream.

save(stream, version)

Serialize session to binary stream.

snapshot_methods(object, instance=True)

Return an object having take_snapshot() and restore_snapshot() methods for the given object. Can return if no save/restore methods are available, for instance for primitive types.


Initialize session with common data containers

save(session, path, version=3, uncompressed=False)

command line version of saving a session

sdump(session, session_file, output=None)

dump contents of session for debugging


Fill in standard metadata for created files


previous_metadata : dict

Optional dictionary of previous metadata.

The standard metadata consists of: