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. This function is intended to be used as a context manager. For example::.
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._CONFIG_ID = 'fslpy'

The default configuration identifier, used as the directory name for storing configuration files.

fsl.utils.settings.set(settings)

Set the module-level Settings instance.

fsl.utils.settings.initialise(*args, **kwargs)

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)

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

fsl.utils.settings.read(name, default=None)

fsl.utils.settings.write(*args, **kwargs)

fsl.utils.settings.delete(*args, **kwargs)

fsl.utils.settings.readFile(*args, **kwargs)

fsl.utils.settings.writeFile(*args, **kwargs)

fsl.utils.settings.deleteFile(*args, **kwargs)

fsl.utils.settings.filePath(*args, **kwargs)

fsl.utils.settings.readAll(*args, **kwarg)

fsl.utils.settings.listFiles(*args, **kwarg)

fsl.utils.settings.clear(*args, **kwarg)

class fsl.utils.settings.Settings(cfgid='fslpy', cfgdir=None, writeOnExit=True)

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).

__init__(cfgid='fslpy', cfgdir=None, writeOnExit=True)

Create a Settings instance.

Parameters:

• cfgid – Configuration ID, used as the name of the configuration directory.

• cfgdir – Store configuration settings in this directory, instead of the default.

• writeOnExit – If True (the default), an atexit function is registered, which calls writeConfigFile().

property configID

Returns the configuration identifier.

property configDir

Returns the location of the configuration directory.

read(name, default=None)

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

write(name, value)

Writes the given value to the given file path.

delete(name)

Delete the setting with the given name.

readFile(path, mode='t')

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')

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)

Deletes the given file path.

filePath(path)

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)

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

listFiles(pattern=None)

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()

Delete all configuration settings and files.

__fixPath(path)

Ensures that the given path (passed into readFile(), writeFile(), or deleteFile()) is cross-platform compatible. Only works for paths which use '/' as the path separator.

__getConfigDir(cid)

Returns a directory in which configuration files can be stored.

Note

If, for whatever reason, a configuration directory could not be located or created, a temporary directory will be used. This means that all settings read during this session will be lost on exit.

__readConfigFile()

Called by __init__(). Reads any settings that were stored in a file, and returns them in a dictionary.

__dict__ = mappingproxy({'__module__': 'fsl.utils.settings', '__doc__': 'The ``Settings`` class contains all of the logic provided by the\n    ``settings`` module.  It is not meant to be instantiated directly\n    (although you may do so if you wish).\n    ', '__init__': <function Settings.__init__>, 'configID': <property object>, 'configDir': <property object>, 'read': <function Settings.read>, 'write': <function Settings.write>, 'delete': <function Settings.delete>, 'readFile': <function Settings.readFile>, 'writeFile': <function Settings.writeFile>, 'deleteFile': <function Settings.deleteFile>, 'filePath': <function Settings.filePath>, 'readAll': <function Settings.readAll>, 'listFiles': <function Settings.listFiles>, 'clear': <function Settings.clear>, '_Settings__fixPath': <function Settings.__fixPath>, '_Settings__getConfigDir': <function Settings.__getConfigDir>, '_Settings__readConfigFile': <function Settings.__readConfigFile>, 'writeConfigFile': <function Settings.writeConfigFile>, '__dict__': <attribute '__dict__' of 'Settings' objects>, '__weakref__': <attribute '__weakref__' of 'Settings' objects>, '__annotations__': {}})

__module__ = 'fsl.utils.settings'

__weakref__

list of weak references to the object (if defined)

writeConfigFile()

Writes all settings to a file.