U \ a@sdZddlZddlZddlZddlZddlmZmZmZm Z m Z m Z m Z m Z mZGdddZddZd d d d Zd dZddZdddZdS)a* 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. N) deprecatedwarn_deprecatedrename_parameterdelete_parametermake_keyword_onlydeprecate_method_overridedeprecate_privatize_attribute'suppress_matplotlib_deprecation_warningMatplotlibDeprecationWarningc@s.eZdZdZd ddZddZeddZdS) classpropertya$ Like `property`, but also triggers on access via the class, and it is the *class* that's passed as argument. Examples -------- :: class C: @classproperty def foo(cls): return cls.__name__ assert C.foo == "C" NcCs4||_|dk s|dk rtd||_||_||_dS)Nz#classproperty only implements fget.)_fget ValueErrorfsetfdel_doc)selffgetrrdocr>> _api.check_isinstance((SomeClass, None), arg=arg) Nc3s|]}|dkrn|VqdSrr).0tpZ none_typerr Osz#check_isinstance..cs.|kr dS|jdkr|jS|jd|jS)NNonebuiltins.)rr)r#r$rr type_nameQs z#check_isinstance..type_namer&z({!r} must be an instance of {}, not a {}r, z or r) type isinstancetupleitemsmapremoveappend TypeErrorformatlenjoin)_typeskwargstypesr)kvnamesrr$rcheck_isinstance@s,        r=T)_print_supported_valuesc Ks^|}|D]L\}}||kr |rFt|d|ddtt|q t|d|q dS)aC 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) z is not a valid value for z; supported values are r*N)r/rr6r0repr)Z_valuesr>r8valueskeyvalrrr check_in_listdsrCc s|}|D]\}}|j}t|t|ksBtddt||Dr ttdddtDd fdd|D}t |dt|d|d |jd q d S) a 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) css|]\}}||dfkVqdSrr)r"tsrrrr%szcheck_shape..ZMNLIJKLHcss|]}d|VqdS)DNr)r"irrrr%sr*c3s&|]}|dk rt|ntVqdSr)strnext)r"nZ dim_labelsrrr%s z must be zD with shape (z). Your input has shape r(N) r/shaper5anyzipiter itertoolschaincountr6r)Z_shaper8Z target_shaper:r;Z data_shapeZ text_shaperrKr check_shapes  rSc Ksj|}t|dkrtd|\\}}z ||WStk rdtd||dtt|dYnXdS)z *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) rz-check_getitem takes a single keyword argumentz9{!r} is not a valid value for {}; supported values are {}r*N)r5rr/KeyErrorr4r6r0r?)_mappingr8mappingr:r;rrr check_getitems   rWcCsVt}tdD]0}|dkr"qDtd|jdds<qD|j}qt |||dS)a4 `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.). rNz-\A(matplotlib|mpl_toolkits)(\Z|\.(?!tests\.))r) sys _getframerPrRrematch f_globalsgetf_backwarningswarn)messagecategoryframe stacklevelrrr warn_externals  rf)N)r rPr[rYr` deprecationrrrrrrr r r r r=rCrSrWrfrrrrs ,&$!'