"""

A collection of utility functions and classes. Originally, many

(but not all) were from the Python Cookbook -- hence the name cbook.

This module is safe to import from anywhere within matplotlib;

it imports matplotlib only at runtime.

"""

from __future__ import (absolute_import, division, print_function,

unicode_literals)

import six

from six.moves import xrange, zip

from itertools import repeat

import datetime

import errno

from functools import reduce

import glob

import gzip

import io

import locale

import os

import re

import sys

import threading

import time

import traceback

import types

import warnings

from weakref import ref, WeakKeyDictionary

import numpy as np

import numpy.ma as ma

class MatplotlibDeprecationWarning(UserWarning):

"""

A class for issuing deprecation warnings for Matplotlib users.

In light of the fact that Python builtin DeprecationWarnings are ignored

by default as of Python 2.7 (see link below), this class was put in to

allow for the signaling of deprecation, but via UserWarnings which are not

ignored by default.

http://docs.python.org/dev/whatsnew/2.7.html#the-future-for-python-2-x

"""

pass

mplDeprecation = MatplotlibDeprecationWarning

def _generate_deprecation_message(since, message='', name='',

alternative='', pending=False,

obj_type='attribute'):

if not message:

altmessage = ''

if pending:

message = (

'The %(func)s %(obj_type)s will be deprecated in a '

'future version.')

else:

message = (

'The %(func)s %(obj_type)s was deprecated in version '

'%(since)s.')

if alternative:

altmessage = ' Use %s instead.' % alternative

message = ((message % {

'func': name,

'name': name,

'alternative': alternative,

'obj_type': obj_type,

'since': since}) +

altmessage)

return message

def warn_deprecated(

since, message='', name='', alternative='', pending=False,

obj_type='attribute'):

"""

Used to display deprecation warning in a standard way.

Parameters

------------

since : str

The release at which this API became deprecated.

message : str, optional

Override the default deprecation message. The format

specifier `%(func)s` may be used for the name of the function,

and `%(alternative)s` may be used in the deprecation message

to insert the name of an alternative to the deprecated

function. `%(obj_type)` may be used to insert a friendly name

for the type of object being deprecated.

name : str, optional

The name of the deprecated function; if not provided the name

is automatically determined from the passed in function,

though this is useful in the case of renamed functions, where

the new function is just assigned to the name of the

deprecated function. For example::

def new_function():

...

oldFunction = new_function

alternative : str, optional

An alternative function that the user may use in place of the

deprecated function. The deprecation warning will tell the user about

this alternative if provided.

pending : bool, optional

If True, uses a PendingDeprecationWarning instead of a

DeprecationWarning.

obj_type : str, optional

The object type being deprecated.

Examples

--------

Basic example::

# To warn of the deprecation of "matplotlib.name_of_module"

warn_deprecated('1.4.0', name='matplotlib.name_of_module',

obj_type='module')

"""

message = _generate_deprecation_message(

since, message, name, alternative, pending, obj_type)

warnings.warn(message, mplDeprecation, stacklevel=1)

def deprecated(since, message='', name='', alternative='', pending=False,

obj_type='function'):

"""

Decorator to mark a function as deprecated.

Parameters

------------

since : str

The release at which this API became deprecated. This is

required.

message : str, optional

Override the default deprecation message. The format

specifier `%(func)s` may be used for the name of the function,

and `%(alternative)s` may be used in the deprecation message

to insert the name of an alternative to the deprecated

function. `%(obj_type)` may be used to insert a friendly name

for the type of object being deprecated.

name : str, optional

The name of the deprecated function; if not provided the name

is automatically determined from the passed in function,

though this is useful in the case of renamed functions, where

the new function is just assigned to the name of the

deprecated function. For example::

def new_function():

...

oldFunction = new_function

alternative : str, optional

An alternative function that the user may use in place of the

deprecated function. The deprecation warning will tell the user about

this alternative if provided.

pending : bool, optional

If True, uses a PendingDeprecationWarning instead of a

DeprecationWarning.

Examples

--------

Basic example::

@deprecated('1.4.0')

def the_function_to_deprecate():

pass

"""

def deprecate(func, message=message, name=name, alternative=alternative,

pending=pending):

import functools

import textwrap

if isinstance(func, classmethod):

try:

func = func.__func__

except AttributeError:

# classmethods in Python2.6 and below lack the __func__

# attribute so we need to hack around to get it

method = func.__get__(None, object)

if hasattr(method, '__func__'):

func = method.__func__

elif hasattr(method, 'im_func'):

func = method.im_func

else:

# Nothing we can do really... just return the original

# classmethod

return func

is_classmethod = True

else:

is_classmethod = False

if not name:

name = func.__name__

message = _generate_deprecation_message(

since, message, name, alternative, pending, obj_type)

@functools.wraps(func)

def deprecated_func(*args, **kwargs):

warnings.warn(message, mplDeprecation, stacklevel=2)

return func(*args, **kwargs)

old_doc = deprecated_func.__doc__

if not old_doc:

old_doc = ''

old_doc = textwrap.dedent(old_doc).strip('\n')

message = message.strip()

new_doc = (('\n.. deprecated:: %(since)s'

'\n %(message)s\n\n' %

{'since': since, 'message': message}) + old_doc)

if not old_doc:

# This is to prevent a spurious 'unexected unindent' warning from

# docutils when the original docstring was blank.

new_doc += r'\ '

deprecated_func.__doc__ = new_doc

if is_classmethod:

deprecated_func = classmethod(deprecated_func)

return deprecated_func

return deprecate

# On some systems, locale.getpreferredencoding returns None,

# which can break unicode; and the sage project reports that

# some systems have incorrect locale specifications, e.g.,

# an encoding instead of a valid locale name. Another

# pathological case that has been reported is an empty string.

# On some systems, getpreferredencoding sets the locale, which has

# side effects. Passing False eliminates those side effects.

def unicode_safe(s):

import matplotlib

if isinstance(s, bytes):

try:

preferredencoding = locale.getpreferredencoding(

matplotlib.rcParams['axes.formatter.use_locale']).strip()

if not preferredencoding:

preferredencoding = None

except (ValueError, ImportError, AttributeError):

preferredencoding = None

if preferredencoding is None:

return six.text_type(s)

else:

return six.text_type(s, preferredencoding)

return s

class converter(object):

"""

Base class for handling string -> python type with support for

missing values

"""

def __init__(self, missing='Null', missingval=None):

self.missing = missing

self.missingval = missingval

def __call__(self, s):

if s == self.missing:

return self.missingval

return s

def is_missing(self, s):

return not s.strip() or s == self.missing

class tostr(converter):

'convert to string or None'

def __init__(self, missing='Null', missingval=''):

converter.__init__(self, missing=missing, missingval=missingval)

class todatetime(converter):

'convert to a datetime or None'

def __init__(self, fmt='%Y-%m-%d', missing='Null', missingval=None):

'use a :func:`time.strptime` format string for conversion'

converter.__init__(self, missing, missingval)

self.fmt = fmt

def __call__(self, s):

if self.is_missing(s):

return self.missingval

tup = time.strptime(s, self.fmt)

return datetime.datetime(*tup[:6])

class todate(converter):

'convert to a date or None'

def __init__(self, fmt='%Y-%m-%d', missing='Null', missingval=None):

'use a :func:`time.strptime` format string for conversion'

converter.__init__(self, missing, missingval)

self.fmt = fmt

def __call__(self, s):

if self.is_missing(s):

return self.missingval

tup = time.strptime(s, self.fmt)

return datetime.date(*tup[:3])

class tofloat(converter):

'convert to a float or None'

def __init__(self, missing='Null', missingval=None):

converter.__init__(self, missing)

self.missingval = missingval

def __call__(self, s):

if self.is_missing(s):

return self.missingval

return float(s)

class toint(converter):

'convert to an int or None'

def __init__(self, missing='Null', missingval=None):

converter.__init__(self, missing)

def __call__(self, s):

if self.is_missing(s):

return self.missingval

return int(s)

class _BoundMethodProxy(object):

'''

Our own proxy object which enables weak references to bound and unbound

methods and arbitrary callables. Pulls information about the function,

class, and instance out of a bound method. Stores a weak reference to the

instance to support garbage collection.

@organization: IBM Corporation

@copyright: Copyright (c) 2005, 2006 IBM Corporation

@license: The BSD License

Minor bugfixes by Michael Droettboom

'''

def __init__(self, cb):

try:

try:

self.inst = ref(cb.im_self)

except TypeError:

self.inst = None

if six.PY3:

self.func = cb.__func__

self.klass = cb.__self__.__class__

else:

self.func = cb.im_func

self.klass = cb.im_class

except AttributeError:

self.inst = None

self.func = cb

self.klass = None

def __getstate__(self):

d = self.__dict__.copy()

# de-weak reference inst

inst = d['inst']

if inst is not None:

d['inst'] = inst()

return d

def __setstate__(self, statedict):

self.__dict__ = statedict

inst = statedict['inst']

# turn inst back into a weakref

if inst is not None:

self.inst = ref(inst)

def __call__(self, *args, **kwargs):

'''

Proxy for a call to the weak referenced object. Take

arbitrary params to pass to the callable.

Raises `ReferenceError`: When the weak reference refers to

a dead object

'''

if self.inst is not None and self.inst() is None:

raise ReferenceError

elif self.inst is not None:

# build a new instance method with a strong reference to the

# instance

mtd = types.MethodType(self.func, self.inst())

else:

# not a bound method, just return the func

mtd = self.func

# invoke the callable and return the result

return mtd(*args, **kwargs)

def __eq__(self, other):

'''

Compare the held function and instance with that held by

another proxy.

'''

try:

if self.inst is None:

return self.func == other.func and other.inst is None

else:

return self.func == other.func and self.inst() == other.inst()

except Exception:

return False

def __ne__(self, other):

'''

Inverse of __eq__.

'''

return not self.__eq__(other)

class CallbackRegistry(object):

"""

Handle registering and disconnecting for a set of signals and

callbacks:

>>> def oneat(x):

... print('eat', x)

>>> def ondrink(x):

... print('drink', x)

>>> from matplotlib.cbook import CallbackRegistry

>>> callbacks = CallbackRegistry()

>>> id_eat = callbacks.connect('eat', oneat)

>>> id_drink = callbacks.connect('drink', ondrink)

>>> callbacks.process('drink', 123)

drink 123

>>> callbacks.process('eat', 456)

eat 456

>>> callbacks.process('be merry', 456) # nothing will be called

>>> callbacks.disconnect(id_eat)

>>> callbacks.process('eat', 456) # nothing will be called

In practice, one should always disconnect all callbacks when they

are no longer needed to avoid dangling references (and thus memory

leaks). However, real code in matplotlib rarely does so, and due

to its design, it is rather difficult to place this kind of code.

To get around this, and prevent this class of memory leaks, we

instead store weak references to bound methods only, so when the

destination object needs to die, the CallbackRegistry won't keep

it alive. The Python stdlib weakref module can not create weak

references to bound methods directly, so we need to create a proxy

object to handle weak references to bound methods (or regular free

functions). This technique was shared by Peter Parente on his

`"Mindtrove" blog

<http://mindtrove.info/articles/python-weak-references/>`_.

"""

def __init__(self, *args):

if len(args):

warn_deprecated(

'1.3',

message="CallbackRegistry no longer requires a list of "

"callback types. Ignoring arguments. *args will "

"be removed in 1.5")

self.callbacks = dict()

self._cid = 0

self._func_cid_map = {}

def __getstate__(self):

# We cannot currently pickle the callables in the registry, so

# return an empty dictionary.

return {}

def __setstate__(self, state):

# re-initialise an empty callback registry

self.__init__()

def connect(self, s, func):

"""

register *func* to be called when a signal *s* is generated

func will be called

"""

self._func_cid_map.setdefault(s, WeakKeyDictionary())

if func in self._func_cid_map[s]:

return self._func_cid_map[s][func]

self._cid += 1

cid = self._cid

self._func_cid_map[s][func] = cid

self.callbacks.setdefault(s, dict())

proxy = _BoundMethodProxy(func)

self.callbacks[s][cid] = proxy

return cid

def disconnect(self, cid):

"""

disconnect the callback registered with callback id *cid*

"""

for eventname, callbackd in list(six.iteritems(self.callbacks)):

try:

del callbackd[cid]

except KeyError:

continue

else:

for category, functions in list(

six.iteritems(self._func_cid_map)):

for function, value in list(six.iteritems(functions)):

if value == cid:

del functions[function]

return

def process(self, s, *args, **kwargs):

"""

process signal *s*. All of the functions registered to receive

callbacks on *s* will be called with *\*args* and *\*\*kwargs*

"""

if s in self.callbacks:

for cid, proxy in list(six.iteritems(self.callbacks[s])):

# Clean out dead references

if proxy.inst is not None and proxy.inst() is None:

del self.callbacks[s][cid]

else:

proxy(*args, **kwargs)

class Scheduler(threading.Thread):

"""

Base class for timeout and idle scheduling

"""

idlelock = threading.Lock()

id = 0

def __init__(self):

threading.Thread.__init__(self)

self.id = Scheduler.id

self._stopped = False

Scheduler.id += 1

self._stopevent = threading.Event()

def stop(self):

if self._stopped:

return

self._stopevent.set()

self.join()

self._stopped = True

class Timeout(Scheduler):

"""

Schedule recurring events with a wait time in seconds

"""

def __init__(self, wait, func):

Scheduler.__init__(self)

self.wait = wait

self.func = func

def run(self):

while not self._stopevent.isSet():

self._stopevent.wait(self.wait)

Scheduler.idlelock.acquire()

b = self.func(self)

Scheduler.idlelock.release()

if not b:

break

class Idle(Scheduler):

"""

Schedule callbacks when scheduler is idle

"""

# the prototype impl is a bit of a poor man's idle handler. It

# just implements a short wait time. But it will provide a

# placeholder for a proper impl ater

waittime = 0.05

def __init__(self, func):

Scheduler.__init__(self)

self.func = func

def run(self):

while not self._stopevent.isSet():

self._stopevent.wait(Idle.waittime)

Scheduler.idlelock.acquire()

b = self.func(self)

Scheduler.idlelock.release()

if not b:

break

class silent_list(list):

"""

override repr when returning a list of matplotlib artists to

prevent long, meaningless output. This is meant to be used for a

homogeneous list of a given type

"""

def __init__(self, type, seq=None):

self.type = type

if seq is not None:

self.extend(seq)

def __repr__(self):

return '<a list of %d %s objects>' % (len(self), self.type)

def __str__(self):

return repr(self)

def __getstate__(self):

# store a dictionary of this SilentList's state

return {'type': self.type, 'seq': self[:]}

def __setstate__(self, state):

self.type = state['type']

self.extend(state['seq'])

def strip_math(s):

'remove latex formatting from mathtext'

remove = (r'\mathdefault', r'\rm', r'\cal', r'\tt', r'\it', '\\', '{', '}')

s = s[1:-1]

for r in remove:

s = s.replace(r, '')

return s

class Bunch(object):

"""

Often we want to just collect a bunch of stuff together, naming each

item of the bunch; a dictionary's OK for that, but a small do- nothing

class is even handier, and prettier to use. Whenever you want to

group a few variables::

>>> point = Bunch(datum=2, squared=4, coord=12)

>>> point.datum

By: Alex Martelli

From: http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52308

"""

def __init__(self, **kwds):

self.__dict__.update(kwds)

def __repr__(self):

keys = six.iterkeys(self.__dict__)

return 'Bunch(%s)' % ', '.join(['%s=%s' % (k, self.__dict__[k])

for k

in keys])

def unique(x):

'Return a list of unique elements of *x*'

return list(six.iterkeys(dict([(val, 1) for val in x])))

def iterable(obj):

'return true if *obj* is iterable'

try:

iter(obj)

except TypeError:

return False

return True

def is_string_like(obj):

'Return True if *obj* looks like a string'

if isinstance(obj, six.string_types):

return True

# numpy strings are subclass of str, ma strings are not

if ma.isMaskedArray(obj):

if obj.ndim == 0 and obj.dtype.kind in 'SU':

return True

else:

return False

try:

obj + ''

except:

return False

return True

def is_sequence_of_strings(obj):

"""

Returns true if *obj* is iterable and contains strings

"""

if not iterable(obj):

return False

if is_string_like(obj):

return False

for o in obj:

if not is_string_like(o):

return False

return True

def is_writable_file_like(obj):

'return true if *obj* looks like a file object with a *write* method'

return hasattr(obj, 'write') and six.callable(obj.write)

def file_requires_unicode(x):

"""

Returns `True` if the given writable file-like object requires Unicode

to be written to it.

"""

try:

x.write(b'')

except TypeError:

return True

else:

return False

def is_scalar(obj):

'return true if *obj* is not string like and is not iterable'

return not is_string_like(obj) and not iterable(obj)

def is_numlike(obj):

'return true if *obj* looks like a number'

try:

obj + 1

except:

return False

else:

return True

def to_filehandle(fname, flag='rU', return_opened=False):

"""

*fname* can be a filename or a file handle. Support for gzipped

files is automatic, if the filename ends in .gz. *flag* is a

read/write flag for :func:`file`

"""

if is_string_like(fname):

if fname.endswith('.gz'):

# get rid of 'U' in flag for gzipped files.

flag = flag.replace('U', '')

fh = gzip.open(fname, flag)

elif fname.endswith('.bz2'):

# get rid of 'U' in flag for bz2 files

flag = flag.replace('U', '')

import bz2

fh = bz2.BZ2File(fname, flag)

else:

fh = open(fname, flag)

opened = True

elif hasattr(fname, 'seek'):

fh = fname

opened = False

else:

raise ValueError('fname must be a string or file handle')

if return_opened:

return fh, opened

return fh

def is_scalar_or_string(val):

"""Return whether the given object is a scalar or string like."""

return is_string_like(val) or not iterable(val)

def _string_to_bool(s):

if not is_string_like(s):

return s

if s == 'on':

return True

if s == 'off':

return False

raise ValueError("string argument must be either 'on' or 'off'")

def get_sample_data(fname, asfileobj=True):

"""

Return a sample data file. *fname* is a path relative to the

`mpl-data/sample_data` directory. If *asfileobj* is `True`

return a file object, otherwise just a file path.

Set the rc parameter examples.directory to the directory where we should

look, if sample_data files are stored in a location different than

default (which is 'mpl-data/sample_data` at the same level of 'matplotlib`

Python module files).

If the filename ends in .gz, the file is implicitly ungzipped.

"""

import matplotlib

if matplotlib.rcParams['examples.directory']:

root = matplotlib.rcParams['examples.directory']

else:

root = os.path.join(os.path.dirname(__file__),

"mpl-data", "sample_data")

path = os.path.join(root, fname)

if asfileobj:

if (os.path.splitext(fname)[-1].lower() in

('.csv', '.xrc', '.txt')):

mode = 'r'

else:

mode = 'rb'

base, ext = os.path.splitext(fname)

if ext == '.gz':

return gzip.open(path, mode)

else:

return open(path, mode)

else:

return path

def flatten(seq, scalarp=is_scalar_or_string):

"""

Returns a generator of flattened nested containers

For example:

>>> from matplotlib.cbook import flatten

>>> l = (('John', ['Hunter']), (1, 23), [[([42, (5, 23)], )]])

>>> print(list(flatten(l)))

['John', 'Hunter', 1, 23, 42, 5, 23]

By: Composite of Holger Krekel and Luther Blissett

From: http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/121294

and Recipe 1.12 in cookbook

"""

for item in seq:

if scalarp(item):

yield item

else:

for subitem in flatten(item, scalarp):

yield subitem

class Sorter(object):

"""

Sort by attribute or item

Example usage::

sort = Sorter()

list = [(1, 2), (4, 8), (0, 3)]

dict = [{'a': 3, 'b': 4}, {'a': 5, 'b': 2}, {'a': 0, 'b': 0},

{'a': 9, 'b': 9}]

sort(list) # default sort

sort(list, 1) # sort by index 1

sort(dict, 'a') # sort a list of dicts by key 'a'

"""

def _helper(self, data, aux, inplace):

aux.sort()

result = [data[i] for junk, i in aux]

if inplace:

data[:] = result

return result

def byItem(self, data, itemindex=None, inplace=1):

if itemindex is None:

if inplace:

data.sort()

result = data

else:

result = data[:]

result.sort()

return result

else:

aux = [(data[i][itemindex], i) for i in range(len(data))]

return self._helper(data, aux, inplace)

def byAttribute(self, data, attributename, inplace=1):

aux = [(getattr(data[i], attributename), i) for i in range(len(data))]

return self._helper(data, aux, inplace)

# a couple of handy synonyms

sort = byItem

__call__ = byItem

class Xlator(dict):

"""

All-in-one multiple-string-substitution class

Example usage::

text = "Larry Wall is the creator of Perl"

adict = {

"Larry Wall" : "Guido van Rossum",

"creator" : "Benevolent Dictator for Life",

"Perl" : "Python",

}

print multiple_replace(adict, text)

xlat = Xlator(adict)

print xlat.xlat(text)

"""

def _make_regex(self):

""" Build re object based on the keys of the current dictionary """

return re.compile("|".join(map(re.escape, list(six.iterkeys(self)))))

def __call__(self, match):

""" Handler invoked for each regex *match* """

return self[match.group(0)]

def xlat(self, text):

""" Translate *text*, returns the modified text. """

return self._make_regex().sub(self, text)

def soundex(name, len=4):

""" soundex module conforming to Odell-Russell algorithm """

# digits holds the soundex values for the alphabet

soundex_digits = '01230120022455012623010202'

sndx = ''

fc = ''

# Translate letters in name to soundex digits

for c in name.upper():

if c.isalpha():

if not fc:

fc = c # Remember first letter

d = soundex_digits[ord(c) - ord('A')]

# Duplicate consecutive soundex digits are skipped

if not sndx or (d != sndx[-1]):

sndx += d

# Replace first digit with first letter

sndx = fc + sndx[1:]

# Remove all 0s from the soundex code

sndx = sndx.replace('0', '')

# Return soundex code truncated or 0-padded to len characters

return (sndx + (len * '0'))[:len]

class Null(object):

""" Null objects always and reliably "do nothing." """

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

pass

def __call__(self, *args, **kwargs):

return self

def __str__(self):

return "Null()"

def __repr__(self):

return "Null()"

if six.PY3:

def __bool__(self):

return 0

else:

def __nonzero__(self):

return 0

def __getattr__(self, name):

return self

def __setattr__(self, name, value):

return self

def __delattr__(self, name):

return self

def mkdirs(newdir, mode=0o777):

"""

make directory *newdir* recursively, and set *mode*. Equivalent to ::

> mkdir -p NEWDIR

> chmod MODE NEWDIR

"""

try:

if not os.path.exists(newdir):

parts = os.path.split(newdir)

for i in range(1, len(parts) + 1):