fsl.utils.settings

This module provides functions for storing and retrieving persistent configuration settings and data files.

The initialise() function must be called to initialise the module. Then, the following functions can be called at the module-level:

Settings.read

Reads a setting with the given name, return default if there is no setting called name.

Settings.write

Writes the given value to the given file path.

Settings.delete

Delete the setting with the given name.

Settings.readFile

Reads and returns the contents of the given file path.

Settings.writeFile

Write to the given file path.

Settings.deleteFile

Deletes the given file path.

Settings.filePath

Converts the given path to an absolute path.

Settings.readAll

Returns all settings with names that match the given glob-style pattern.

Settings.listFiles

Returns a list of all stored settings files which match the given glob-style pattern.

Settings.clear

Delete all configuration settings and files.

Some functions are also available to replace the module-level Settings instance:

set

Set the module-level Settings instance.

use

Temporarily replace the module-level Settings object with the given one.

These functions will have no effect before initialise() is called.

Two types of configuration data are available:

  • Key-value pairs - access these via the read, write and delete functions. These are stored in a single file, via pickle. Anything that can be pickled can be stored.

  • Separate files, either text or binary. Access these via the readFile, writeFile, and deleteFile functions.

Both of the above data types will be stored in a configuration directory. The location of this directory differs from platform to platform, but is likely to be either ~/.fslpy/ or ~/.config/fslpy/.

fsl.utils.settings.set(settings)[source]

Set the module-level Settings instance.

fsl.utils.settings.initialise(*args, **kwargs)[source]

Initialise the settings module. This function creates a Settings instance, and enables the module-level functions. All settings are passed through to Settings.__init__().

fsl.utils.settings.use(settings)[source]

Temporarily replace the module-level Settings object with the given one.

fsl.utils.settings.read(name, default=None)[source]
fsl.utils.settings.write(*args, **kwargs)[source]
fsl.utils.settings.delete(*args, **kwargs)[source]
fsl.utils.settings.readFile(*args, **kwargs)[source]
fsl.utils.settings.writeFile(*args, **kwargs)[source]
fsl.utils.settings.deleteFile(*args, **kwargs)[source]
fsl.utils.settings.filePath(*args, **kwargs)[source]
fsl.utils.settings.readAll(*args, **kwarg)[source]
fsl.utils.settings.listFiles(*args, **kwarg)[source]
fsl.utils.settings.clear(*args, **kwarg)[source]
class fsl.utils.settings.Settings(cfgid='fslpy', cfgdir=None, writeOnExit=True)[source]

Bases: object

The Settings class contains all of the logic provided by the settings module. It is not meant to be instantiated directly (although you may do so if you wish).

property configID

Returns the configuration identifier.

property configDir

Returns the location of the configuration directory.

read(name, default=None)[source]

Reads a setting with the given name, return default if there is no setting called name.

write(name, value)[source]

Writes the given value to the given file path.

delete(name)[source]

Delete the setting with the given name.

readFile(path, mode='t')[source]

Reads and returns the contents of the given file path. Returns None if the path does not exist.

Parameters

mode't' for text mode, or 'b' for binary.

writeFile(path, mode='t')[source]

Write to the given file path. This function is intended to be used as a context manager. For example:

with settings.writeFile('mydata.txt') as f:
    f.write('data\n')

An alternate method of writing to a file is via filePath(), e.g.:

fname = settings.filePath('mydata.txt')
with open(fname, 'wt') as f:
    f.write('data\n')

However using writeFile has the advantage that any intermediate directories will be created if they don’t already exist.

deleteFile(path)[source]

Deletes the given file path.

filePath(path)[source]

Converts the given path to an absolute path. Note that there is no guarantee that the returned file path (or its containing directory) exists.

readAll(pattern=None)[source]

Returns all settings with names that match the given glob-style pattern.

listFiles(pattern=None)[source]

Returns a list of all stored settings files which match the given glob-style pattern. If a pattern is not given, all files are returned.

clear()[source]

Delete all configuration settings and files.

writeConfigFile()[source]

Writes all settings to a file.