Coverage for /usr/lib/python3/dist-packages/matplotlib/__init__.py: 47%

1""" 

2An object-oriented plotting library. 

3 

4A procedural interface is provided by the companion pyplot module, 

5which may be imported directly, e.g.:: 

6 

7 import matplotlib.pyplot as plt 

8 

9or using ipython:: 

10 

11 ipython 

12 

13at your terminal, followed by:: 

14 

15 In [1]: %matplotlib 

16 In [2]: import matplotlib.pyplot as plt 

17 

18at the ipython shell prompt. 

19 

20For the most part, direct use of the explicit object-oriented library is 

21encouraged when programming; the implicit pyplot interface is primarily for 

22working interactively. The exceptions to this suggestion are the pyplot 

23functions `.pyplot.figure`, `.pyplot.subplot`, `.pyplot.subplots`, and 

24`.pyplot.savefig`, which can greatly simplify scripting. See 

25:ref:`api_interfaces` for an explanation of the tradeoffs between the implicit 

26and explicit interfaces. 

27 

28Modules include: 

29 

30 :mod:`matplotlib.axes` 

31 The `~.axes.Axes` class. Most pyplot functions are wrappers for 

32 `~.axes.Axes` methods. The axes module is the highest level of OO 

33 access to the library. 

34 

35 :mod:`matplotlib.figure` 

36 The `.Figure` class. 

37 

38 :mod:`matplotlib.artist` 

39 The `.Artist` base class for all classes that draw things. 

40 

41 :mod:`matplotlib.lines` 

42 The `.Line2D` class for drawing lines and markers. 

43 

44 :mod:`matplotlib.patches` 

45 Classes for drawing polygons. 

46 

47 :mod:`matplotlib.text` 

48 The `.Text` and `.Annotation` classes. 

49 

50 :mod:`matplotlib.image` 

51 The `.AxesImage` and `.FigureImage` classes. 

52 

53 :mod:`matplotlib.collections` 

54 Classes for efficient drawing of groups of lines or polygons. 

55 

56 :mod:`matplotlib.colors` 

57 Color specifications and making colormaps. 

58 

59 :mod:`matplotlib.cm` 

60 Colormaps, and the `.ScalarMappable` mixin class for providing color 

61 mapping functionality to other classes. 

62 

63 :mod:`matplotlib.ticker` 

64 Calculation of tick mark locations and formatting of tick labels. 

65 

66 :mod:`matplotlib.backends` 

67 A subpackage with modules for various GUI libraries and output formats. 

68 

69The base matplotlib namespace includes: 

70 

71 `~matplotlib.rcParams` 

72 Default configuration settings; their defaults may be overridden using 

73 a :file:`matplotlibrc` file. 

74 

75 `~matplotlib.use` 

76 Setting the Matplotlib backend. This should be called before any 

77 figure is created, because it is not possible to switch between 

78 different GUI backends after that. 

79 

80Matplotlib was initially written by John D. Hunter (1968-2012) and is now 

81developed and maintained by a host of others. 

82 

83Occasionally the internal documentation (python docstrings) will refer 

84to MATLAB®, a registered trademark of The MathWorks, Inc. 

85 

86""" 

87 

88import atexit 

89from collections import namedtuple 

90from collections.abc import MutableMapping 

91import contextlib 

92import functools 

93import importlib 

94import inspect 

95from inspect import Parameter 

96import locale 

97import logging 

98import os 

99from pathlib import Path 

100import pprint 

101import re 

102import shutil 

103import subprocess 

104import sys 

105import tempfile 

106import warnings 

107 

108import numpy 

109from packaging.version import parse as parse_version 

110 

111# cbook must import matplotlib only within function 

112# definitions, so it is safe to import from it here. 

113from . import _api, _version, cbook, _docstring, rcsetup 

114from matplotlib.cbook import sanitize_sequence 

115from matplotlib._api import MatplotlibDeprecationWarning 

116from matplotlib.rcsetup import validate_backend, cycler 

117 

118 

119_log = logging.getLogger(__name__) 

120 

121__bibtex__ = r"""@Article{Hunter:2007, 

122 Author = {Hunter, J. D.}, 

123 Title = {Matplotlib: A 2D graphics environment}, 

124 Journal = {Computing in Science \& Engineering}, 

125 Volume = {9}, 

126 Number = {3}, 

127 Pages = {90--95}, 

128 abstract = {Matplotlib is a 2D graphics package used for Python 

129 for application development, interactive scripting, and 

130 publication-quality image generation across user 

131 interfaces and operating systems.}, 

132 publisher = {IEEE COMPUTER SOC}, 

133 year = 2007 

134}""" 

135 

136# modelled after sys.version_info 

137_VersionInfo = namedtuple('_VersionInfo', 

138 'major, minor, micro, releaselevel, serial') 

139 

140 

141def _parse_to_version_info(version_str): 

142 """ 

143 Parse a version string to a namedtuple analogous to sys.version_info. 

144 

145 See: 

146 https://packaging.pypa.io/en/latest/version.html#packaging.version.parse 

147 https://docs.python.org/3/library/sys.html#sys.version_info 

148 """ 

149 v = parse_version(version_str) 

150 if v.pre is None and v.post is None and v.dev is None: 

151 return _VersionInfo(v.major, v.minor, v.micro, 'final', 0) 

152 elif v.dev is not None: 

153 return _VersionInfo(v.major, v.minor, v.micro, 'alpha', v.dev) 

154 elif v.pre is not None: 

155 releaselevel = { 

156 'a': 'alpha', 

157 'b': 'beta', 

158 'rc': 'candidate'}.get(v.pre[0], 'alpha') 

159 return _VersionInfo(v.major, v.minor, v.micro, releaselevel, v.pre[1]) 

160 else: 

161 # fallback for v.post: guess-next-dev scheme from setuptools_scm 

162 return _VersionInfo(v.major, v.minor, v.micro + 1, 'alpha', v.post) 

163 

164 

165def _get_version(): 

166 """Return the version string used for __version__.""" 

167 # Only shell out to a git subprocess if really needed, i.e. when we are in 

168 # a matplotlib git repo but not in a shallow clone, such as those used by 

169 # CI, as the latter would trigger a warning from setuptools_scm. 

170 root = Path(__file__).resolve().parents[2] 

171 if ((root / ".matplotlib-repo").exists() 

172 and (root / ".git").exists() 

173 and not (root / ".git/shallow").exists()): 

174 import setuptools_scm 

175 return setuptools_scm.get_version( 

176 root=root, 

177 version_scheme="release-branch-semver", 

178 local_scheme="node-and-date", 

179 fallback_version=_version.version, 

180 ) 

181 else: # Get the version from the _version.py setuptools_scm file. 

182 return _version.version 

183 

184 

185@_api.caching_module_getattr 

186class __getattr__: 

187 __version__ = property(lambda self: _get_version()) 

188 __version_info__ = property( 

189 lambda self: _parse_to_version_info(self.__version__)) 

190 # module-level deprecations 

191 URL_REGEX = _api.deprecated("3.5", obj_type="")(property( 

192 lambda self: re.compile(r'^http://|^https://|^ftp://|^file:'))) 

193 

194 

195def _check_versions(): 

196 

197 # Quickfix to ensure Microsoft Visual C++ redistributable 

198 # DLLs are loaded before importing kiwisolver 

199 from . import ft2font 

200 

201 for modname, minver in [ 

202 ("cycler", "0.10"), 

203 ("dateutil", "2.7"), 

204 ("kiwisolver", "1.0.1"), 

205 ("numpy", "1.19"), 

206 ("pyparsing", "2.2.1"), 

207 ]: 

208 module = importlib.import_module(modname) 

209 if parse_version(module.__version__) < parse_version(minver): 

210 raise ImportError(f"Matplotlib requires {modname}>={minver}; " 

211 f"you have {module.__version__}") 

212 

213 

214_check_versions() 

215 

216 

217# The decorator ensures this always returns the same handler (and it is only 

218# attached once). 

219@functools.lru_cache() 

220def _ensure_handler(): 

221 """ 

222 The first time this function is called, attach a `StreamHandler` using the 

223 same format as `logging.basicConfig` to the Matplotlib root logger. 

224 

225 Return this handler every time this function is called. 

226 """ 

227 handler = logging.StreamHandler() 

228 handler.setFormatter(logging.Formatter(logging.BASIC_FORMAT)) 

229 _log.addHandler(handler) 

230 return handler 

231 

232 

233def set_loglevel(level): 

234 """ 

235 Set Matplotlib's root logger and root logger handler level, creating 

236 the handler if it does not exist yet. 

237 

238 Typically, one should call ``set_loglevel("info")`` or 

239 ``set_loglevel("debug")`` to get additional debugging information. 

240 

241 Parameters 

242 ---------- 

243 level : {"notset", "debug", "info", "warning", "error", "critical"} 

244 The log level of the handler. 

245 

246 Notes 

247 ----- 

248 The first time this function is called, an additional handler is attached 

249 to Matplotlib's root handler; this handler is reused every time and this 

250 function simply manipulates the logger and handler's level. 

251 """ 

252 _log.setLevel(level.upper()) 

253 _ensure_handler().setLevel(level.upper()) 

254 

255 

256def _logged_cached(fmt, func=None): 

257 """ 

258 Decorator that logs a function's return value, and memoizes that value. 

259 

260 After :: 

261 

262 @_logged_cached(fmt) 

263 def func(): ... 

264 

265 the first call to *func* will log its return value at the DEBUG level using 

266 %-format string *fmt*, and memoize it; later calls to *func* will directly 

267 return that value. 

268 """ 

269 if func is None: # Return the actual decorator. 

270 return functools.partial(_logged_cached, fmt) 

271 

272 called = False 

273 ret = None 

274 

275 @functools.wraps(func) 

276 def wrapper(**kwargs): 

277 nonlocal called, ret 

278 if not called: 

279 ret = func(**kwargs) 

280 called = True 

281 _log.debug(fmt, ret) 

282 return ret 

283 

284 return wrapper 

285 

286 

287_ExecInfo = namedtuple("_ExecInfo", "executable raw_version version") 

288 

289 

290class ExecutableNotFoundError(FileNotFoundError): 

291 """ 

292 Error raised when an executable that Matplotlib optionally 

293 depends on can't be found. 

294 """ 

295 pass 

296 

297 

298@functools.lru_cache() 

299def _get_executable_info(name): 

300 """ 

301 Get the version of some executable that Matplotlib optionally depends on. 

302 

303 .. warning:: 

304 The list of executables that this function supports is set according to 

305 Matplotlib's internal needs, and may change without notice. 

306 

307 Parameters 

308 ---------- 

309 name : str 

310 The executable to query. The following values are currently supported: 

311 "dvipng", "gs", "inkscape", "magick", "pdftocairo", "pdftops". This 

312 list is subject to change without notice. 

313 

314 Returns 

315 ------- 

316 tuple 

317 A namedtuple with fields ``executable`` (`str`) and ``version`` 

318 (`packaging.Version`, or ``None`` if the version cannot be determined). 

319 

320 Raises 

321 ------ 

322 ExecutableNotFoundError 

323 If the executable is not found or older than the oldest version 

324 supported by Matplotlib. For debugging purposes, it is also 

325 possible to "hide" an executable from Matplotlib by adding it to the 

326 :envvar:`_MPLHIDEEXECUTABLES` environment variable (a comma-separated 

327 list), which must be set prior to any calls to this function. 

328 ValueError 

329 If the executable is not one that we know how to query. 

330 """ 

331 

332 def impl(args, regex, min_ver=None, ignore_exit_code=False): 

333 # Execute the subprocess specified by args; capture stdout and stderr. 

334 # Search for a regex match in the output; if the match succeeds, the 

335 # first group of the match is the version. 

336 # Return an _ExecInfo if the executable exists, and has a version of 

337 # at least min_ver (if set); else, raise ExecutableNotFoundError. 

338 try: 

339 output = subprocess.check_output( 

340 args, stderr=subprocess.STDOUT, 

341 universal_newlines=True, errors="replace") 

342 except subprocess.CalledProcessError as _cpe: 

343 if ignore_exit_code: 

344 output = _cpe.output 

345 else: 

346 raise ExecutableNotFoundError(str(_cpe)) from _cpe 

347 except OSError as _ose: 

348 raise ExecutableNotFoundError(str(_ose)) from _ose 

349 match = re.search(regex, output) 

350 if match: 

351 raw_version = match.group(1) 

352 version = parse_version(raw_version) 

353 if min_ver is not None and version < parse_version(min_ver): 

354 raise ExecutableNotFoundError( 

355 f"You have {args[0]} version {version} but the minimum " 

356 f"version supported by Matplotlib is {min_ver}") 

357 return _ExecInfo(args[0], raw_version, version) 

358 else: 

359 raise ExecutableNotFoundError( 

360 f"Failed to determine the version of {args[0]} from " 

361 f"{' '.join(args)}, which output {output}") 

362 

363 if name in os.environ.get("_MPLHIDEEXECUTABLES", "").split(","): 

364 raise ExecutableNotFoundError(f"{name} was hidden") 

365 

366 if name == "dvipng": 

367 return impl(["dvipng", "-version"], "(?m)^dvipng(?: .*)? (.+)", "1.6") 

368 elif name == "gs": 

369 execs = (["gswin32c", "gswin64c", "mgs", "gs"] # "mgs" for miktex. 

370 if sys.platform == "win32" else 

371 ["gs"]) 

372 for e in execs: 

373 try: 

374 return impl([e, "--version"], "(.*)", "9") 

375 except ExecutableNotFoundError: 

376 pass 

377 message = "Failed to find a Ghostscript installation" 

378 raise ExecutableNotFoundError(message) 

379 elif name == "inkscape": 

380 try: 

381 # Try headless option first (needed for Inkscape version < 1.0): 

382 return impl(["inkscape", "--without-gui", "-V"], 

383 "Inkscape ([^ ]*)") 

384 except ExecutableNotFoundError: 

385 pass # Suppress exception chaining. 

386 # If --without-gui is not accepted, we may be using Inkscape >= 1.0 so 

387 # try without it: 

388 return impl(["inkscape", "-V"], "Inkscape ([^ ]*)") 

389 elif name == "magick": 

390 if sys.platform == "win32": 

391 # Check the registry to avoid confusing ImageMagick's convert with 

392 # Windows's builtin convert.exe. 

393 import winreg 

394 binpath = "" 

395 for flag in [0, winreg.KEY_WOW64_32KEY, winreg.KEY_WOW64_64KEY]: 

396 try: 

397 with winreg.OpenKeyEx( 

398 winreg.HKEY_LOCAL_MACHINE, 

399 r"Software\Imagemagick\Current", 

400 0, winreg.KEY_QUERY_VALUE | flag) as hkey: 

401 binpath = winreg.QueryValueEx(hkey, "BinPath")[0] 

402 except OSError: 

403 pass 

404 path = None 

405 if binpath: 

406 for name in ["convert.exe", "magick.exe"]: 

407 candidate = Path(binpath, name) 

408 if candidate.exists(): 

409 path = str(candidate) 

410 break 

411 if path is None: 

412 raise ExecutableNotFoundError( 

413 "Failed to find an ImageMagick installation") 

414 else: 

415 path = "convert" 

416 info = impl([path, "--version"], r"^Version: ImageMagick (\S*)") 

417 if info.raw_version == "7.0.10-34": 

418 # https://github.com/ImageMagick/ImageMagick/issues/2720 

419 raise ExecutableNotFoundError( 

420 f"You have ImageMagick {info.version}, which is unsupported") 

421 return info 

422 elif name == "pdftocairo": 

423 return impl(["pdftocairo", "-v"], "pdftocairo version (.*)") 

424 elif name == "pdftops": 

425 info = impl(["pdftops", "-v"], "^pdftops version (.*)", 

426 ignore_exit_code=True) 

427 if info and not ( 

428 3 <= info.version.major or 

429 # poppler version numbers. 

430 parse_version("0.9") <= info.version < parse_version("1.0")): 

431 raise ExecutableNotFoundError( 

432 f"You have pdftops version {info.version} but the minimum " 

433 f"version supported by Matplotlib is 3.0") 

434 return info 

435 else: 

436 raise ValueError("Unknown executable: {!r}".format(name)) 

437 

438 

439@_api.deprecated("3.6", alternative="a vendored copy of this function") 

440def checkdep_usetex(s): 

441 if not s: 

442 return False 

443 if not shutil.which("tex"): 

444 _log.warning("usetex mode requires TeX.") 

445 return False 

446 try: 

447 _get_executable_info("dvipng") 

448 except ExecutableNotFoundError: 

449 _log.warning("usetex mode requires dvipng.") 

450 return False 

451 try: 

452 _get_executable_info("gs") 

453 except ExecutableNotFoundError: 

454 _log.warning("usetex mode requires ghostscript.") 

455 return False 

456 return True 

457 

458 

459def _get_xdg_config_dir(): 

460 """ 

461 Return the XDG configuration directory, according to the XDG base 

462 directory spec: 

463 

464 https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html 

465 """ 

466 return os.environ.get('XDG_CONFIG_HOME') or str(Path.home() / ".config") 

467 

468 

469def _get_xdg_cache_dir(): 

470 """ 

471 Return the XDG cache directory, according to the XDG base directory spec: 

472 

473 https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html 

474 """ 

475 return os.environ.get('XDG_CACHE_HOME') or str(Path.home() / ".cache") 

476 

477 

478def _get_config_or_cache_dir(xdg_base_getter): 

479 configdir = os.environ.get('MPLCONFIGDIR') 

480 if configdir: 

481 configdir = Path(configdir).resolve() 

482 elif sys.platform.startswith(('linux', 'freebsd')): 

483 # Only call _xdg_base_getter here so that MPLCONFIGDIR is tried first, 

484 # as _xdg_base_getter can throw. 

485 configdir = Path(xdg_base_getter(), "matplotlib") 

486 else: 

487 configdir = Path.home() / ".matplotlib" 

488 try: 

489 configdir.mkdir(parents=True, exist_ok=True) 

490 except OSError: 

491 pass 

492 else: 

493 if os.access(str(configdir), os.W_OK) and configdir.is_dir(): 

494 return str(configdir) 

495 # If the config or cache directory cannot be created or is not a writable 

496 # directory, create a temporary one. 

497 tmpdir = os.environ["MPLCONFIGDIR"] = \ 

498 tempfile.mkdtemp(prefix="matplotlib-") 

499 atexit.register(shutil.rmtree, tmpdir) 

500 _log.warning( 

501 "Matplotlib created a temporary config/cache directory at %s because " 

502 "the default path (%s) is not a writable directory; it is highly " 

503 "recommended to set the MPLCONFIGDIR environment variable to a " 

504 "writable directory, in particular to speed up the import of " 

505 "Matplotlib and to better support multiprocessing.", 

506 tmpdir, configdir) 

507 return tmpdir 

508 

509 

510@_logged_cached('CONFIGDIR=%s') 

511def get_configdir(): 

512 """ 

513 Return the string path of the configuration directory. 

514 

515 The directory is chosen as follows: 

516 

517 1. If the MPLCONFIGDIR environment variable is supplied, choose that. 

518 2. On Linux, follow the XDG specification and look first in 

519 ``$XDG_CONFIG_HOME``, if defined, or ``$HOME/.config``. On other 

520 platforms, choose ``$HOME/.matplotlib``. 

521 3. If the chosen directory exists and is writable, use that as the 

522 configuration directory. 

523 4. Else, create a temporary directory, and use it as the configuration 

524 directory. 

525 """ 

526 return _get_config_or_cache_dir(_get_xdg_config_dir) 

527 

528 

529@_logged_cached('CACHEDIR=%s') 

530def get_cachedir(): 

531 """ 

532 Return the string path of the cache directory. 

533 

534 The procedure used to find the directory is the same as for 

535 _get_config_dir, except using ``$XDG_CACHE_HOME``/``$HOME/.cache`` instead. 

536 """ 

537 return _get_config_or_cache_dir(_get_xdg_cache_dir) 

538 

539 

540@_logged_cached('matplotlib data path: %s') 

541def get_data_path(): 

542 """Return the path to Matplotlib data.""" 

543 _data_path = Path(__file__).with_name("mpl-data") 

544 if _data_path.exists(): 

545 return str(_data_path) 

546 else: 

547 return '/usr/share/matplotlib/mpl-data' 

548 

549 

550def matplotlib_fname(): 

551 """ 

552 Get the location of the config file. 

553 

554 The file location is determined in the following order 

555 

556 - ``$PWD/matplotlibrc`` 

557 - ``$MATPLOTLIBRC`` if it is not a directory 

558 - ``$MATPLOTLIBRC/matplotlibrc`` 

559 - ``$MPLCONFIGDIR/matplotlibrc`` 

560 - On Linux, 

561 - ``$XDG_CONFIG_HOME/matplotlib/matplotlibrc`` (if ``$XDG_CONFIG_HOME`` 

562 is defined) 

563 - or ``$HOME/.config/matplotlib/matplotlibrc`` (if ``$XDG_CONFIG_HOME`` 

564 is not defined) 

565 - On other platforms, 

566 - ``$HOME/.matplotlib/matplotlibrc`` if ``$HOME`` is defined 

567 - Lastly, it looks in ``$MATPLOTLIBDATA/matplotlibrc``, which should always 

568 exist. 

569 """ 

570 

571 def gen_candidates(): 

572 # rely on down-stream code to make absolute. This protects us 

573 # from having to directly get the current working directory 

574 # which can fail if the user has ended up with a cwd that is 

575 # non-existent. 

576 yield 'matplotlibrc' 

577 try: 

578 matplotlibrc = os.environ['MATPLOTLIBRC'] 

579 except KeyError: 

580 pass 

581 else: 

582 yield matplotlibrc 

583 yield os.path.join(matplotlibrc, 'matplotlibrc') 

584 yield os.path.join(get_configdir(), 'matplotlibrc') 

585 yield '/etc/matplotlibrc' 

586 

587 for fname in gen_candidates(): 

588 if os.path.exists(fname) and not os.path.isdir(fname): 

589 return fname 

590 

591 raise RuntimeError("Could not find matplotlibrc file; your Matplotlib " 

592 "install is broken") 

593 

594 

595# rcParams deprecated and automatically mapped to another key. 

596# Values are tuples of (version, new_name, f_old2new, f_new2old). 

597_deprecated_map = {} 

598# rcParams deprecated; some can manually be mapped to another key. 

599# Values are tuples of (version, new_name_or_None). 

600_deprecated_ignore_map = {} 

601# rcParams deprecated; can use None to suppress warnings; remain actually 

602# listed in the rcParams. 

603# Values are tuples of (version,) 

604_deprecated_remain_as_none = {} 

605 

606 

607@_docstring.Substitution( 

608 "\n".join(map("- {}".format, sorted(rcsetup._validators, key=str.lower))) 

609) 

610class RcParams(MutableMapping, dict): 

611 """ 

612 A dictionary object including validation. 

613 

614 Validating functions are defined and associated with rc parameters in 

615 :mod:`matplotlib.rcsetup`. 

616 

617 The list of rcParams is: 

618 

619 %s 

620 

621 See Also 

622 -------- 

623 :ref:`customizing-with-matplotlibrc-files` 

624 """ 

625 

626 validate = rcsetup._validators 

627 

628 # validate values on the way in 

629 def __init__(self, *args, **kwargs): 

630 self.update(*args, **kwargs) 

631 

632 def __setitem__(self, key, val): 

633 try: 

634 if key in _deprecated_map: 

635 version, alt_key, alt_val, inverse_alt = _deprecated_map[key] 

636 _api.warn_deprecated( 

637 version, name=key, obj_type="rcparam", alternative=alt_key) 

638 key = alt_key 

639 val = alt_val(val) 

640 elif key in _deprecated_remain_as_none and val is not None: 

641 version, = _deprecated_remain_as_none[key] 

642 _api.warn_deprecated(version, name=key, obj_type="rcparam") 

643 elif key in _deprecated_ignore_map: 

644 version, alt_key = _deprecated_ignore_map[key] 

645 _api.warn_deprecated( 

646 version, name=key, obj_type="rcparam", alternative=alt_key) 

647 return 

648 elif key == 'backend': 

649 if val is rcsetup._auto_backend_sentinel: 

650 if 'backend' in self: 

651 return 

652 try: 

653 cval = self.validate[key](val) 

654 except ValueError as ve: 

655 raise ValueError(f"Key {key}: {ve}") from None 

656 dict.__setitem__(self, key, cval) 

657 except KeyError as err: 

658 raise KeyError( 

659 f"{key} is not a valid rc parameter (see rcParams.keys() for " 

660 f"a list of valid parameters)") from err 

661 

662 def __getitem__(self, key): 

663 if key in _deprecated_map: 

664 version, alt_key, alt_val, inverse_alt = _deprecated_map[key] 

665 _api.warn_deprecated( 

666 version, name=key, obj_type="rcparam", alternative=alt_key) 

667 return inverse_alt(dict.__getitem__(self, alt_key)) 

668 

669 elif key in _deprecated_ignore_map: 

670 version, alt_key = _deprecated_ignore_map[key] 

671 _api.warn_deprecated( 

672 version, name=key, obj_type="rcparam", alternative=alt_key) 

673 return dict.__getitem__(self, alt_key) if alt_key else None 

674 

675 # In theory, this should only ever be used after the global rcParams 

676 # has been set up, but better be safe e.g. in presence of breakpoints. 

677 elif key == "backend" and self is globals().get("rcParams"): 

678 val = dict.__getitem__(self, key) 

679 if val is rcsetup._auto_backend_sentinel: 

680 from matplotlib import pyplot as plt 

681 plt.switch_backend(rcsetup._auto_backend_sentinel) 

682 

683 return dict.__getitem__(self, key) 

684 

685 def _get_backend_or_none(self): 

686 """Get the requested backend, if any, without triggering resolution.""" 

687 backend = dict.__getitem__(self, "backend") 

688 return None if backend is rcsetup._auto_backend_sentinel else backend 

689 

690 def __repr__(self): 

691 class_name = self.__class__.__name__ 

692 indent = len(class_name) + 1 

693 with _api.suppress_matplotlib_deprecation_warning(): 

694 repr_split = pprint.pformat(dict(self), indent=1, 

695 width=80 - indent).split('\n') 

696 repr_indented = ('\n' + ' ' * indent).join(repr_split) 

697 return '{}({})'.format(class_name, repr_indented) 

698 

699 def __str__(self): 

700 return '\n'.join(map('{0[0]}: {0[1]}'.format, sorted(self.items()))) 

701 

702 def __iter__(self): 

703 """Yield sorted list of keys.""" 

704 with _api.suppress_matplotlib_deprecation_warning(): 

705 yield from sorted(dict.__iter__(self)) 

706 

707 def __len__(self): 

708 return dict.__len__(self) 

709 

710 def find_all(self, pattern): 

711 """ 

712 Return the subset of this RcParams dictionary whose keys match, 

713 using :func:`re.search`, the given ``pattern``. 

714 

715 .. note:: 

716 

717 Changes to the returned dictionary are *not* propagated to 

718 the parent RcParams dictionary. 

719 

720 """ 

721 pattern_re = re.compile(pattern) 

722 return RcParams((key, value) 

723 for key, value in self.items() 

724 if pattern_re.search(key)) 

725 

726 def copy(self): 

727 """Copy this RcParams instance.""" 

728 rccopy = RcParams() 

729 for k in self: # Skip deprecations and revalidation. 

730 dict.__setitem__(rccopy, k, dict.__getitem__(self, k)) 

731 return rccopy 

732 

733 

734def rc_params(fail_on_error=False): 

735 """Construct a `RcParams` instance from the default Matplotlib rc file.""" 

736 return rc_params_from_file(matplotlib_fname(), fail_on_error) 

737 

738 

739@_api.deprecated("3.5") 

740def is_url(filename): 

741 """Return whether *filename* is an http, https, ftp, or file URL path.""" 

742 return __getattr__("URL_REGEX").match(filename) is not None 

743 

744 

745@functools.lru_cache() 

746def _get_ssl_context(): 

747 try: 

748 import certifi 

749 except ImportError: 

750 _log.debug("Could not import certifi.") 

751 return None 

752 import ssl 

753 return ssl.create_default_context(cafile=certifi.where()) 

754 

755 

756@contextlib.contextmanager 

757def _open_file_or_url(fname): 

758 if (isinstance(fname, str) 

759 and fname.startswith(('http://', 'https://', 'ftp://', 'file:'))): 

760 import urllib.request 

761 ssl_ctx = _get_ssl_context() 

762 if ssl_ctx is None: 

763 _log.debug( 

764 "Could not get certifi ssl context, https may not work." 

765 ) 

766 with urllib.request.urlopen(fname, context=ssl_ctx) as f: 

767 yield (line.decode('utf-8') for line in f) 

768 else: 

769 fname = os.path.expanduser(fname) 

770 with open(fname, encoding='utf-8') as f: 

771 yield f 

772 

773 

774def _rc_params_in_file(fname, transform=lambda x: x, fail_on_error=False): 

775 """ 

776 Construct a `RcParams` instance from file *fname*. 

777 

778 Unlike `rc_params_from_file`, the configuration class only contains the 

779 parameters specified in the file (i.e. default values are not filled in). 

780 

781 Parameters 

782 ---------- 

783 fname : path-like 

784 The loaded file. 

785 transform : callable, default: the identity function 

786 A function called on each individual line of the file to transform it, 

787 before further parsing. 

788 fail_on_error : bool, default: False 

789 Whether invalid entries should result in an exception or a warning. 

790 """ 

791 import matplotlib as mpl 

792 rc_temp = {} 

793 with _open_file_or_url(fname) as fd: 

794 try: 

795 for line_no, line in enumerate(fd, 1): 

796 line = transform(line) 

797 strippedline = cbook._strip_comment(line) 

798 if not strippedline: 

799 continue 

800 tup = strippedline.split(':', 1) 

801 if len(tup) != 2: 

802 _log.warning('Missing colon in file %r, line %d (%r)', 

803 fname, line_no, line.rstrip('\n')) 

804 continue 

805 key, val = tup 

806 key = key.strip() 

807 val = val.strip() 

808 if val.startswith('"') and val.endswith('"'): 

809 val = val[1:-1] # strip double quotes 

810 if key in rc_temp: 

811 _log.warning('Duplicate key in file %r, line %d (%r)', 

812 fname, line_no, line.rstrip('\n')) 

813 rc_temp[key] = (val, line, line_no) 

814 except UnicodeDecodeError: 

815 _log.warning('Cannot decode configuration file %r as utf-8.', 

816 fname) 

817 raise 

818 

819 config = RcParams() 

820 

821 for key, (val, line, line_no) in rc_temp.items(): 

822 if key in rcsetup._validators: 

823 if fail_on_error: 

824 config[key] = val # try to convert to proper type or raise 

825 else: 

826 try: 

827 config[key] = val # try to convert to proper type or skip 

828 except Exception as msg: 

829 _log.warning('Bad value in file %r, line %d (%r): %s', 

830 fname, line_no, line.rstrip('\n'), msg) 

831 elif key in _deprecated_ignore_map: 

832 version, alt_key = _deprecated_ignore_map[key] 

833 _api.warn_deprecated( 

834 version, name=key, alternative=alt_key, obj_type='rcparam', 

835 addendum="Please update your matplotlibrc.") 

836 else: 

837 # __version__ must be looked up as an attribute to trigger the 

838 # module-level __getattr__. 

839 version = ('main' if '.post' in mpl.__version__ 

840 else f'v{mpl.__version__}') 

841 _log.warning(""" 

842Bad key %(key)s in file %(fname)s, line %(line_no)s (%(line)r) 

843You probably need to get an updated matplotlibrc file from 

844https://github.com/matplotlib/matplotlib/blob/%(version)s/matplotlibrc.template 

845or from the matplotlib source distribution""", 

846 dict(key=key, fname=fname, line_no=line_no, 

847 line=line.rstrip('\n'), version=version)) 

848 return config 

849 

850 

851def rc_params_from_file(fname, fail_on_error=False, use_default_template=True): 

852 """ 

853 Construct a `RcParams` from file *fname*. 

854 

855 Parameters 

856 ---------- 

857 fname : str or path-like 

858 A file with Matplotlib rc settings. 

859 fail_on_error : bool 

860 If True, raise an error when the parser fails to convert a parameter. 

861 use_default_template : bool 

862 If True, initialize with default parameters before updating with those 

863 in the given file. If False, the configuration class only contains the 

864 parameters specified in the file. (Useful for updating dicts.) 

865 """ 

866 config_from_file = _rc_params_in_file(fname, fail_on_error=fail_on_error) 

867 

868 if not use_default_template: 

869 return config_from_file 

870 

871 with _api.suppress_matplotlib_deprecation_warning(): 

872 config = RcParams({**rcParamsDefault, **config_from_file}) 

873 

874 if "".join(config['text.latex.preamble']): 

875 _log.info(""" 

876***************************************************************** 

877You have the following UNSUPPORTED LaTeX preamble customizations: 

878%s 

879Please do not ask for support with these customizations active. 

880***************************************************************** 

881""", '\n'.join(config['text.latex.preamble'])) 

882 _log.debug('loaded rc file %s', fname) 

883 

884 return config 

885 

886 

887# When constructing the global instances, we need to perform certain updates 

888# by explicitly calling the superclass (dict.update, dict.items) to avoid 

889# triggering resolution of _auto_backend_sentinel. 

890rcParamsDefault = _rc_params_in_file( 

891 cbook._get_data_path("matplotlibrc"), 

892 # Strip leading comment. 

893 transform=lambda line: line[1:] if line.startswith("#") else line, 

894 fail_on_error=True) 

895dict.update(rcParamsDefault, rcsetup._hardcoded_defaults) 

896# Normally, the default matplotlibrc file contains *no* entry for backend (the 

897# corresponding line starts with ##, not #; we fill on _auto_backend_sentinel 

898# in that case. However, packagers can set a different default backend 

899# (resulting in a normal `#backend: foo` line) in which case we should *not* 

900# fill in _auto_backend_sentinel. 

901dict.setdefault(rcParamsDefault, "backend", rcsetup._auto_backend_sentinel) 

902rcParams = RcParams() # The global instance. 

903dict.update(rcParams, dict.items(rcParamsDefault)) 

904dict.update(rcParams, _rc_params_in_file(matplotlib_fname())) 

905rcParamsOrig = rcParams.copy() 

906with _api.suppress_matplotlib_deprecation_warning(): 

907 # This also checks that all rcParams are indeed listed in the template. 

908 # Assigning to rcsetup.defaultParams is left only for backcompat. 

909 defaultParams = rcsetup.defaultParams = { 

910 # We want to resolve deprecated rcParams, but not backend... 

911 key: [(rcsetup._auto_backend_sentinel if key == "backend" else 

912 rcParamsDefault[key]),