"""

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. Underscore-prefixed names are considered private and

not listed, though may still be accessed directly from ``library``.

``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_from_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_from_file(path, use_default_template=False)

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_from_file(style, use_default_template=False)

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

@_api.deprecated("3.11")

def update_user_library(library):

return _update_user_library(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_from_file(path, use_default_template=False)

for w in warns:

_log.warning('In %s: %s', path, w.message)

return styles

@_api.deprecated("3.11")

def read_style_directory(style_dir):

return _read_style_directory(style_dir)

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

@_api.deprecated("3.11")

def update_nested_dict(main_dict, new_dict):

return _update_nested_dict(main_dict, new_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.copy()))

available[:] = sorted(name for name in library if not name.startswith('_'))

reload_library()