diff --git a/doc/api/matplotlib_configuration_api.rst b/doc/api/matplotlib_configuration_api.rst index e497d80b7c12..f786824b4c3c 100644 --- a/doc/api/matplotlib_configuration_api.rst +++ b/doc/api/matplotlib_configuration_api.rst @@ -43,6 +43,8 @@ Default values and styling .. autofunction:: matplotlib_fname +.. autofunction:: get_data_path + Logging ======= diff --git a/doc/api/prev_api_changes/api_changes_3.2.0/deprecations.rst b/doc/api/prev_api_changes/api_changes_3.2.0/deprecations.rst index c61c9cca3b03..0003a0643158 100644 --- a/doc/api/prev_api_changes/api_changes_3.2.0/deprecations.rst +++ b/doc/api/prev_api_changes/api_changes_3.2.0/deprecations.rst @@ -290,3 +290,10 @@ from the public API in future versions. ``style.core.is_style_file`` and ``style.core.iter_style_files`` are deprecated. + +The ``datapath`` rcParam +~~~~~~~~~~~~~~~~~~~~~~~~ +Use `.get_data_path` instead. (The rcParam is deprecated because it cannot be +meaningfully set by an end user.) The rcParam had no effect from 3.2.0, but +was deprecated only in 3.2.1. In 3.2.1+ if ``'datapath'`` is set in a +``matplotlibrc`` file it will be respected, but this behavior will be removed in 3.3. diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py index c4dba5f29613..fa1caecda148 100644 --- a/lib/matplotlib/__init__.py +++ b/lib/matplotlib/__init__.py @@ -132,6 +132,7 @@ import shutil import subprocess import tempfile +import warnings # cbook must import matplotlib only within function # definitions, so it is safe to import from it here. @@ -269,10 +270,10 @@ def func(): ... ret = None @functools.wraps(func) - def wrapper(): + def wrapper(**kwargs): nonlocal called, ret if not called: - ret = func() + ret = func(**kwargs) called = True _log.debug(fmt, ret) return ret @@ -619,9 +620,31 @@ def get_cachedir(): return _get_config_or_cache_dir(_get_xdg_cache_dir()) -def _get_data_path(): - """Return the path to matplotlib data.""" +@_logged_cached('matplotlib data path: %s') +def get_data_path(*, _from_rc=None): + """Return the path to Matplotlib data.""" + if _from_rc is not None: + cbook.warn_deprecated( + "3.2", + message=("Setting the datapath via matplotlibrc is " + "deprecated %(since)s and will be removed in %(removal)s. " + ""), + removal='3.3') + path = Path(_from_rc) + if path.is_dir(): + defaultParams['datapath'][0] = str(path) + return str(path) + else: + warnings.warn(f"You passed datapath: {_from_rc!r} in your " + f"matplotribrc file ({matplotlib_fname()}). " + "However this path does not exist, falling back " + "to standard paths.") + + return _get_data_path() + +@_logged_cached('(private) matplotlib data path: %s') +def _get_data_path(): if 'MATPLOTLIBDATA' in os.environ: path = os.environ['MATPLOTLIBDATA'] if not os.path.isdir(path): @@ -633,6 +656,7 @@ def _get_data_path(): path = Path(__file__).with_name("mpl-data") if path.is_dir(): + defaultParams['datapath'][0] = str(path) return str(path) cbook.warn_deprecated( @@ -655,18 +679,12 @@ def get_candidate_paths(): for path in get_candidate_paths(): if path.is_dir(): + defaultParams['datapath'][0] = str(path) return str(path) raise RuntimeError('Could not find the matplotlib data files') -@_logged_cached('matplotlib data path: %s') -def get_data_path(): - if defaultParams['datapath'][0] is None: - defaultParams['datapath'][0] = _get_data_path() - return defaultParams['datapath'][0] - - @cbook.deprecated("3.1") def get_py2exe_datafiles(): data_path = Path(get_data_path()) @@ -708,7 +726,7 @@ def gen_candidates(): yield matplotlibrc yield os.path.join(matplotlibrc, 'matplotlibrc') yield os.path.join(get_configdir(), 'matplotlibrc') - yield os.path.join(get_data_path(), 'matplotlibrc') + yield os.path.join(_get_data_path(), 'matplotlibrc') for fname in gen_candidates(): if os.path.exists(fname) and not os.path.isdir(fname): @@ -736,6 +754,7 @@ def gen_candidates(): 'savefig.frameon': ('3.1',), 'verbose.fileo': ('3.1',), 'verbose.level': ('3.1',), + 'datapath': ('3.2.1',), } @@ -973,8 +992,11 @@ def rc_params_from_file(fname, fail_on_error=False, use_default_template=True): if key not in _all_deprecated]) config.update(config_from_file) - if config['datapath'] is None: - config['datapath'] = get_data_path() + with cbook._suppress_matplotlib_deprecation_warning(): + if config['datapath'] is None: + config['datapath'] = _get_data_path() + else: + config['datapath'] = get_data_path(_from_rc=config['datapath']) if "".join(config['text.latex.preamble']): _log.info(""" diff --git a/lib/matplotlib/cbook/__init__.py b/lib/matplotlib/cbook/__init__.py index 1b222f971878..8338982df401 100644 --- a/lib/matplotlib/cbook/__init__.py +++ b/lib/matplotlib/cbook/__init__.py @@ -439,7 +439,7 @@ def get_sample_data(fname, asfileobj=True): If the filename ends in .gz, the file is implicitly ungzipped. """ - path = Path(matplotlib._get_data_path(), 'sample_data', fname) + path = Path(matplotlib.get_data_path(), 'sample_data', fname) if asfileobj: suffix = path.suffix.lower() if suffix == '.gz': diff --git a/matplotlibrc.template b/matplotlibrc.template index 17f12a673ebc..16d9becaae93 100644 --- a/matplotlibrc.template +++ b/matplotlibrc.template @@ -103,10 +103,6 @@ #toolbar : toolbar2 ## {None, toolbar2} #timezone : UTC ## a pytz timezone string, e.g., US/Central or Europe/Paris -## Where your matplotlib data lives if you installed to a non-default -## location. This is where the matplotlib fonts, bitmaps, etc reside -#datapath : /home/jdhunter/mpldata - ## *************************************************************************** ## * LINES *