o gM@sdZddlZddlZddlZddlZGdddeZeZ  ddddd Zdddddddd d d Z dddddddd d dZ GdddZ dddZ GdddZ e ZdddZdddZddddZejddZdS) a Helper functions for deprecating parts of the Matplotlib API. This documentation is only relevant for Matplotlib developers, not for users. .. warning: This module is for internal use only. Do not use it in your own code. We may change the API at any time with no warning. Nc@seZdZdZdS)MatplotlibDeprecationWarninga 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. https://docs.python.org/dev/whatsnew/2.7.html#the-future-for-python-2-x N)__name__ __module__ __qualname____doc__rrY/home/ubuntu/cloudmapper/venv/lib/python3.10/site-packages/matplotlib/_api/deprecation.pyrsrFremovalc Cs|r |rtdn |rd|nd}|s0d|rdnd|rdndd |r'd nd|r-d nd}|r4tnt}||t|||||||d S) Nz5A pending deprecation cannot have a scheduled removalzin ztwo minor releases laterz The %(name)s %(obj_type)sz' will be deprecated in a future versionz' was deprecated in Matplotlib %(since)sz and will be removed %(removal)sr .z Use %(alternative)s instead.z %(addendum)s)funcnameobj_typesincer alternativeaddendum) ValueErrorPendingDeprecationWarningrdict) rmessagerrpendingrrr warning_clsrrr_generate_deprecation_warning%s>     rrrrrrrr c Cs4t||||||||d}ddlm} | |tddS)a0 Display a standardized deprecation. Parameters ---------- since : str The release at which this API became deprecated. message : str, optional Override the default deprecation message. The ``%(since)s``, ``%(name)s``, ``%(alternative)s``, ``%(obj_type)s``, ``%(addendum)s``, and ``%(removal)s`` format specifiers will be replaced by the values of the respective arguments passed to this function. name : str, optional The name of the deprecated object. alternative : str, optional An alternative API that the user may use in place of the deprecated API. The deprecation warning will tell the user about this alternative if provided. pending : bool, optional If True, uses a PendingDeprecationWarning instead of a DeprecationWarning. Cannot be used together with *removal*. obj_type : str, optional The object type being deprecated. addendum : str, optional Additional text appended directly to the final message. removal : str, optional The expected removal version. With the default (an empty string), a removal version is automatically computed from *since*. Set to other Falsy values to not schedule a removal date. Cannot be used together with *pending*. 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') r ) warn_external)categoryN)rr rr) rrrrrrrr warningrrrrwarn_deprecatedAs 1 rc s ||||||ffdd }|S)a7 Decorator to mark a function, a class, or a property as deprecated. When deprecating a classmethod, a staticmethod, or a property, the ``@deprecated`` decorator should go *under* ``@classmethod`` and ``@staticmethod`` (i.e., `deprecated` should directly decorate the underlying callable), but *over* ``@property``. When deprecating a class ``C`` intended to be used as a base class in a multiple inheritance hierarchy, ``C`` *must* define an ``__init__`` method (if ``C`` instead inherited its ``__init__`` from its own base class, then ``@deprecated`` would mess up ``__init__`` inheritance when installing its own (deprecation-emitting) ``C.__init__``). Parameters ---------- since : str The release at which this API became deprecated. message : str, optional Override the default deprecation message. The ``%(since)s``, ``%(name)s``, ``%(alternative)s``, ``%(obj_type)s``, ``%(addendum)s``, and ``%(removal)s`` format specifiers will be replaced by the values of the respective arguments passed to this function. name : str, optional The name used in the deprecation message; if not provided, the name is automatically determined from the deprecated object. alternative : str, optional An alternative API that the user may use in place of the deprecated API. The deprecation warning will tell the user about this alternative if provided. pending : bool, optional If True, uses a PendingDeprecationWarning instead of a DeprecationWarning. Cannot be used together with *removal*. obj_type : str, optional The object type being deprecated; by default, 'class' if decorating a class, 'attribute' if decorating a property, 'function' otherwise. addendum : str, optional Additional text appended directly to the final message. removal : str, optional The expected removal version. With the default (an empty string), a removal version is automatically computed from *since*. Set to other Falsy values to not schedule a removal date. Cannot be used together with *pending*. Examples -------- Basic example:: @deprecated('1.4.0') def the_function_to_deprecate(): pass c sHddlmttr# durd jpjj}fdd}n@ttfrMd dp3jjj}Gfdddtfd d}n durSd pYjj}fd d} fd d fdd} t |p|d d}d} d|d| |vr| ndd d } |s| d7} || | S)Nr) classpropertyclasscs4z|_Wn tyYnwtj|_SN)rAttributeError functoolswraps__init__wrappernew_doc)objrrfinalizes  z/deprecated..deprecate..finalize attributecsHeZdZfddZfddZfddZfddZZS) z;deprecated..deprecate.._deprecated_propertycs.|dus |durt|rt||Sr") isinstancesuper__get__)selfinstanceowner) __class__r emit_warningrrr/s zCdeprecated..deprecate.._deprecated_property.__get__cs|durt||Sr")r.__set__)r0r1valuer3r4rrr5szCdeprecated..deprecate.._deprecated_property.__set__cs|durt|Sr")r. __delete__)r0r1r7rrr8s zFdeprecated..deprecate.._deprecated_property.__delete__csdkr|dSdS)Nzr)r0r2set_namerrr __set_name__szHdeprecated..deprecate.._deprecated_property.__set_name__)rrrr/r5r8r; __classcell__r)r r4r)r3r_deprecated_propertys r=csjjj|dS)N)fgetfsetfdeldoc)r>r?r@)_r))r=r*rrr+sfunctioncst|}||_|Sr")r$r%rr')r rrr+sc stddS)Nr)rr)rrrrrrr rrrr4s  z3deprecated..deprecate..emit_warningcs|i|Sr"rargskwargs)r4r rrr(sz.deprecated..deprecate..wrapperr  z Notes -----z[*Deprecated*] z .. deprecated:: z z\ ) matplotlib._apir r-typer&rrpropertyr>inspectcleandocstrip) r*rrrrrrold_docr+r( notes_headerr)r r) r=rrr r4r rrr*rrr deprecatesF       zdeprecated..deprecater) rrrrrrrr rQrrPr deprecatedys>XrRc@s eZdZdZddZddZdS)deprecate_privatize_attributea Helper to deprecate public access to an attribute. This helper should only be used at class scope, as follows:: class Foo: attr = _deprecate_privatize_attribute(*args, **kwargs) where *all* parameters are forwarded to `deprecated`. This form makes ``attr`` a property which forwards access to ``self._attr`` (same name but with a leading underscore), with a deprecation warning. Note that the attribute name is derived from *the name this helper is assigned to*. cOst|i||_dSr")rR deprecator)r0rErFrrrr&!sz&deprecate_privatize_attribute.__init__cs&t||jtfddddS)Ncst|dS)NrB)getattrr0r:rr&sz.r:)setattrrTrJ)r0r2rrr:rr;$s  z*deprecate_privatize_attribute.__set_name__N)rrrrr&r;rrrrrSs rScsdur ttSt}|jvs"Jddjd|jvs3Jddjdtfdd}|S)a Decorator indicating that parameter *old* of *func* is renamed to *new*. The actual implementation of *func* should use *new*, not *old*. If *old* is passed to *func*, a DeprecationWarning is emitted, and its value is used, even if *new* is also passed by keyword (this is to simplify pyplot wrapper functions, which always pass *new* explicitly to the Axes method). If *new* is also passed but positionally, a TypeError will be raised by the underlying function during argument binding. Examples -------- :: @_api.rename_parameter("3.1", "bad_name", "good_name") def func(good_name): ... NMatplotlib internal error: z cannot be a parameter for () must be a parameter for c sL|vrtddjddd d||<|i|S)NzThe z parameter of z() has been renamed z since Matplotlib z7; support for the old name will be dropped %(removal)s.r)rrpoprDr newoldrrrr(Gsz!rename_parameter..wrapper)r$partialrename_parameterrK signature parametersrr%)rr`r_r rcr(rr^rrb)s    rbc@seZdZddZdS)_deprecated_parameter_classcCdS)NzrrVrrr__repr__Zsz$_deprecated_parameter_class.__repr__N)rrrrgrrrrreYs rec sdurtjtfiSttddjDdjvrPjj}|tj j u|tj j usOsOj fddjDd_ ndsbJdd jd d dtf d d }|S)aI Decorator indicating that parameter *name* of *func* is being deprecated. The actual implementation of *func* should keep the *name* parameter in its signature, or accept a ``**kwargs`` argument (through which *name* would be passed). Parameters that come after the deprecated parameter effectively become keyword-only (as they cannot be passed positionally without triggering the DeprecationWarning on the deprecated parameter), and should be marked as such after the deprecation period has passed and the deprecated parameter is removed. Parameters other than *since*, *name*, and *func* are keyword-only and forwarded to `.warn_deprecated`. Examples -------- :: @_api.delete_parameter("3.1", "unused") def func(used_arg, other_arg, unused, more_args): ... Ncss$|] }|jtjjkr|jVqdSr")kindrK Parameter VAR_KEYWORDr.0paramrrr s z#delete_parameter..cs&g|]}|jkr|jtdn|qS))default)rreplace_deprecated_parameterrkr:rr s  z$delete_parameter..rdFrYr[rZrcsj|i|j}r|rtdjddnEr/|r/tdjddn2tfdd||ifDradd}tftd jd rZd |n|d |i|S) Nz#Additional positional arguments to zS() are deprecated since %(since)s and support for them will be removed %(removal)s.r\z Additional keyword arguments to c3s$|] }|vo |tkVqdSr")rq)rldr:rrrnsz4delete_parameter..wrapper..zIf any parameter follows z5, they should be passed as keyword, not positionally. parameter of rZ )rrr)bind argumentsgetrranyrepr) inner_args inner_kwargsrxdeprecation_addendum rr is_varargs is_varkwargsrF kwargs_namerrcrrrr(s:   z!delete_parameter..wrapper)r$radelete_parameterrKrcnextrdvaluesrhriVAR_POSITIONALrjrp __signature__rr]r%)rrr rFrhr(rrrras2      rcsdur ttSttjjtjjjvr%jj ks1Jddj dgj}fdd|| dDj fddj Dd_tfd d }|S) z Decorator indicating that passing parameter *name* (or any of the following ones) positionally to *func* is being deprecated. NrYz/ must be a positional-or-keyword parameter for rZcs g|] }j|jkr|qSr)rdrh)rlr)POKrcrrrrsz%make_keyword_only..cs&g|]}|jvr|jdn|qS))rh)rrprk)KWOkwonlyrrrrsrscsFgjj}t||krtddjdd|i|S)NzPassing the %(name)s %(obj_type)s positionally is deprecated since Matplotlib %(since)s; the parameter will become keyword-only %(removal)s.rurZ)rrr)rrdindexlenrr)rErFidx)r rrrrr(s z"make_keyword_only..wrapper)r$ramake_keyword_onlyrKrcriPOSITIONAL_OR_KEYWORD KEYWORD_ONLYrdrhrrrprrr%)rrr namesr(r)rrr rrrcrrrs&   "  r) allow_emptyc Ksdd}dd}|j}t||}t|t|rt|tr|n||}||krI|r;tt|dddd|jj|jjfvrItd i|dd ||SdS) a Return ``obj.method`` with a deprecation if it was overridden, else None. Parameters ---------- method An unbound method, i.e. an expression of the form ``Class.method_name``. Remember that within the body of a method, one can always use ``__class__`` to refer to the class that is currently being defined. obj Either an object of the class where *method* is defined, or a subclass of that class. allow_empty : bool, default: False Whether to allow overrides by "empty" methods without emitting a warning. **kwargs Additional parameters passed to `warn_deprecated` to generate the deprecation warning; must at least include the "since" key. cSsdSr"rrrrremptyz(deprecate_method_override..emptycSrf)rANrrrrrempty_with_docstringrz7deprecate_method_override..empty_with_docstring__code__Nco_codemethod)rrr)rrUr-rIr/rrr) rr*rrFrrr bound_child bound_baserrrdeprecate_method_overrides.   rccsBttdtdVWddS1swYdS)Nignore)warningscatch_warnings simplefilterrrrrr'suppress_matplotlib_deprecation_warnings   "r)r r r Fr r r")r contextlibr$rKr UserWarningrmplDeprecationrrrRrSrbrerqrrrcontextmanagerrrrrrs8   8  0  S(*