""" Core functions and attributes for the matplotlib style library: ``use`` Select style sheet to override the current matplotlib settings. ``context`` Context manager to use a style sheet temporarily. ``available`` List available style sheets. ``library`` A dictionary of style names and matplotlib settings. """ import contextlib import importlib.resources import logging import os from pathlib import Path import warnings import matplotlib as mpl from matplotlib import _api, _docstring, _rc_params_in_file, rcParamsDefault _log = logging.getLogger(__name__) __all__ = ['use', 'context', 'available', 'library', 'reload_library'] BASE_LIBRARY_PATH = os.path.join(mpl.get_data_path(), 'stylelib') # Users may want multiple library paths, so store a list of paths. USER_LIBRARY_PATHS = [os.path.join(mpl.get_configdir(), 'stylelib')] STYLE_EXTENSION = 'mplstyle' # A list of rcParams that should not be applied from styles STYLE_BLACKLIST = { 'interactive', 'backend', 'webagg.port', 'webagg.address', 'webagg.port_retries', 'webagg.open_in_browser', 'backend_fallback', 'toolbar', 'timezone', 'figure.max_open_warning', 'figure.raise_window', 'savefig.directory', 'tk.window_focus', 'docstring.hardcopy', 'date.epoch'} @_docstring.Substitution( "\n".join(map("- {}".format, sorted(STYLE_BLACKLIST, key=str.lower))) ) def use(style): """ Use Matplotlib style settings from a style specification. The style name of 'default' is reserved for reverting back to the default style settings. .. note:: This updates the `.rcParams` with the settings from the style. `.rcParams` not defined in the style are kept. Parameters ---------- style : str, dict, Path or list A style specification. Valid options are: str - One of the style names in `.style.available` (a builtin style or a style installed in the user library path). - A dotted name of the form "package.style_name"; in that case, "package" should be an importable Python package name, e.g. at ``/path/to/package/__init__.py``; the loaded style file is ``/path/to/package/style_name.mplstyle``. (Style files in subpackages are likewise supported.) - The path or URL to a style file, which gets loaded by `.rc_params_from_file`. dict A mapping of key/value pairs for `matplotlib.rcParams`. Path The path to a style file, which gets loaded by `.rc_params_from_file`. list A list of style specifiers (str, Path or dict), which are applied from first to last in the list. Notes ----- The following `.rcParams` are not related to style and will be ignored if found in a style specification: %s """ if isinstance(style, (str, Path)) or hasattr(style, 'keys'): # If name is a single str, Path or dict, make it a single element list. styles = [style] else: styles = style style_alias = {'mpl20': 'default', 'mpl15': 'classic'} for style in styles: if isinstance(style, str): style = style_alias.get(style, style) if style == "default": # Deprecation warnings were already handled when creating # rcParamsDefault, no need to reemit them here. with _api.suppress_matplotlib_deprecation_warning(): # don't trigger RcParams.__getitem__('backend') style = {k: rcParamsDefault[k] for k in rcParamsDefault if k not in STYLE_BLACKLIST} elif style in library: style = library[style] elif "." in style: pkg, _, name = style.rpartition(".") try: path = importlib.resources.files(pkg) / f"{name}.{STYLE_EXTENSION}" style = _rc_params_in_file(path) except (ModuleNotFoundError, OSError, TypeError) as exc: # There is an ambiguity whether a dotted name refers to a # package.style_name or to a dotted file path. Currently, # we silently try the first form and then the second one; # in the future, we may consider forcing file paths to # either use Path objects or be prepended with "./" and use # the slash as marker for file paths. pass if isinstance(style, (str, Path)): try: style = _rc_params_in_file(style) except OSError as err: raise OSError( f"{style!r} is not a valid package style, path of style " f"file, URL of style file, or library style name (library " f"styles are listed in `style.available`)") from err filtered = {} for k in style: # don't trigger RcParams.__getitem__('backend') if k in STYLE_BLACKLIST: _api.warn_external( f"Style includes a parameter, {k!r}, that is not " f"related to style. Ignoring this parameter.") else: filtered[k] = style[k] mpl.rcParams.update(filtered) @contextlib.contextmanager def context(style, after_reset=False): """ Context manager for using style settings temporarily. Parameters ---------- style : str, dict, Path or list A style specification. Valid options are: str - One of the style names in `.style.available` (a builtin style or a style installed in the user library path). - A dotted name of the form "package.style_name"; in that case, "package" should be an importable Python package name, e.g. at ``/path/to/package/__init__.py``; the loaded style file is ``/path/to/package/style_name.mplstyle``. (Style files in subpackages are likewise supported.) - The path or URL to a style file, which gets loaded by `.rc_params_from_file`. dict A mapping of key/value pairs for `matplotlib.rcParams`. Path The path to a style file, which gets loaded by `.rc_params_from_file`. list A list of style specifiers (str, Path or dict), which are applied from first to last in the list. after_reset : bool If True, apply style after resetting settings to their defaults; otherwise, apply style on top of the current settings. """ with mpl.rc_context(): if after_reset: mpl.rcdefaults() use(style) yield def update_user_library(library): """Update style library with user-defined rc files.""" for stylelib_path in map(os.path.expanduser, USER_LIBRARY_PATHS): styles = read_style_directory(stylelib_path) update_nested_dict(library, styles) return library def read_style_directory(style_dir): """Return dictionary of styles defined in *style_dir*.""" styles = dict() for path in Path(style_dir).glob(f"*.{STYLE_EXTENSION}"): with warnings.catch_warnings(record=True) as warns: styles[path.stem] = _rc_params_in_file(path) for w in warns: _log.warning('In %s: %s', path, w.message) return styles def update_nested_dict(main_dict, new_dict): """ Update nested dict (only level of nesting) with new values. Unlike `dict.update`, this assumes that the values of the parent dict are dicts (or dict-like), so you shouldn't replace the nested dict if it already exists. Instead you should update the sub-dict. """ # update named styles specified by user for name, rc_dict in new_dict.items(): main_dict.setdefault(name, {}).update(rc_dict) return main_dict # Load style library # ================== _base_library = read_style_directory(BASE_LIBRARY_PATH) library = {} available = [] def reload_library(): """Reload the style library.""" library.clear() library.update(update_user_library(_base_library)) available[:] = sorted(library.keys()) reload_library()