"""Miscallaneous utility functions for the psyplot package."""

# Disclaimer

# ----------

#

# Copyright (C) 2021 Helmholtz-Zentrum Hereon

# Copyright (C) 2020-2021 Helmholtz-Zentrum Geesthacht

# Copyright (C) 2016-2021 University of Lausanne

#

# This file is part of psyplot and is released under the GNU LGPL-3.O license.

# See COPYING and COPYING.LESSER in the root of the repository for full

# licensing details.

#

# This program is free software: you can redistribute it and/or modify

# it under the terms of the GNU Lesser General Public License version 3.0 as

# published by the Free Software Foundation.

#

# This program is distributed in the hope that it will be useful,

# but WITHOUT ANY WARRANTY; without even the implied warranty of

# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

# GNU LGPL-3.0 license for more details.

#

# You should have received a copy of the GNU LGPL-3.0 license

# along with this program. If not, see <https://www.gnu.org/licenses/>.

import sys

import re

import six

from difflib import get_close_matches

from itertools import chain

from psyplot.compat.pycompat import OrderedDict, filterfalse

from psyplot.docstring import dedent, docstrings

def plugin_entrypoints(group="psyplot", name="name"):

"""This utility function gets the entry points of the psyplot plugins"""

if sys.version_info[:2] > (3, 7):

from importlib.metadata import entry_points

try:

eps = entry_points(group=group, name=name)

except TypeError: # python<3.10

eps = [ep for ep in entry_points().get(group, [])

if ep.name == name]

else:

from pkg_resources import iter_entry_points

eps = iter_entry_points(group=group, name=name)

return eps

class DefaultOrderedDict(OrderedDict):

"""An ordered :class:`collections.defaultdict`

Taken from http://stackoverflow.com/a/6190500/562769"""

def __init__(self, default_factory=None, *a, **kw):

if (default_factory is not None and

not callable(default_factory)):

raise TypeError('first argument must be callable')

OrderedDict.__init__(self, *a, **kw)

self.default_factory = default_factory

def __getitem__(self, key):

try:

return OrderedDict.__getitem__(self, key)

except KeyError:

return self.__missing__(key)

def __missing__(self, key):

if self.default_factory is None:

raise KeyError(key)

self[key] = value = self.default_factory()

return value

def __reduce__(self):

if self.default_factory is None:

args = tuple()

else:

args = self.default_factory,

return type(self), args, None, None, self.items()

def copy(self):

"""Return a shallow copy of the dictionary"""

return self.__copy__()

def __copy__(self):

return type(self)(self.default_factory, self)

def __deepcopy__(self, memo):

import copy

return type(self)(self.default_factory,

copy.deepcopy(self.items()))

def __repr__(self):

return 'DefaultOrderedDict(%s, %s)' % (self.default_factory,

OrderedDict.__repr__(self))

class _TempBool(object):

"""Wrapper around a boolean defining an __enter__ and __exit__ method

Notes

-----

If you want to use this class as an instance property, rather use the

:func:`_temp_bool_prop` because this class as a descriptor is ment to be a

class descriptor"""

#: default boolean value for the :attr:`value` attribute

default = False

#: boolean value indicating whether there shall be a validation or not

value = False

def __init__(self, default=False):

"""

Parameters

----------

default: bool

value of the object"""

self.default = default

self.value = default

self._entered = []

def __enter__(self):

self.value = not self.default

self._entered.append(1)

def __exit__(self, type, value, tb):

self._entered.pop(-1)

if not self._entered:

self.value = self.default

if six.PY2:

def __nonzero__(self):

return self.value

else:

def __bool__(self):

return self.value

def __repr__(self):

return repr(bool(self))

def __str__(self):

return str(bool(self))

def __call__(self, value=None):

"""

Parameters

----------

value: bool or None

If None, the current value will be negated. Otherwise the current

value of this instance is set to the given `value`"""

if value is None:

self.value = not self.value

else:

self.value = value

def __get__(self, instance, owner):

return self

def __set__(self, instance, value):

self.value = value

def _temp_bool_prop(propname, doc="", default=False):

"""Creates a property that uses the :class:`_TempBool` class

Parameters

----------

propname: str

The attribute name to use. The _TempBool instance will be stored in the

``'_' + propname`` attribute of the corresponding instance

doc: str

The documentation of the property

default: bool

The default value of the _TempBool class"""

def getx(self):

if getattr(self, '_' + propname, None) is not None:

return getattr(self, '_' + propname)

else:

setattr(self, '_' + propname, _TempBool(default))

return getattr(self, '_' + propname)

def setx(self, value):

getattr(self, propname).value = bool(value)

def delx(self):

getattr(self, propname).value = default

return property(getx, setx, delx, doc)

def unique_everseen(iterable, key=None):

"""List unique elements, preserving order. Remember all elements ever seen.

Function taken from https://docs.python.org/2/library/itertools.html"""

# unique_everseen('AAAABBBCCDAABBB') --> A B C D

# unique_everseen('ABBCcAD', str.lower) --> A B C D

seen = set()

seen_add = seen.add

if key is None:

for element in filterfalse(seen.__contains__, iterable):

seen_add(element)

yield element

else:

for element in iterable:

k = key(element)

if k not in seen:

seen_add(k)

yield element

def is_remote_url(path):

patt = re.compile(r'^https?\://')

if not isinstance(path, six.string_types):

return all(map(patt.search, (s or '' for s in path)))

return bool(re.search(r'^https?\://', path))

@docstrings.get_sections(base='check_key', sections=['Parameters', 'Returns',

'Raises'])

@dedent

def check_key(key, possible_keys, raise_error=True,

name='formatoption keyword',

msg=("See show_fmtkeys function for possible formatopion "

"keywords"),

*args, **kwargs):

"""

Checks whether the key is in a list of possible keys

This function checks whether the given `key` is in `possible_keys` and if

not looks for similar sounding keys

Parameters

----------

key: str

Key to check

possible_keys: list of strings

a list of possible keys to use

raise_error: bool

If not True, a list of similar keys is returned

name: str

The name of the key that shall be used in the error message

msg: str

The additional message that shall be used if no close match to

key is found

*args, **kwargs

They are passed to the :func:`difflib.get_close_matches` function

(i.e. `n` to increase the number of returned similar keys and

`cutoff` to change the sensibility)

Returns

-------

str

The `key` if it is a valid string, else an empty string

list

A list of similar formatoption strings (if found)

str

An error message which includes

Raises

------

KeyError

If the key is not a valid formatoption and `raise_error` is True"""

if key not in possible_keys:

similarkeys = get_close_matches(key, possible_keys, *args, **kwargs)

if similarkeys:

msg = ('Unknown %s %s! Possible similiar '

'frasings are %s.') % (name, key, ', '.join(similarkeys))

else:

msg = ("Unknown %s %s! ") % (name, key) + msg

if not raise_error:

return '', similarkeys, msg

raise KeyError(msg)

else:

return key, [key], ''

def sort_kwargs(kwargs, *param_lists):

"""Function to sort keyword arguments and sort them into dictionaries

This function returns dictionaries that contain the keyword arguments

from `kwargs` corresponding given iterables in ``*params``

Parameters

----------

kwargs: dict

Original dictionary

``*param_lists``

iterables of strings, each standing for a possible key in kwargs

Returns

-------

list

len(params) + 1 dictionaries. Each dictionary contains the items of

`kwargs` corresponding to the specified list in ``*param_lists``. The

last dictionary contains the remaining items"""

return chain(

({key: kwargs.pop(key) for key in params.intersection(kwargs)}

for params in map(set, param_lists)), [kwargs])

def hashable(val):

"""Test if `val` is hashable and if not, get it's string representation

Parameters

----------

val: object

Any (possibly not hashable) python object

Returns

-------

val or string

The given `val` if it is hashable or it's string representation"""

if val is None:

return val

try:

hash(val)

except TypeError:

return repr(val)

else:

return val

@docstrings.get_sections(base='join_dicts')

def join_dicts(dicts, delimiter=None, keep_all=False):

"""Join multiple dictionaries into one

Parameters

----------

dicts: list of dict

A list of dictionaries

delimiter: str

The string that shall be used as the delimiter in case that there

are multiple values for one attribute in the arrays. If None, they

will be returned as sets

keep_all: bool

If True, all formatoptions are kept. Otherwise only the intersection

Returns

-------

dict

The combined dictionary"""

if not dicts:

return {}

if keep_all:

all_keys = set(chain(*(d.keys() for d in dicts)))

else:

all_keys = set(dicts[0])

for d in dicts[1:]:

all_keys.intersection_update(d)

ret = {}

for key in all_keys:

vals = {hashable(d.get(key, None)) for d in dicts} - {None}

if len(vals) == 1:

ret[key] = next(iter(vals))

elif delimiter is None:

ret[key] = vals

else:

ret[key] = delimiter.join(map(str, vals))

return ret

def is_iterable(iterable):

"""Test if an object is iterable

Parameters

----------

iterable: object

The object to test

Returns

-------

bool

True, if the object is an iterable object"""

try:

iter(iterable)

except TypeError:

return False

else:

return True