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

""" 

This is an object-oriented plotting library. 

A procedural interface is provided by the companion pyplot module, 

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

import matplotlib.pyplot as plt 

or using ipython:: 

ipython 

at your terminal, followed by:: 

In [1]: %matplotlib 

In [2]: import matplotlib.pyplot as plt 

at the ipython shell prompt. 

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

encouraged when programming; pyplot is primarily for working 

interactively. The 

exceptions are the pyplot commands :func:`~matplotlib.pyplot.figure`, 

:func:`~matplotlib.pyplot.subplot`, 

:func:`~matplotlib.pyplot.subplots`, and 

:func:`~pyplot.savefig`, which can greatly simplify scripting. 

Modules include: 

:mod:`matplotlib.axes` 

defines the :class:`~matplotlib.axes.Axes` class. Most pyplot 

commands are wrappers for :class:`~matplotlib.axes.Axes` 

methods. The axes module is the highest level of OO access to 

the library. 

:mod:`matplotlib.figure` 

defines the :class:`~matplotlib.figure.Figure` class. 

:mod:`matplotlib.artist` 

defines the :class:`~matplotlib.artist.Artist` base class for 

all classes that draw things. 

:mod:`matplotlib.lines` 

defines the :class:`~matplotlib.lines.Line2D` class for 

drawing lines and markers 

:mod:`matplotlib.patches` 

defines classes for drawing polygons 

:mod:`matplotlib.text` 

defines the :class:`~matplotlib.text.Text`, 

:class:`~matplotlib.text.TextWithDash`, and 

:class:`~matplotlib.text.Annotate` classes 

:mod:`matplotlib.image` 

defines the :class:`~matplotlib.image.AxesImage` and 

:class:`~matplotlib.image.FigureImage` classes 

:mod:`matplotlib.collections` 

classes for efficient drawing of groups of lines or polygons 

:mod:`matplotlib.colors` 

classes for interpreting color specifications and for making 

colormaps 

:mod:`matplotlib.cm` 

colormaps and the :class:`~matplotlib.image.ScalarMappable` 

mixin class for providing color mapping functionality to other 

classes 

:mod:`matplotlib.ticker` 

classes for calculating tick mark locations and for formatting 

tick labels 

:mod:`matplotlib.backends` 

a subpackage with modules for various gui libraries and output 

formats 

The base matplotlib namespace includes: 

:data:`~matplotlib.rcParams` 

a global dictionary of default configuration settings. It is 

initialized by code which may be overridden by a matplotlibrc 

file. 

:func:`~matplotlib.rc` 

a function for setting groups of rcParams values 

:func:`~matplotlib.use` 

a function for setting the matplotlib backend. If used, this 

function must be called immediately after importing matplotlib 

for the first time. In particular, it must be called 

**before** importing pyplot (if pyplot is imported). 

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

developed and maintained by a host of others. 

Occasionally the internal documentation (python docstrings) will refer 

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

""" 

# NOTE: This file must remain Python 2 compatible for the foreseeable future, 

# to ensure that we error out properly for existing editable installs. 

import sys 

if sys.version_info < (3, 5): # noqa: E402 

raise ImportError(""" 

Matplotlib 3.0+ does not support Python 2.x, 3.0, 3.1, 3.2, 3.3, or 3.4. 

Beginning with Matplotlib 3.0, Python 3.5 and above is required. 

See Matplotlib `INSTALL.rst` file for more information: 

https://github.com/matplotlib/matplotlib/blob/master/INSTALL.rst 

""") 

import atexit 

from collections.abc import MutableMapping 

import contextlib 

import distutils.version 

import functools 

import io 

import importlib 

import inspect 

from inspect import Parameter 

import locale 

import logging 

import os 

from pathlib import Path 

import pprint 

import re 

import shutil 

import stat 

import subprocess 

import tempfile 

import urllib.request 

import warnings 

# cbook must import matplotlib only within function 

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

from . import cbook, rcsetup 

from matplotlib.cbook import ( 

MatplotlibDeprecationWarning, dedent, get_label, sanitize_sequence) 

from matplotlib.cbook import mplDeprecation # deprecated 

from matplotlib.rcsetup import defaultParams, validate_backend, cycler 

import numpy 

# Get the version from the _version.py versioneer file. For a git checkout, 

# this is computed based on the number of commits since the last tag. 

from ._version import get_versions 

__version__ = str(get_versions()['version']) 

del get_versions 

_log = logging.getLogger(__name__) 

__version__numpy__ = '1.10.0' # minimum required numpy version 

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

Author = {Hunter, J. D.}, 

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

Journal = {Computing In Science \& Engineering}, 

Volume = {9}, 

Number = {3}, 

Pages = {90--95}, 

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

for application development, interactive scripting, and 

publication-quality image generation across user 

interfaces and operating systems.}, 

publisher = {IEEE COMPUTER SOC}, 

year = 2007 

}""" 

def compare_versions(a, b): 

"return True if a is greater than or equal to b" 

if isinstance(a, bytes): 

cbook.warn_deprecated( 

"3.0", "compare_version arguments should be strs.") 

a = a.decode('ascii') 

if isinstance(b, bytes): 

cbook.warn_deprecated( 

"3.0", "compare_version arguments should be strs.") 

b = b.decode('ascii') 

if a: 

a = distutils.version.LooseVersion(a) 

b = distutils.version.LooseVersion(b) 

return a >= b 

else: 

return False 

try: 

import dateutil 

except ImportError: 

raise ImportError("Matplotlib requires dateutil") 

try: 

import pyparsing 

except ImportError: 

raise ImportError("Matplotlib requires pyparsing") 

else: 

if not compare_versions(pyparsing.__version__, '2.0.1'): 

raise ImportError( 

"Matplotlib requires pyparsing>=2.0.1; you have %s" 

% pyparsing.__version__) 

if not compare_versions(numpy.__version__, __version__numpy__): 

raise ImportError( 

"Matplotlib requires numpy>=%s; you have %s" % ( 

__version__numpy__, numpy.__version__)) 

if not hasattr(sys, 'argv'): # for modpython 

sys.argv = ['modpython'] 

_verbose_msg = """\ 

matplotlib.verbose is deprecated; 

Command line argument --verbose-LEVEL is deprecated. 

This functionality is now provided by the standard 

python logging library. To get more (or less) logging output: 

import logging 

logger = logging.getLogger('matplotlib') 

logger.set_level(logging.INFO)""" 

def _set_logger_verbose_level(level_str='silent', file_str='sys.stdout'): 

""" 

Use a --verbose-LEVEL level to set the logging level: 

""" 

levelmap = {'silent': logging.WARNING, 'helpful': logging.INFO, 

'debug': logging.DEBUG, 'debug-annoying': logging.DEBUG, 

'info': logging.INFO, 'warning': logging.WARNING} 

# Check that current state of logger isn't already more verbose 

# than the requested level. If it is more verbose, then leave more 

# verbose. 

newlev = levelmap[level_str] 

oldlev = _log.getEffectiveLevel() 

if newlev < oldlev: 

_log.setLevel(newlev) 

std = { 

'sys.stdout': sys.stdout, 

'sys.stderr': sys.stderr, 

} 

if file_str in std: 

fileo = std[file_str] 

else: 

fileo = sys.stdout 

try: 

fileo = open(file_str, 'w') 

# if this fails, we will just write to stdout 

except IOError: 

warnings.warn('could not open log file "{0}"' 

'for writing. Check your ' 

'matplotlibrc'.format(file_str)) 

console = logging.StreamHandler(fileo) 

console.setLevel(newlev) 

_log.addHandler(console) 

def _parse_commandline(): 

""" 

Check for --verbose-LEVEL type command line arguments and 

set logging level appropriately. 

""" 

levels = ('silent', 'helpful', 'debug', 'debug-annoying', 

'info', 'warning') 

for arg in sys.argv[1:]: 

if arg.startswith('--verbose-'): 

level_str = arg[10:] 

# If it doesn't match one of ours, then don't even 

# bother noting it, we are just a 3rd-party library 

# to somebody else's script. 

if level_str in levels: 

_set_logger_verbose_level(level_str) 

_parse_commandline() 

class Verbose(object): 

""" 

A class to handle reporting. Set the fileo attribute to any file 

instance to handle the output. Default is sys.stdout 

""" 

levels = ('silent', 'helpful', 'debug', 'debug-annoying') 

vald = {level: i for i, level in enumerate(levels)} 

# parse the verbosity from the command line; flags look like 

# --verbose-silent or --verbose-helpful 

_commandLineVerbose = None 

for arg in sys.argv[1:]: 

if not arg.startswith('--verbose-'): 

continue 

level_str = arg[10:] 

# If it doesn't match one of ours, then don't even 

# bother noting it, we are just a 3rd-party library 

# to somebody else's script. 

if level_str in levels: 

_commandLineVerbose = level_str 

@cbook.deprecated("2.2", message=_verbose_msg) 

def __init__(self): 

self.set_level('silent') 

self.fileo = sys.stdout 

@cbook.deprecated("2.2", message=_verbose_msg) 

def set_level(self, level): 

'set the verbosity to one of the Verbose.levels strings' 

if self._commandLineVerbose is not None: 

level = self._commandLineVerbose 

if level not in self.levels: 

warnings.warn('matplotlib: unrecognized --verbose-* string "%s".' 

' Legal values are %s' % (level, self.levels)) 

else: 

self.level = level 

@cbook.deprecated("2.2", message=_verbose_msg) 

def set_fileo(self, fname): 

std = { 

'sys.stdout': sys.stdout, 

'sys.stderr': sys.stderr, 

} 

if fname in std: 

self.fileo = std[fname] 

else: 

try: 

fileo = open(fname, 'w') 

except IOError: 

raise ValueError('Verbose object could not open log file "{0}"' 

' for writing.\nCheck your matplotlibrc ' 

'verbose.fileo setting'.format(fname)) 

else: 

self.fileo = fileo 

@cbook.deprecated("2.2", message=_verbose_msg) 

def report(self, s, level='helpful'): 

""" 

print message s to self.fileo if self.level>=level. Return 

value indicates whether a message was issued 

""" 

if self.ge(level): 

print(s, file=self.fileo) 

return True 

return False 

@cbook.deprecated("2.2", message=_verbose_msg) 

def wrap(self, fmt, func, level='helpful', always=True): 

""" 

return a callable function that wraps func and reports it 

output through the verbose handler if current verbosity level 

is higher than level 

if always is True, the report will occur on every function 

call; otherwise only on the first time the function is called 

""" 

assert callable(func) 

def wrapper(*args, **kwargs): 

ret = func(*args, **kwargs) 

if (always or not wrapper._spoke): 

spoke = self.report(fmt % ret, level) 

if not wrapper._spoke: 

wrapper._spoke = spoke 

return ret 

wrapper._spoke = False 

wrapper.__doc__ = func.__doc__ 

return wrapper 

@cbook.deprecated("2.2", message=_verbose_msg) 

def ge(self, level): 

'return true if self.level is >= level' 

return self.vald[self.level] >= self.vald[level] 

with warnings.catch_warnings(): 

warnings.simplefilter("ignore") 

verbose = Verbose() 

def _logged_cached(fmt, func=None): 

""" 

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

After :: 

@_logged_cached(fmt) 

def func(): ... 

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

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

return that value. 

""" 

if func is None: # Return the actual decorator. 

return functools.partial(_logged_cached, fmt) 

called = False 

ret = None 

@functools.wraps(func) 

def wrapper(): 

nonlocal called, ret 

if not called: 

ret = func() 

called = True 

_log.debug(fmt, ret) 

return ret 

return wrapper 

def checkdep_dvipng(): 

try: 

s = subprocess.Popen(['dvipng', '-version'], 

stdout=subprocess.PIPE, 

stderr=subprocess.PIPE) 

stdout, stderr = s.communicate() 

line = stdout.decode('ascii').split('\n')[1] 

v = line.split()[-1] 

return v 

except (IndexError, ValueError, OSError): 

return None 

def checkdep_ghostscript(): 

if checkdep_ghostscript.executable is None: 

if sys.platform == 'win32': 

# mgs is the name in miktex 

gs_execs = ['gswin32c', 'gswin64c', 'mgs', 'gs'] 

else: 

gs_execs = ['gs'] 

for gs_exec in gs_execs: 

try: 

s = subprocess.Popen( 

[gs_exec, '--version'], stdout=subprocess.PIPE, 

stderr=subprocess.PIPE) 

stdout, stderr = s.communicate() 

if s.returncode == 0: 

v = stdout[:-1].decode('ascii') 

checkdep_ghostscript.executable = gs_exec 

checkdep_ghostscript.version = v 

except (IndexError, ValueError, OSError): 

pass 

return checkdep_ghostscript.executable, checkdep_ghostscript.version 

checkdep_ghostscript.executable = None 

checkdep_ghostscript.version = None 

def checkdep_pdftops(): 

try: 

s = subprocess.Popen(['pdftops', '-v'], stdout=subprocess.PIPE, 

stderr=subprocess.PIPE) 

stdout, stderr = s.communicate() 

lines = stderr.decode('ascii').split('\n') 

for line in lines: 

if 'version' in line: 

v = line.split()[-1] 

return v 

except (IndexError, ValueError, UnboundLocalError, OSError): 

return None 

def checkdep_inkscape(): 

if checkdep_inkscape.version is None: 

try: 

s = subprocess.Popen(['inkscape', '-V'], 

stdout=subprocess.PIPE, 

stderr=subprocess.PIPE) 

stdout, stderr = s.communicate() 

lines = stdout.decode('ascii').split('\n') 

for line in lines: 

if 'Inkscape' in line: 

v = line.split()[1] 

break 

checkdep_inkscape.version = v 

except (IndexError, ValueError, UnboundLocalError, OSError): 

pass 

return checkdep_inkscape.version 

checkdep_inkscape.version = None 

def checkdep_ps_distiller(s): 

if not s: 

return False 

flag = True 

gs_req = '8.60' 

gs_exec, gs_v = checkdep_ghostscript() 

if not compare_versions(gs_v, gs_req): 

flag = False 

warnings.warn(('matplotlibrc ps.usedistiller option can not be used ' 

'unless ghostscript-%s or later is installed on your ' 

'system') % gs_req) 

if s == 'xpdf': 

pdftops_req = '3.0' 

pdftops_req_alt = '0.9' # poppler version numbers, ugh 

pdftops_v = checkdep_pdftops() 

if compare_versions(pdftops_v, pdftops_req): 

pass 

elif (compare_versions(pdftops_v, pdftops_req_alt) and not 

compare_versions(pdftops_v, '1.0')): 

pass 

else: 

flag = False 

warnings.warn(('matplotlibrc ps.usedistiller can not be set to ' 

'xpdf unless xpdf-%s or later is installed on ' 

'your system') % pdftops_req) 

if flag: 

return s 

else: 

return False 

def checkdep_usetex(s): 

if not s: 

return False 

gs_req = '9.00' 

dvipng_req = '1.6' 

flag = True 

if shutil.which("tex") is None: 

flag = False 

warnings.warn('matplotlibrc text.usetex option can not be used unless ' 

'TeX is installed on your system') 

dvipng_v = checkdep_dvipng() 

if not compare_versions(dvipng_v, dvipng_req): 

flag = False 

warnings.warn('matplotlibrc text.usetex can not be used with *Agg ' 

'backend unless dvipng-%s or later is installed on ' 

'your system' % dvipng_req) 

gs_exec, gs_v = checkdep_ghostscript() 

if not compare_versions(gs_v, gs_req): 

flag = False 

warnings.warn('matplotlibrc text.usetex can not be used unless ' 

'ghostscript-%s or later is installed on your system' 

% gs_req) 

return flag 

@_logged_cached('$HOME=%s') 

def get_home(): 

""" 

Return the user's home directory. 

If the user's home directory cannot be found, return None. 

""" 

try: 

return str(Path.home()) 

except Exception: 

return None 

def _create_tmp_config_dir(): 

""" 

If the config directory can not be created, create a temporary directory. 

""" 

configdir = os.environ['MPLCONFIGDIR'] = ( 

tempfile.mkdtemp(prefix='matplotlib-')) 

atexit.register(shutil.rmtree, configdir) 

return configdir 

def _get_xdg_config_dir(): 

""" 

Returns the XDG configuration directory, according to the `XDG 

base directory spec 

<http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_. 

""" 

return (os.environ.get('XDG_CONFIG_HOME') 

or (str(Path(get_home(), ".config")) 

if get_home() 

else None)) 

def _get_xdg_cache_dir(): 

""" 

Returns the XDG cache directory, according to the `XDG 

base directory spec 

<http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_. 

""" 

return (os.environ.get('XDG_CACHE_HOME') 

or (str(Path(get_home(), ".cache")) 

if get_home() 

else None)) 

def _get_config_or_cache_dir(xdg_base): 

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

if configdir: 

configdir = Path(configdir).resolve() 

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

configdir = Path(xdg_base, "matplotlib") 

elif get_home(): 

configdir = Path(get_home(), ".matplotlib") 

else: 

configdir = None 

if configdir: 

try: 

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

except OSError: 

pass 

else: 

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

return str(configdir) 

return _create_tmp_config_dir() 

@_logged_cached('CONFIGDIR=%s') 

def get_configdir(): 

""" 

Return the string representing the configuration directory. 

The directory is chosen as follows: 

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

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

`$XDG_CONFIG_HOME`, if defined, or `$HOME/.config`. 

2b. On other platforms, choose `$HOME/.matplotlib`. 

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

configuration directory. 

4. If possible, create a temporary directory, and use it as the 

configuration directory. 

5. A writable directory could not be found or created; return None. 

""" 

return _get_config_or_cache_dir(_get_xdg_config_dir()) 

@_logged_cached('CACHEDIR=%s') 

def get_cachedir(): 

""" 

Return the location of the cache directory. 

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

_get_config_dir, except using `$XDG_CACHE_HOME`/`~/.cache` instead. 

""" 

return _get_config_or_cache_dir(_get_xdg_cache_dir()) 

def _get_data_path(): 

'get the path to matplotlib data' 

if 'MATPLOTLIBDATA' in os.environ: 

path = os.environ['MATPLOTLIBDATA'] 

if not os.path.isdir(path): 

raise RuntimeError('Path in environment MATPLOTLIBDATA not a ' 

'directory') 

return path 

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

def get_candidate_paths(): 

yield Path(__file__).with_name('mpl-data') 

# setuptools' namespace_packages may highjack this init file 

# so need to try something known to be in Matplotlib, not basemap. 

import matplotlib.afm 

yield Path(matplotlib.afm.__file__).with_name('mpl-data') 

# py2exe zips pure python, so still need special check. 

if getattr(sys, 'frozen', None): 

yield Path(sys.executable).with_name('mpl-data') 

# Try again assuming we need to step up one more directory. 

yield Path(sys.executable).parent.with_name('mpl-data') 

# Try again assuming sys.path[0] is a dir not a exe. 

yield Path(sys.path[0]) / 'mpl-data' 

for path in get_candidate_paths(): 

if path.is_dir(): 

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] 

def get_py2exe_datafiles(): 

data_path = Path(get_data_path()) 

d = {} 

for path in filter(Path.is_file, data_path.glob("**/*")): 

(d.setdefault(str(path.parent.relative_to(data_path.parent)), []) 

.append(str(path))) 

return list(d.items()) 

def matplotlib_fname(): 

""" 

Get the location of the config file. 

The file location is determined in the following order 

- `$PWD/matplotlibrc` 

- `$MATPLOTLIBRC` if it is a file (or a named pipe, which can be created 

e.g. by process substitution) 

- `$MATPLOTLIBRC/matplotlibrc` 

- `$MPLCONFIGDIR/matplotlibrc` 

- On Linux, 

- `$XDG_CONFIG_HOME/matplotlib/matplotlibrc` (if 

$XDG_CONFIG_HOME is defined) 

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

$XDG_CONFIG_HOME is not defined) 

- On other platforms, 

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

- Lastly, it looks in `$MATPLOTLIBDATA/matplotlibrc` for a 

system-defined copy. 

""" 

def gen_candidates(): 

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

try: 

matplotlibrc = os.environ['MATPLOTLIBRC'] 

except KeyError: 

pass 

else: 

yield matplotlibrc 

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

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

yield '/etc/matplotlibrc' 

for fname in gen_candidates(): 

if os.path.exists(fname): 

st_mode = os.stat(fname).st_mode 

if stat.S_ISREG(st_mode) or stat.S_ISFIFO(st_mode): 

break 

# Return first candidate that is a file, or last candidate if none is 

# valid (in that case, a warning is raised at startup by `rc_params`). 

return fname 

# rcParams deprecated and automatically mapped to another key. 

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

_deprecated_map = {} 

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

# Values are tuples of (version, new_name_or_None). 

_deprecated_ignore_map = { 

'text.dvipnghack': ('2.1', None), 

'nbagg.transparent': ('2.2', 'figure.facecolor'), 

'plugins.directory': ('2.2', None), 

'pgf.debug': ('3.0', None), 

} 

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

# listed in the rcParams (not included in _all_deprecated). 

# Values are typles of (version,) 

_deprecated_remain_as_none = { 

'axes.hold': ('2.1',), 

'backend.qt4': ('2.2',), 

'backend.qt5': ('2.2',), 

'text.latex.unicode': ('3.0',), 

} 

_all_deprecated = {*_deprecated_map, *_deprecated_ignore_map} 

class RcParams(MutableMapping, dict): 

""" 

A dictionary object including validation 

validating functions are defined and associated with rc parameters in 

:mod:`matplotlib.rcsetup` 

""" 

validate = {key: converter 

for key, (default, converter) in defaultParams.items() 

if key not in _all_deprecated} 

@property 

@cbook.deprecated("3.0") 

def msg_depr(self): 

return "%s is deprecated and replaced with %s; please use the latter." 

@property 

@cbook.deprecated("3.0") 

def msg_depr_ignore(self): 

return "%s is deprecated and ignored. Use %s instead."