– 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, legacy_mode=False, 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()
  • legacy_mode – If False (defaults to True) then the caller is expected to handle multiple sessions by itself.
  • prefix – String which should prefix all session filenames. The prefix is sluggified before use.


Legacy mode is where applications using PlainBox API can only handle one session. Creating another session replaces whatever was stored before. In non-legacy mode applications can enumerate sessions, create arbitrary number of sessions at the same time and remove sessions once they are no longer necessary.

Legacy mode is implemented with a symbolic link called ‘last-session’ that keeps track of the last session created using legacy_mode=True. When a new legacy-mode session is created the target of that symlink is read and recursively removed.


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


Load checkpoint data from the filesystem


data from the most recent checkpoint

Return type:


  • IOError, OSError – on various problems related to accessing the filesystem
  • NotImplementedError – when openat(2) is not available on this platform. Should never happen on Linux or Windows where appropriate checks divert to a correct implementation that is not using them.

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.
  • NotImplementedError – when openat(2), renameat(2), unlinkat(2) are not available on this platform. Should never happen on Linux or Windows where appropriate checks divert to a correct implementation that is not using them.

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


Find the last session storage object created in this repository.

Returns:SessionStorage object associated with the last session created in this repository using legacy mode.


This will only return storage objects that were created using legacy mode. Nonlegacy storage objects will not be returned this way.


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