Source code for simplebench.reporters.graph.matplotlib.theme.base

"""MatPlotLib Theme implementation.

Provides a base class for MatPlotLib themes used in SimpleBench graphs.
"""
from __future__ import annotations

from typing import Any

from matplotlib import RcParams

from simplebench.exceptions import SimpleBenchNotImplementedError

from .exceptions import _ThemeErrorTag




class Theme(RcParams):
    """An immutable MatPlotLib base theme class for the graphs.

    This is a subclass of :class:`matplotlib.RcParams` that represents a theme for Matplotlib graphs.
    It can be used to define custom styles for Matplotlib graphs generated by SimpleBench.

    See `Customizing Matplotlib with style sheets and rcParams
    <https://matplotlib.org/stable/tutorials/introductory/customizing.html>`_
    for more information on customizing Matplotlib themes.
    """
    def __init__(self, rcparams: dict[str, Any] | None = None) -> None:
        """Initialize a :class:`~.Theme` instance.

        :param rcparams: The rcParams to use for the theme.
                         If ``None``, the default Matplotlib rcParams will be used.
        :type rcparams: dict[str, Any] | None
        """
        self._immutable: bool = False
        if rcparams is None:
            rcparams = {}
        super().__init__(rcparams)
        self._immutable = True

    def __setitem__(self, key: str, value: Any) -> None:
        """Set an item in the :class:`~.Theme`.

        This thin wrapper prevents modification of the :class:`~.Theme` after initialization.

        It is required to maintain the immutability of the :class:`~.Theme` instance because the
        underlying :class:`~matplotlib.RcParams` class allows item modification
        (and requires it for initialization).

        :param key: The key to set.
        :type key: str
        :param value: The value to set.
        :type value: Any
        :raises SimpleBenchNotImplementedError: If attempting to modify the :class:`~.Theme`
                                                 after initialization.
        """
        if self._immutable:
            raise SimpleBenchNotImplementedError("Cannot modify items in a Theme.",
                                                 tag=_ThemeErrorTag.THEME_IMMUTABLE)
        super().__setitem__(key, value)

    def __delitem__(self, key: str) -> None:
        """Delete an item from the :class:`~.Theme`.

        This thin wrapper prevents deletion of items from the :class:`~.Theme` after initialization.

        It is required to maintain the immutability of the :class:`~.Theme` instance because the
        underlying :class:`~matplotlib.RcParams` class allows item deletion.

        :param key: The key to delete.
        :type key: str
        :raises SimpleBenchNotImplementedError: If attempting to delete an item from the
                                                 :class:`~.Theme` after initialization.
        """
        if self._immutable:
            raise SimpleBenchNotImplementedError("Cannot delete items from a Theme.",
                                                 tag=_ThemeErrorTag.THEME_IMMUTABLE)
        super().__delitem__(key)



    def replace(self, rcparams: dict[str, Any]) -> Theme:
        """Replace some parameters in the theme and return a new :class:`~.Theme` instance
        without modifying the current instance.

        .. code-block:: python

            new_theme = old_theme.replace({'axes.grid': False, 'figure.dpi': 200})

        :param rcparams: The new rcParams to use for the theme.
        :type rcparams: dict[str, Any]
        :return: A new :class:`~.Theme` instance with the updated rcParams.
        :rtype: :class:`~.Theme`
        """
        new_params = self.copy()
        new_params.update(rcparams)
        return Theme(new_params)