– storage for sessions

This module contains storage support code for handling sessions. Using the SessionStorageRepository one can enumerate sessions at a particular location. Each location is wrapped by a SessionStorage instance. That latter class be used to create (allocate) and remove all of the files associated with a particular session.


Bases: OSError

Exception raised when SessionStorage.save_checkpoint() finds an existing ‘next’ file from a (presumably) previous call to save_checkpoint() that got interrupted


POSIX exception code


exception filename


second exception filename


exception strerror


Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.


Bases: object

Abstraction for storage area that is used by SessionState to keep some persistent and volatile data.

This class implements functions performing input/output operations on session checkpoint data. The location property can be used for keeping any additional files or directories but keep in mind that they will be removed by SessionStorage.remove()

This class indirectly collaborates with SessionSuspendHelper and SessionResumeHelper.


Forcibly unlock the storage by removing a file created during atomic filesystem operations of save_checkpoint().

This method might be useful if save_checkpoint() raises LockedStorageError. It removes the “next” file that is used for atomic rename.

classmethod create(base_dir, prefix='pbox-')[source]

Create a new SessionStorage in a random subdirectory of the specified base directory. The base directory is also created if necessary.

  • base_dir – Directory in which a random session directory will be created. Typically the base directory should be obtained from SessionStorageRepository.get_default_location()
  • prefix – String which should prefix all session filenames. The prefix is sluggified before use.

identifier of the session storage (name of the random directory)


Load checkpoint data from the filesystem

Returns:data from the most recent checkpoint
Return type:bytes
Raises:IOError, OSError – on various problems related to accessing the filesystem

location of the session storage


Remove all filesystem entries associated with this instance.


Save checkpoint data to the filesystem.

The directory associated with this SessionStorage must already exist. Typically the instance should be obtained by calling SessionStorage.create() which will ensure that this is already the case.

  • TypeError – if data is not a bytes object.
  • LockedStorageError – if leftovers from previous save_checkpoint() have been detected. Normally those should never be here but in certain cases that is possible. Callers might want to call break_lock() to resolve the problem and try again.
  • IOError, OSError – on various problems related to accessing the filesystem. Typically permission errors may be reported here.

pathname of the session state file


Bases: object

Helper class to enumerate filesystem artefacts of current or past Sessions

This class collaborates with SessionStorage. The basic use-case is to open a well-known location and enumerate all the sessions that are stored there. This allows to create SessionStorage instances to further manage each session (such as remove them by calling :meth:SessionStorage.remove()`)

classmethod get_default_location()[source]

Get the default location of the session state repository

The default location is defined by $PLAINBOX_SESSION_REPOSITORY which must be a writable directory (created if needed) where plainbox will keep its session data. The default location, if the environment variable is not provided, is ${XDG_CACHE_HOME:-$HOME/.cache}/plainbox/sessions


Enumerate stored sessions in the repository.

If the repository directory is not present then an empty list is returned.

Returns:list of SessionStorage representing discovered sessions sorted by their age (youngest first)

pathname of the repository

comments powered by Disqus