^jCdZddlZddlZddlZddlZddlZddlZddlZddlm Z m Z m Z m Z m Z mZmZmZmZGddZeZGddeZGd d ZGd d Zd ZdZdZdZefdZdZddZdZ dZ!dZ"dZ#ddZ$y)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_warningMatplotlibDeprecationWarningceZdZdZy)_Unsetcy)Nzselfs Q/opt/ringagent/.cad-venv/lib/python3.12/site-packages/matplotlib/_api/__init__.py__repr__z_Unset.__repr__!sN)__name__ __module__ __qualname__rrrrrr srrceZdZdZy)UnsupportedErrorz Raised on inherited methods if the child class does not support the functionality of the base class. See `.unsupported_method` for details. N)rrr__doc__rrrrr&srrc"eZdZdZdddZdZy)unsupported_methoda Descriptor that creates a method raising `.UnsupportedError`. Historically, we have quite a few cases of inheritance hierarchies that do not fully respect the Liskov Substitution Principle, e.g. Axes and Artist. Some of the methods of a base class may not be implemented in the child class. In that case, we override the method in the child class to raise `.UnsupportedError`. Use in a class body to mark inherited methods as unsupported:: class Axes3D(Axes): twinx = _api.unsupported_method() Calling ``Axes3D().twinx()`` will raise "UnsupportedError: Axes3D does not support 'twinx'." Parameters ---------- append_message : str Optional additional text to be appended to the error message. Nappend_messagec||_yNr)rrs r__init__zunsupported_method.__init__Es ,rc|jd|d|jrd|jzz fd}||_|jd||_|j|_t |||y)Nz does not support 'z'. ctr!)r)rargskwargsmessages rmethodz/unsupported_method.__set_name__..methodMs"7+ +r.)rrrrsetattr)rownernamer)r(s @r __set_name__zunsupported_method.__set_name__Hs{^^$$7vR@    sT000 0G ,!&!3!3 4AdV<!,,tV$r)rrrrr"r.rrrrr/s**.- %rrc.eZdZdZddZdZedZy) 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" NcZ||_|| td||_||_||_y)Nz#classproperty only implements fget.)_fget ValueErrorfsetfdel_doc)rfgetr4r5docs rr"zclassproperty.__init__gs5  t/BC C   rc$|j|Sr!r2)rinstancer,s r__get__zclassproperty.__get__pszz%  rc|jSr!r:rs rr7zclassproperty.fgetss zzr)NNN)rrrrr"r<propertyr7rrrr0r0Vs% !rr0c tdt|tr|fn|fntfd|D}fd}|jD]\}}t||rgt ||}d|vr"|j d|j dtdj|t|dkDrdj|ddd z|dzn|d |t|y) a3 For each *key, value* pair in *kwargs*, check that *value* is an instance of one of *types*; if not, raise an appropriate TypeError. As a special case, a ``None`` entry in *types* is treated as NoneType. Examples -------- >>> _api.check_isinstance((SomeClass, None), arg=arg) Nc3*K|] }|n| ywr!r).0tp none_types r z#check_isinstance..sCr 92Csc||urdS|jdk(r |jS|jd|jS)NNonebuiltinsr*)rr)rBrCs r type_namez#check_isinstance..type_namesD / ;(* (CR__ ; a'89 ;rrFz({!r} must be an instance of {}, not a {}r, z or r) type isinstancetupleitemsmapremoveappend TypeErrorformatlenjoin)typesr'rHkvnamesrCs @rcheck_isinstancerZ{sT I#E40eX"]i\ CUC C ;   )1!U#,c)U+,E V$ V$:AA5zA~IIeCRj)F2U2Y>+08d1g& () ) )rc\t|dkDrstd|g|Dr^tj||d}t|xdk(rd}nUdk(r d|dd }nG d d j t t |d }n"d d j t t |}|d |d|S)a Generate an error message that a potential setting is not an acceptable value. If the acceptable values are all strings, and sufficiently large, then add just a few suggestions to the end of the message. Otherwise list the supported values. Parameters ---------- name : str The name of the setting, keyword argument, etc. to generate the message for. potential The potential value from the user that is not a valid choice. values : iterable Sequence of values to check on. c3<K|]}t|tywr!)rLstr)rArXs rrDz,list_suggestion_error_msg..sPaz!S1Psg?)cutoffrrz Did you mean: ?z Did you mean one of: rIz Supported values are z is not a valid value for r*)rTalldifflibget_close_matchesrUrOrepr)r- potentialvaluesbest suggestions rlist_suggestion_error_msgrjs  6{Q3PI;O;OPP((F3G$i .tAwk; 5diiD$6P5QQRS -diiD&8I.J-KL ]4TF!J< HHrc |s td|jD]"\}} ||v}|rtt|||y#t$rd}Y(wxYw)a| For each *key, value* pair in *kwargs*, check that *value* is in *values*; if not, raise an appropriate ValueError. Parameters ---------- values : iterable Sequence of values to check on. Note: All values must support == comparisons. This means in particular the entries must not be numpy arrays. **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) zNo argument to check!FN)rRrNr3rj)rgr'keyvalexistss r check_in_listrosn0 /00LLN JS F]F6sCHI I J F sA AAc &|jD]\}}|j}t|t|k7stdt ||DsFt t jddt jD}dj|dddDcgc]}| t|n t|c}ddd}t|dk(r|dz }t|d t|d |d |jycc}w) 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) c38K|]\}}||k7xr|duywr!r)rAsts rrDzcheck_shape..s$SDAqqAv/!4-/SsNMLKJIHc3&K|] }d| yw)DNr)rAis rrDzcheck_shape..s4Q1QC4srINrJr,z must be zD with shape (z), but your input has shape ) rNshaperTanyzipiter itertoolschaincountrUr^nextr3)ryr'rWrX data_shape dim_labelsn text_shapes r check_shapers  1WW  Os5z )SC EB$$@AJ5zQc! %yU N:,G,,-GG96 $:s$D c t|dk7r td|j\\}} ||S#t$r#|t |||j dwxYw)aE *kwargs* must consist of a single *key, value* pair. If *key* is in *mapping*, return ``mapping[value]``; else, raise an appropriate ValueError. Parameters ---------- _error_cls : Class of error to raise. Examples -------- >>> _api.getitem_checked({"foo": "bar"}, arg=arg) rz/getitem_checked takes a single keyword argumentN)rTr3rNKeyErrorrjkeys)mapping _error_clsr'rWrXs rgetitem_checkedr sk 6{aJKKllnGFQTqz T21aHItSTs 5,A!cjdk(sJtjDcic]\}}t|tr||c}}t j fd}|Scc}}w)a  Helper decorator for implementing module-level ``__getattr__`` as a class. This decorator must be used at the module toplevel as follows:: @caching_module_getattr class __getattr__: # The class *must* be named ``__getattr__``. @property # Only properties are taken into account. def name(self): ... The ``__getattr__`` class will be replaced by a ``__getattr__`` function such that trying to access ``name`` on the module will resolve the corresponding property (which may be decorated e.g. with ``_api.deprecated`` for deprecating module globals). The properties are all implicitly cached. Moreover, a suitable AttributeError is generated and raised if no property with the given name exists. __getattr__cj|vr|jStdjd|)Nzmodule z has no attribute )r<AttributeErrorr)r-clsr;propss rrz+caching_module_getattr..__getattr__:sD 5=;&&x0 0cnn''9$ BD Dr)rvarsrNrLr> functoolscache)rr-proprr;rs` @@rcaching_module_getattrr!sw& <<= (( (*.s)//*; ,JD$4*4Z ,EuH__DD  ,sA5c$tjt|Sfd}|jD]k\}}d}dD]O}||zt vsd}|D]5}|||z}||z|_d||zd|_t||z|7Q|r_td||jDcic]\}}|D]}||} }}}d} td i} | | | | z} | rtd | i| | _ Scc}}}w) aQ Class decorator for defining property aliases. Use as :: @_api.define_aliases({"property": ["alias", ...], ...}) class C: ... For each property, if the corresponding ``get_property`` is defined in the class so far, an alias named ``get_alias`` will be defined; the same will be done for setters. If neither the getter nor the setter exists, an exception will be raised. The alias map is stored as the ``_alias_to_prop`` attribute under the format ``{"alias": "property", ...}` on the class, and can be used by `.normalize_kwargs`. cXtjtfd}|S)Nc(t||i|Sr!)getattr)rr&r'r-s rr)z2define_aliases..make_alias..methodZs&74&77 7r)rwrapsr)r-r)rs` r make_aliasz"define_aliases..make_aliasYs* d+ , 8 - 8 rF)get_set_Tz Alias for `z`.z%Neither getter nor setter exists for cFh|j|jSr!)rrg)ds rget_aliased_and_aliasesz/define_aliases..get_aliased_and_aliasesps''AHHJ''r_alias_to_propz2Parent class already defines conflicting aliases: ) rpartialdefine_aliasesrNrrrr+r3rNotImplementedErrorr) alias_drrraliasesrnprefixaliasr) alias_to_proprpreexisting_aliases conflictings ` rrrDs$ {  99 ! B g& 9F}S )$9E' 6F&,unFO'26D=/%DFNC%8 9 97x@B B B*1OO%ggO=Bt O OMO("#'7<*+>?,];rs  """ |$%$%NJ )FI<'JT F,6T0 F7t1h, L"0/r