g%MdZddlmZddlZddlZddlZddlmZddlm Z m Z dddddd d d9dZ ddddddddd:dZ e fddd;d#Zd e fdddd4Zehd5Zd?d8ZdS)@zDeprecation utilities) annotationsN)Callable)AnyTypeFqiskitz/no earlier than 3 months after the release date)additional_msgpending package_nameremoval_timeline is_property stacklevelsincestrr str | Noner boolr r r rintc*fd}|S)aDecorator to indicate a function has been deprecated. It should be placed beneath other decorators like `@staticmethod` and property decorators. When deprecating a class, set this decorator on its `__init__` function. Args: since: The version the deprecation started at. If the deprecation is pending, set the version to when that started; but later, when switching from pending to deprecated, update ``since`` to the new version. additional_msg: Put here any additional information, such as what to use instead. For example, "Instead, use the function ``new_func`` from the module ``.``, which is similar but uses GPU acceleration." pending: Set to ``True`` if the deprecation is still pending. package_name: The PyPI package name, e.g. "qiskit-nature". removal_timeline: How soon can this deprecation be removed? Expects a value like "no sooner than 6 months after the latest release" or "in release 9.99". is_property: If the deprecated function is a `@property`, set this to True so that the generated message correctly describes it as such. (This isn't necessary for property setters, as their docstring is ignored by Python.) stacklevel: Stack level passed to :func:`warnings.warn`. Returns: Callable: The decorated callable. cdj}j} r d|d|d}nDd|vr7jdkr"|dtd }d|d|d}nd|d|d}n d |d|d}t |  \t jfd }t| |S) NzThe property ``.``__init__z .__init__z The class ``z The method ``z()``zThe function ``deprecated_entityr rr r r cBtj|i|SNcategoryrwarningswarnargskwargsrfuncmsgrs N/granary/edev/quantum/lib/python3.11/site-packages/qiskit/utils/deprecation.pywrapperz2deprecate_func..decorator..wrapper^/ M#Z H H H H4((( (rr ) __qualname__ __module____name__len_write_deprecation_msg functoolswrapsadd_deprecation_to_docstring)r%qualnamemod_namercls_namer(rr&r r r r r rrs` @@r' decoratorz!deprecate_func..decorator;sJ$?  L!J( I IX I I I  H__} **#$7s;'7'7&7$78$J8$J$Jh$J$J$J!!$MH$M$Mx$M$M$M!! K( K KX K K K ./%)-    X    ) ) ) ) ) ) )   ) %WcPPPPr*)rr r r r r rr7s``````` r'deprecate_funcr9sJF)))))))))))V r*)r deprecation_descriptionr r new_alias predicater namer:r;r<Callable[[Any], bool] | Nonec 2f d} | S)aDecorator to indicate an argument has been deprecated in some way. This decorator may be used multiple times on the same function, once per deprecated argument. It should be placed beneath other decorators like ``@staticmethod`` and property decorators. Args: name: The name of the deprecated argument. since: The version the deprecation started at. If the deprecation is pending, set the version to when that started; but later, when switching from pending to deprecated, update `since` to the new version. deprecation_description: What is being deprecated? E.g. "Setting my_func()'s `my_arg` argument to `None`." If not set, will default to "{func_name}'s argument `{name}`". additional_msg: Put here any additional information, such as what to use instead (if new_alias is not set). For example, "Instead, use the argument `new_arg`, which is similar but does not impact the circuit's setup." pending: Set to `True` if the deprecation is still pending. package_name: The PyPI package name, e.g. "qiskit-nature". new_alias: If the arg has simply been renamed, set this to the new name. The decorator will dynamically update the `kwargs` so that when the user sets the old arg, it will be passed in as the `new_alias` arg. predicate: Only log the runtime warning if the predicate returns True. This is useful to deprecate certain values or types for an argument, e.g. `lambda my_arg: isinstance(my_arg, dict)`. Regardless of if a predicate is set, the runtime warning will only log when the user specifies the argument. removal_timeline: How soon can this deprecation be removed? Expects a value like "no sooner than 6 months after the latest release" or "in release 9.99". Returns: Callable: The decorated callable. c & jdjd pdd d} rd d} r|d }n|}n }t| |\tj fd t d r j_nhjj_d tj j D}tj j|vrtd t! S)Nrz()rz``'s argument ``zInstead, use the argument ``z``, which behaves identically.z. rc Nt|| j |i|SN) func_nameoriginal_func_co_varnames old_arg_namer; warning_msgrr<)_maybe_warn_and_rename_kwarg__original_func_co_varnames) r#r$rr%rCr&r=r;r<r(s r'r(z1deprecate_arg..decorator..wrappersO (#*1*M!#!#    4((( (r*rHch|] }|j Sr8kind.0params r' z3deprecate_arg..decorator..___%5:___r*l@deprecate_arg cannot be used with functions that take variable *args. Use warnings.warn() directly instead.r+)r-r,r0r1r2hasattrrH__code__ co_varnamesinspect signature parametersvalues ParameterVAR_POSITIONAL ValueErrorr3)r%r alias_msgfinal_additional_msg param_kindsrrCr&r(r r:r=r;r r r<r rs` @@@@r'r7z deprecate_arg..decorators>>):>>> 3_7_I7_7_W[7_7_7_  2`y```I 1*3'G'G~'G'G$$'0$$#1 ./%/-    X    ) ) ) ) ) ) ) ) ) ) )   )& 46 7 7 262RG / /26-2KG /__73DT3J3J3U3\3\3^3^___K /;>> 8 %WcPPPPr*r8) r=rr r:r r r;r<r r7s ````````` r' deprecate_argr_isVV7777777777777r r*)r kwarg_mapdict[str, str | None]r Type[Warning]cfd}|S)aNDeprecated. Instead, use `@deprecate_arg`. Args: kwarg_map: A dictionary of the old argument name to the new name. category: Usually either DeprecationWarning or PendingDeprecationWarning. since: The version the deprecation started at. Only Optional for backwards compatibility - this should always be set. If the deprecation is pending, set the version to when that started; but later, when switching from pending to deprecated, update `since` to the new version. Returns: Callable: The decorated callable. c Pji D]\}}|dnd|d}d|d||<tj  fdt dr j_nhjj_dtj j D}tj j |vrtd  D](}t| t! t" )S) Nzwill in the future be removed.zreplaced with rz keyword argument z is deprecated and c D](\}}t|| j|||d )|i|SrB)itemsrGrH) r#r$oldnewrr%rCr`old_kwarg_to_msgr(s r'r(z7deprecate_arguments..decorator..wrappersv%OO--  S,'.5.Q!$! 0 5%"     4((( (r*rHch|] }|j Sr8rJrLs r'rOz9deprecate_arguments..decorator..rPr*rQr+)r,rfr1r2rRrHrSrTrUrVrWrXrYrZr[r3 issubclassPendingDeprecationWarning) r%old_argnew_arg msg_suffixr^r&rCrir(rr`rs ` @@@r'r7z&deprecate_arguments..decorators%  ) 1 1   GW4;O00IdZaIdIdId XXXXJXX W % %    ) ) ) ) ) ) ) ) )   )( 46 7 7 262RG / /26-2KG /__73DT3J3J3U3\3\3^3^___K /;>> 8 $**,,  C (E:hHa3b3b     r*r8)r`rrr7s``` r'deprecate_argumentsrps1(///////b r*r&cfd}|S)ayDeprecated. Instead, use `@deprecate_func`. Args: msg: Warning message to emit. stacklevel: The warning stacklevel to use, defaults to 2. category: Usually either DeprecationWarning or PendingDeprecationWarning. since: The version the deprecation started at. Only Optional for backwards compatibility - this should always be set. If the deprecation is pending, set the version to when that started; but later, when switching from pending to deprecated, update `since` to the new version. Returns: Callable: The decorated, deprecated callable. c tjfd}t|tt|S)NcBtj|i|Srrr"s r'r(z6deprecate_function..decorator..wrapper/r)r*r+)r1r2r3rkrl)r%r(rr&rrs` r'r7z%deprecate_function..decorator.su    ) ) ) ) ) ) )   ) % Sz(D]/^/^    r*r8)r&rrrr7s```` r'deprecate_functionrts6,         r*r#tuple[Any, ...]r$dict[str, Any]rCrDtuple[str, ...]rErFreturnNonecdt||D} | ||| vrdS|r|| vrt|d|d|d| |} |r || sdStj||d|| ||<dSdS)Nci|]\}}|| Sr8r8)rMvalr=s r' z0_maybe_warn_and_rename_kwarg..Ks[[[d4[[[r*z received both z and z (deprecated).r)zipupdate TypeErrorr r!) r#r$rCrDrEr;rFrr<arg_names_to_valuesr|s r'rGrG<s\[c$@Y6Z6Z[[[v&&&...cY"5559aaYaa\aaabbb l +C3 M+Q????yr*rFtuple[str, Type[DeprecationWarning] | Type[PendingDeprecationWarning]]c ~|rt}d}d|}nt}d}d|}|d|d|d|d|d } |r| d|z } | |fS) Nzpending deprecationz8marked deprecated in a future release, and then removed deprecatedzremoved z is z as of  z . It will be r)rlDeprecationWarning) rr rr r r rdeprecation_status removal_descr&s r'r0r0^s 5 % 3dRbdd %)4"244   & &"4 & &\ & &E & &" & & &$ #>### =r*>tip:args:hint:note:todo:warn:error:notes:warns:yield:danger:raises:return:yields:caution:example:returns:warning: examples: see also: warnings: arguments: attention: important: attributes: parameters: references: keyword args:other parameters:keyword arguments:r%rcd|vrtd|jd|d}n |r|dn|}d}d}|jr|j}d}t |D]\} } | } |s@| d kr:| r8t | t | z } d | z}d }| tvr| }|std |jd nng}||d||d||g} |r| ||dz |dz <n| | d ||_dS)aDynamically insert the deprecation message into ``func``'s docstring. Args: func: The function to modify. msg: The full deprecation message. since: The version the deprecation started at. pending: Is the deprecation still pending?  zNDeprecation messages cannot contain new lines (`\n`), but the deprecation for aY had them. Usually this happens when using `"""` multiline strings; instead, use string concatenation. This is a simplification to facilitate deprecation messages being added to the documentation. If you have a compelling reason to need new lines, feel free to improve this function or open a request at https://github.com/Qiskit/qiskit/issues.Nunknown_pendingFrrTzadd_deprecation_to_docstring cannot currently handle when a Napoleon metadata line like 'Args' is the very first line of docstring, e.g. `"""Args:`. So, it cannot process zF. Instead, move the metadata line to the second line, e.g.: """ Args:z.. deprecated:: z ) r[r,__doc__ splitlines enumeratestripr/lstriplower_NAPOLEON_META_LINESextendjoin)r%r&rr version_strindent meta_indexoriginal_linescontent_encounteredilinestrippednum_leading_spaces new_liness r'r3r3s s{{ 7  7 7 7    } ,3>(((( FJ |0022# 00  GAtzz||H ' +166h6%(YYT[[]]1C1C%C"11&*#~~#777 *$ZBFBSZZZ8  00;00 S I):CzA~ Q677i(((99^,,DLLLr*)rrr rr rr rr rr rrr)r=rrrr rr:rr rr rr;rr<r>r r)r`rarrbrr)r&rrrrrbrr)r#rur$rvrCrrDrwrErr;rrFrrrbr<r>rxry)rrr rrrr rr rr rrxr) r%rr&rrrr rrxry)r __future__rr1rUr collections.abcrtypingrrr9r_rrprtrGr0 frozensetrr3r8r*r'rs""""""$$$$$$ "& MNNNNNNj"&*.  .2MddddddR1E EEEEEET0!  !!!!!!H    D@!y!!HH-H-H-H-H-H-r*