forked from matplotlib/matplotlib
-
Notifications
You must be signed in to change notification settings - Fork 2
Expand file tree
/
Copy path__init__.py
More file actions
132 lines (108 loc) · 4.13 KB
/
Copy path__init__.py
File metadata and controls
132 lines (108 loc) · 4.13 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
"""
Helper functions for managing the Matplotlib API.
This documentation is only relevant for Matplotlib developers, not for users.
.. warning:
This module and its submodules are for internal use only. Do not use them
in your own code. We may change the API at any time with no warning.
"""
import itertools
import re
import sys
import warnings
def check_in_list(_values, *, _print_supported_values=True, **kwargs):
"""
For each *key, value* pair in *kwargs*, check that *value* is in *_values*.
Parameters
----------
_values : iterable
Sequence of values to check on.
_print_supported_values : bool, default: True
Whether to print *_values* when raising ValueError.
**kwargs : dict
*key, value* pairs as keyword arguments to find in *_values*.
Raises
------
ValueError
If any *value* in *kwargs* is not found in *_values*.
Examples
--------
>>> _api.check_in_list(["foo", "bar"], arg=arg, other_arg=other_arg)
"""
values = _values
for key, val in kwargs.items():
if val not in values:
if _print_supported_values:
raise ValueError(
f"{val!r} is not a valid value for {key}; "
f"supported values are {', '.join(map(repr, values))}")
else:
raise ValueError(f"{val!r} is not a valid value for {key}")
def check_shape(_shape, **kwargs):
"""
For each *key, value* pair in *kwargs*, check that *value* has the shape
*_shape*, if not, raise an appropriate ValueError.
*None* in the shape is treated as a "free" size that can have any length.
e.g. (None, 2) -> (N, 2)
The values checked must be numpy arrays.
Examples
--------
To check for (N, 2) shaped arrays
>>> _api.check_shape((None, 2), arg=arg, other_arg=other_arg)
"""
target_shape = _shape
for k, v in kwargs.items():
data_shape = v.shape
if len(target_shape) != len(data_shape) or any(
t not in [s, None]
for t, s in zip(target_shape, data_shape)
):
dim_labels = iter(itertools.chain(
'MNLIJKLH',
(f"D{i}" for i in itertools.count())))
text_shape = ", ".join((str(n)
if n is not None
else next(dim_labels)
for n in target_shape))
raise ValueError(
f"{k!r} must be {len(target_shape)}D "
f"with shape ({text_shape}). "
f"Your input has shape {v.shape}."
)
def check_getitem(_mapping, **kwargs):
"""
*kwargs* must consist of a single *key, value* pair. If *key* is in
*_mapping*, return ``_mapping[value]``; else, raise an appropriate
ValueError.
Examples
--------
>>> _api.check_getitem({"foo": "bar"}, arg=arg)
"""
mapping = _mapping
if len(kwargs) != 1:
raise ValueError("check_getitem takes a single keyword argument")
(k, v), = kwargs.items()
try:
return mapping[v]
except KeyError:
raise ValueError(
"{!r} is not a valid value for {}; supported values are {}"
.format(v, k, ', '.join(map(repr, mapping)))) from None
def warn_external(message, category=None):
"""
`warnings.warn` wrapper that sets *stacklevel* to "outside Matplotlib".
The original emitter of the warning can be obtained by patching this
function back to `warnings.warn`, i.e. ``_api.warn_external =
warnings.warn`` (or ``functools.partial(warnings.warn, stacklevel=2)``,
etc.).
"""
frame = sys._getframe()
for stacklevel in itertools.count(1): # lgtm[py/unused-loop-variable]
if frame is None:
# when called in embedded context may hit frame is None
break
if not re.match(r"\A(matplotlib|mpl_toolkits)(\Z|\.(?!tests\.))",
# Work around sphinx-gallery not setting __name__.
frame.f_globals.get("__name__", "")):
break
frame = frame.f_back
warnings.warn(message, category, stacklevel)