maestral.config.user
====================

.. py:module:: maestral.config.user

.. autoapi-nested-parse::

   This module provides user configuration file management and is mostly copied from the
   config module of the Spyder IDE.







Module Contents
---------------

.. py:data:: logger

.. py:class:: NoDefault

.. py:class:: DefaultsConfig(path)

   Bases: :py:obj:`configparser.ConfigParser`


   Class used to save defaults to a file and as base class for UserConfig.


   .. py:method:: save()

      Save config into the associated file.



   .. py:property:: config_path
      :type: str

      The ini file where this configuration is stored.


.. py:class:: UserConfig(path, defaults = None, load = True, version = Version('0.0.0'), backup = False, remove_obsolete = False)

   Bases: :py:obj:`DefaultsConfig`


   UserConfig class, based on ConfigParser. This class is safe to use from different
   threads but must not be used from different processes!

   :param path: Configuration file will be saved to this path.
   :param defaults: Dictionary containing options.
   :param version: Version of the configuration file.
   :param backup: Whether to create a backup on version changes and on initial setup.
   :param remove_obsolete: If `True`, values that were removed from the configuration
       on version change, are removed from the saved configuration file.

   .. note:: The ``get`` and ``set`` arguments number and type differ from the
       reimplemented methods.


   .. py:attribute:: DEFAULT_SECTION_NAME
      :value: 'main'



   .. py:attribute:: default_config


   .. py:method:: remove_deprecated_options(save = True)

      Remove options which are present in the file but not in defaults.



   .. py:method:: backup_path_for_version(version)

      Get backup location based on version.

      :param version: The version of the backup, if any.
      :returns: The back for the backup file.



   .. py:method:: apply_configuration_patches(old_version)

      Apply any patch to configuration values on version changes.

      To be reimplemented if patches to configuration values are needed.

      :param old_version: Old config version to patch.



   .. py:method:: get_version()

      Get the current config version.

      :returns: Configuration (not application!) version.



   .. py:method:: set_version(version, save = True)

      Set configuration (not application!) version.

      :param version: New version to set.
      :param save: Whether to save changes to drive.



   .. py:method:: reset_to_defaults(section = None, save = True)

      Reset config to default values.

      :param section: The section to reset. If not given, reset all sections.
      :param save: Whether to save the changes to the drive.



   .. py:method:: get_default(section, option)

      Get default value for a given ``section`` and ``option``.

      This is useful for type checking in `get` method.

      :param section: Section to search for option.
      :param option: Config option.
      :returns: Config value or None if section / option do not exist.



   .. py:method:: get(section, option, default = NoDefault)

      Get an option.

      :param section: Config section to search in.
      :param option: Config option to get.
      :param default: Default value to fall back to if not present.
      :returns: Config value.
      :raises cp.NoSectionError: if the section does not exist.
      :raises cp.NoOptionError: if the option does not exist and no default is given.



   .. py:method:: set_default(section, option, default_value)

      Set Default value for a given `section`, `option`.

      If the section or option does not exist, it will be created.



   .. py:method:: set(section, option, value, save = True)

      Set an ``option` on a given ``section``.

      If section is None, the ``option`` is added to the default section.

      :param section: Config section to search in.
      :param option: Config option to set.
      :param value: Config value.
      :param save: Whether to save the changes to the drive.



   .. py:method:: remove_section(section, save = True)

      Remove ``section`` and all options within it.

      :param section: Section to remove from the config file.
      :param save: Whether to save the changes to the drive.
      :returns: Whether the section was removed successfully.



   .. py:method:: remove_option(section, option, save = True)

      Remove ``option`` from ``section``.

      :param section: Section to look for the option.
      :param option: Option to remove from the config file.
      :param save: Whether to save the changes to the drive.
      :returns: Whether the section was removed successfully.



   .. py:method:: cleanup()

      Remove files associated with config and reset to defaults.



.. py:class:: PersistentMutableSet(conf, section, option)

   Bases: :py:obj:`MutableSet`\ [\ :py:obj:`_T`\ ]


   Wraps a list in our state file as a Mapping

   :param conf: UserConfig instance to store the set.
   :param section: Section name in state file.
   :param option: Option name in state file.


   .. py:attribute:: section


   .. py:attribute:: option


   .. py:method:: add(entry)

      Add an element.



   .. py:method:: discard(entry)

      Remove an element.  Do not raise an exception if absent.



   .. py:method:: update(*others)


   .. py:method:: difference_update(*others)


   .. py:method:: clear()

      Clears all elements.