mixins.py

# -*- coding: utf-8 -*-
#
# Copyright © Spyder Project Contributors
# Licensed under the terms of the MIT License
# (see spyder/__init__.py for details)

"""
Spyder API helper mixins.
"""

# Standard library imports
import logging
from typing import Any, Union, Optional
import warnings

# Third-party imports
from qtpy.QtWidgets import QAction, QWidget

# Local imports
from spyder.config.gui import Shortcut
from spyder.config.manager import CONF
from spyder.config.types import ConfigurationKey
from spyder.config.user import NoDefault


logger = logging.getLogger(__name__)

BasicTypes = Union[bool, int, str, tuple, list, dict]


class SpyderConfigurationAccessor:
    """
    Mixin used to access options stored in the Spyder configuration system.
    """

    # Name of the configuration section that's going to be
    # used to record the object's permanent data in Spyder
    # config system.
    CONF_SECTION = None

    def get_conf(self,
                 option: ConfigurationKey,
                 default: Union[NoDefault, BasicTypes] = NoDefault,
                 section: Optional[str] = None):
        """
        Get an option from the Spyder configuration system.

        Parameters
        ----------
        option: ConfigurationKey
            Name/Tuple path of the option to get its value from.
        default: Union[NoDefault, BasicTypes]
            Fallback value to return if the option is not found on the
            configuration system.
        section: str
            Section in the configuration system, e.g. `shortcuts`. If None,
            then the value of `CONF_SECTION` is used.

        Returns
        -------
        value: BasicTypes
            Value of the option in the configuration section.

        Raises
        ------
        configparser.NoOptionError
            If the section does not exist in the configuration.
        """
        section = self.CONF_SECTION if section is None else section
        if section is None:
            raise AttributeError(
                'A SpyderConfigurationAccessor must define a `CONF_SECTION` '
                'class attribute!'
            )

        return CONF.get(section, option, default)

    def get_conf_options(self, section: Optional[str] = None):
        """
        Get all options from the given section.

        Parameters
        ----------
        section: Optional[str]
            Section in the configuration system, e.g. `shortcuts`. If None,
            then the value of `CONF_SECTION` is used.

        Returns
        -------
        values: BasicTypes
            Values of the option in the configuration section.

        Raises
        ------
        configparser.NoOptionError
            If the section does not exist in the configuration.
        """
        section = self.CONF_SECTION if section is None else section
        if section is None:
            raise AttributeError(
                'A SpyderConfigurationAccessor must define a `CONF_SECTION` '
                'class attribute!'
            )
        return CONF.options(section)

    def set_conf(self,
                 option: ConfigurationKey,
                 value: BasicTypes,
                 section: Optional[str] = None,
                 recursive_notification: bool = True):
        """
        Set an option in the Spyder configuration system.

        Parameters
        ----------
        option: ConfigurationKey
            Name/Tuple path of the option to set its value.
        value: BasicTypes
            Value to set on the configuration system.
        section: Optional[str]
            Section in the configuration system, e.g. `shortcuts`. If None,
            then the value of `CONF_SECTION` is used.
        recursive_notification: bool
            If True, all objects that observe all changes on the
            configuration section and objects that observe partial tuple paths
            are notified. For example if the option `opt` of section `sec`
            changes, then the observers for section `sec` are notified.
            Likewise, if the option `(a, b, c)` changes, then observers for
            `(a, b, c)`, `(a, b)` and a are notified as well.
        """
        section = self.CONF_SECTION if section is None else section
        if section is None:
            raise AttributeError(
                'A SpyderConfigurationAccessor must define a `CONF_SECTION` '
                'class attribute!'
            )
        CONF.set(
            section,
            option,
            value,
            recursive_notification=recursive_notification
        )

    def remove_conf(self,
                    option: ConfigurationKey,
                    section: Optional[str] = None):
        """
        Remove an option in the Spyder configuration system.

        Parameters
        ----------
        option: ConfigurationKey
            Name/Tuple path of the option to remove its value.
        section: Optional[str]
            Section in the configuration system, e.g. `shortcuts`. If None,
            then the value of `CONF_SECTION` is used.
        """
        section = self.CONF_SECTION if section is None else section
        if section is None:
            raise AttributeError(
                'A SpyderConfigurationAccessor must define a `CONF_SECTION` '
                'class attribute!'
            )
        CONF.remove_option(section, option)

    def get_conf_default(self,
                         option: ConfigurationKey,
                         section: Optional[str] = None):
        """
        Get an option default value in the Spyder configuration system.

        Parameters
        ----------
        option: ConfigurationKey
            Name/Tuple path of the option to remove its value.
        section: Optional[str]
            Section in the configuration system, e.g. `shortcuts`. If None,
            then the value of `CONF_SECTION` is used.
        """
        section = self.CONF_SECTION if section is None else section
        if section is None:
            raise AttributeError(
                'A SpyderConfigurationAccessor must define a `CONF_SECTION` '
                'class attribute!'
            )
        return CONF.get_default(section, option)

    def get_shortcut(
            self, name: str, context: Optional[str] = None,
            plugin_name: Optional[str] = None) -> str:
        """
        Get a shortcut sequence stored under the given name and context.

        Parameters
        ----------
        name: str
            Key identifier under which the shortcut is stored.
        context: Optional[str]
            Name of the shortcut context.
        plugin: Optional[str]
            Name of the plugin where the shortcut is defined.

        Returns
        -------
        shortcut: str
            Key sequence of the shortcut.

        Raises
        ------
        configparser.NoOptionError
            If the section does not exist in the configuration.
        """
        context = self.CONF_SECTION if context is None else context
        return CONF.get_shortcut(context, name, plugin_name)

    def config_shortcut(
            self, action: QAction, name: str, parent: QWidget,
            context: Optional[str] = None) -> Shortcut:
        """
        Create a Shortcut namedtuple for a widget.

        The data contained in this tuple will be registered in our shortcuts
        preferences page.

        Parameters
        ----------
        action: QAction
            Action that will use the shortcut.
        name: str
            Key identifier under which the shortcut is stored.
        parent: QWidget
            Parent widget for the shortcut.
        context: Optional[str]
            Name of the context (plugin) where the shortcut was defined.

        Returns
        -------
        shortcut: Shortcut
            Namedtuple with the information of the shortcut as used for the
            shortcuts preferences page.
        """
        shortcut_context = self.CONF_SECTION if context is None else context
        return CONF.config_shortcut(
            action,
            shortcut_context,
            name,
            parent
        )

    @property
    def old_conf_version(self):
        """Get old Spyder configuration version."""
        return CONF.old_spyder_version


class SpyderConfigurationObserver(SpyderConfigurationAccessor):
    """
    Concrete implementation of the protocol
    :class:`spyder.config.types.ConfigurationObserver`.

    This mixin enables a class to receive configuration updates seamlessly,
    by registering methods using the
    :function:`spyder.api.config.decorators.on_conf_change` decorator, which
    receives a configuration section and option to observe.

    When a change occurs on any of the registered configuration options,
    the corresponding registered method is called with the new value.
    """

    def __init__(self):
        super().__init__()
        if self.CONF_SECTION is None:
            warnings.warn(
                'A SpyderConfigurationObserver must define a `CONF_SECTION` '
                f'class attribute! Hint: {self} or its parent should define '
                'the section.'
            )

        self._configuration_listeners = {}
        self._multi_option_listeners = set({})
        self._gather_observers()
        self._merge_none_observers()

        # Register class to listen for changes in all registered options
        for section in self._configuration_listeners:
            section = self.CONF_SECTION if section is None else section
            observed_options = self._configuration_listeners[section]
            for option in observed_options:
                logger.debug(f'{self} is observing {option} '
                             f'in section {section}')
                CONF.observe_configuration(self, section, option)

    def __del__(self):
        # Remove object from the configuration observer
        CONF.unobserve_configuration(self)

    def _gather_observers(self):
        """Gather all the methods decorated with `on_conf_change`."""
        for method_name in dir(self):
            method = getattr(self, method_name, None)
            if hasattr(method, '_conf_listen'):
                info = method._conf_listen
                if len(info) > 1:
                    self._multi_option_listeners |= {method_name}

                for section, option in info:
                    section_listeners = self._configuration_listeners.get(
                        section, {})
                    option_listeners = section_listeners.get(option, [])
                    option_listeners.append(method_name)
                    section_listeners[option] = option_listeners
                    self._configuration_listeners[section] = section_listeners

    def _merge_none_observers(self):
        """Replace observers that declared section as None by CONF_SECTION."""
        default_selectors = self._configuration_listeners.get(None, {})
        section_selectors = self._configuration_listeners.get(
            self.CONF_SECTION, {})

        for option in default_selectors:
            default_option_receivers = default_selectors.get(option, [])
            section_option_receivers = section_selectors.get(option, [])
            merged_receivers = (
                default_option_receivers + section_option_receivers)
            section_selectors[option] = merged_receivers

        self._configuration_listeners[self.CONF_SECTION] = section_selectors
        self._configuration_listeners.pop(None, None)

    def on_configuration_change(self, option: ConfigurationKey, section: str,
                                value: Any):
        """
        Handle configuration updates for the option `option` on the section
        `section`, whose new value corresponds to `value`.

        Parameters
        ----------
        option: ConfigurationKey
            Configuration option that did change.
        section: str
            Name of the section where `option` is contained.
        value: Any
            New value of the configuration option that produced the event.
        """
        section_receivers = self._configuration_listeners.get(section, {})
        option_receivers = section_receivers.get(option, [])
        for receiver in option_receivers:
            method = getattr(self, receiver)
            if receiver in self._multi_option_listeners:
                method(option, value)
            else:
                method(value)