:mod:`dip.settings`
===================
.. module:: dip.settings

The :mod:`dip.settings` module implements the infrastructure for
application specific persistent storage typically used for user settings.


:class:`ISettings`
------------------
.. class:: ISettings

    Base class: :class:`~dip.model.Interface`

    The ISettings class defines the interface that should be implemented by
    an object, often a view, that reads and writes user settings.

    .. attribute:: id = Str()

        The identifier of the setting.

    .. method:: ISettings.restore(settings_manager)

        Restore the settings obtained from a settings manager.
        
        :param settings_manager:
            is the settings manager.

    .. method:: ISettings.save(settings_manager)

        Save the settings to a settings manager.
        
        :param settings_manager:
            is the settings manager.


:class:`ISettingsManager`
-------------------------
.. class:: ISettingsManager

    Base class: :class:`~dip.model.Interface`

    The ISettingsManager interface defines the API of a settings manager.
        

    .. method:: ISettingsManager.load(organization, application=None)

        Load the application's settings.
        
        :param organization:
            is the name of the organization.  It is recommended that this is a
            FQDN.
        :param application:
            is the name of the application.  It will default to the base name
            of sys.argv[0] with any extension removed.

    .. method:: ISettingsManager.read_value(name)

        Read the value of a setting.
        
        :param name:
            is the name of the setting.
        :return:
            the value of the setting, or None if there is no such setting.

    .. method:: ISettingsManager.restore(models)

        Restore the settings for a sequence of models.  If no settings have
        been loaded, i.e. :meth:`~dip.settings.ISettingsManager.load` has not
        been called, then this has no effect.
        
        :param models:
            is the sequence of models.  Any model that does not implement
            :class:`~dip.settings.ISettings` is ignored.

    .. method:: ISettingsManager.save(models)

        Save the settings for a sequence of models.  If no settings have
        been loaded, i.e. :meth:`~dip.settings.ISettingsManager.load` has not
        been called, then this has no effect.
        
        :param models:
            is the sequence of models.  Any model that does not implement
            :class:`~dip.settings.ISettings` is ignored.

    .. method:: ISettingsManager.write_value(name, value)

        Write the value of a setting.
        
        :param name:
            is the name of the setting.
        :param value:
            is the value of the setting.  If this is None then the setting is
            removed.


:class:`ISettingsStorage`
-------------------------
.. class:: ISettingsStorage

    Base class: :class:`~dip.model.Interface`

    The ISettingsStorage class defines the interface that should be
    implemented by storage used to hold settings.

    .. method:: ISettingsStorage.begin_group(group)

        Begin a group.
        
        :param group:
            is the name of the group.

    .. method:: ISettingsStorage.end_group()

        End the current group. 

    .. method:: ISettingsStorage.flush()

        Ensure that all settings changes are written to persistent storage.
                

    .. method:: ISettingsStorage.read_value(name)

        Read the value of a setting.
        
        :param name:
            is the name of the setting.
        :return:
            the value of the setting, or None if there is no such setting.

    .. method:: ISettingsStorage.write_value(name, value)

        Write the value of a setting.
        
        :param name:
            is the name of the setting.
        :param value:
            is the value of the setting.  If this is None then the setting is
            removed.


:class:`SettingsManager`
------------------------
.. class:: SettingsManager

    Base class: :class:`~dip.model.Singleton`

    The SettingsManager class is a singleton that provides access to a
    default settings manager.

    .. attribute:: instance = Instance(ISettingsManager)

        The settings manager instance.