^j#UdZddlZddlZddlZddlmZmZmZddlmZddl m Z m Z m Z m Z mZmZddlmZddlmZmZmZmZmZmZmZddlmZmZdd lmZmZd Zd Z e!e"d <d Z#dZ$dZ%dZ&ejNZ'ejPZ(eee)Z*e+e,e e,fZ-ddddddddZ.e+e,e,fe"d<de e,ddfdZ/de0ejde0ejfdZ1de de ddfd Z2ded!eee fddfd"Z3de dee4de efdeee ffd#Z5de de d$e+e,e fde fd%Z6d&e d'e7e d(fd)e+e,e fde+e,e ffd*Z8d&e d)e+e,e fde+e,e ffd+Z9e fd,e de de,d-e!d.e,ddf d/Z:de de,fd0Z;de fd,e de dede4e efd1e,d2e,de e,d-e!ddfd3ZZ>ej~d?d?e*d@ddddAdAdBf dee4de efd1e,d2e,d,e e d;e!de e,dCe e-dDe e+e,e fdEee4e fdFe4dGe dHde e d(e fge d(e fffdIZ@y)JaDeprecation wrapper and utilities for marking deprecated code. This module provides the main ``@deprecated`` decorator for marking functions and methods as deprecated while optionally forwarding calls to their replacements. Class-level deprecation is handled by :func:`~deprecate.proxy.deprecated_class`. Key Components: - :func:`~deprecate.deprecation.deprecated`: Main decorator for deprecation with automatic call forwarding - Warning templates for different deprecation scenarios - Internal helpers for argument mapping and warning management Copyright (C) 2020-2026 Jiri Borovec <6035284+Borda@users.noreply.github.com> N)cached_propertypartialwraps) Parameter)AnyCallableLiteralOptionalUnioncast)warn)DeprecationConfig TargetMode _CallPlan_DeprecatedCallable_has_deprecation_meta_HasDeprecationMeta _WrapperState)"_update_docstring_with_deprecationnormalize_docstring_style)_get_signature!get_func_arguments_types_defaultszv1.0_DEFAULT_STACKLEVEL_TO_CALLERzThe `%(source_name)s` was deprecated since v%(deprecated_in)s in favor of `%(target_path)s`. It will be removed in v%(remove_in)s.zThe `%(source_name)s` uses deprecated arguments: %(argument_map)s. They were deprecated since v%(deprecated_in)s and will be removed in v%(remove_in)s.z`%(old_arg)s` -> `%(new_arg)s`zdThe `%(source_name)s` was deprecated since v%(deprecated_in)s. It will be removed in v%(remove_in)s.)categoryxzx.yz0.0z1.0zx -> y) source_name source_path deprecated_in remove_in target_name target_path argument_map_TEMPLATE_MGS_PROBE_ARGS template_mgsreturnc |sy |tzy#tttf$r$}td|dt t|d}~wwxYw)a Probe ``template_mgs`` with every documented placeholder, raising at decoration time on failure. Args: template_mgs: User-supplied warning message template, or ``None``. ``None`` and empty strings are no-ops because the call sites already fall back to the built-in templates. Raises: ValueError: When ``template_mgs`` references an unknown ``%(...)s`` key, uses a malformed conversion specifier, or otherwise fails ``%``-formatting against the full placeholder set. NzInvalid template_mgs: z. Available placeholders: )r$KeyError TypeError ValueErrorlist)r%excs `/var/www/ramen.bs-engineer-server.com/venv/lib/python3.12/site-packages/deprecate/deprecation.py_validate_template_mgsr.LsW // i ,$SG+EdKcFdEe f  s AAAparamsc^|Dcgc]}|jttfvs|c}Scc}w)z.MyClass.method"`` → class ``MyClass`` (class inside a function) - ``"outer.."`` → skipped; prefix ends with ```` - ``"base_sum_kwargs"`` → skipped; no dot means module-level function False positive resolution — ``__qualname__`` is a display string, not an ownership API, so two scenarios used to yield spurious warnings. Both are now handled: - **Decorators that rewrite ``__qualname__``** (e.g. a decorator applied before :func:`~deprecate.deprecated` that sets ``fn.__qualname__ = "OtherClass.method"``): resolved by reading ``__qualname__`` from the enclosing class body frame via :func:`sys._getframe`. Python itself sets ``__qualname__`` in the class-body locals at class-definition time, so this value reflects the true enclosing class regardless of any decorator that mutated the source callable's ``__qualname__`` attribute. - **Metaclass-generated classes** (``type("Name", bases, ns)``, ``__init_subclass__``, or manual assignment producing qualnames like ``"FakeOwner.method"`` for unrelated types): resolved by verifying that the top-level class name in the qualname prefix actually exists in the callable's module globals. When the referenced class does not exist, the qualname is unreliable and the guard returns without raising. Args: source: The callable being decorated with ``@deprecated``. target: The replacement callable supplied as the ``target`` argument. __init____name__N __qualname__.r< __module__zCannot use @deprecated on 'z' with target 'z': cross-class method forwarding is not supported because `self` would carry the wrong type. The target must be a method on the same class ('z') or a full class (use target=z for class migration).)r:getattrrsplitlenendswithsys _getframef_localsget startswithr*AttributeErrorsplitmoduleshasattrr)r<)r6r7 src_qualname tgt_qualname src_parts tgt_parts src_prefix tgt_prefixframe_qn tgt_top_class tgt_modulesrc_class_nametgt_class_name src_owner tgt_owners r- _check_cross_class_method_targetr^gsH*$R)HJ)V6>26L6>26L##C+I##C+I 9~c)n1&q\9Q< J:&**=*=j*I ==#,,00D HOOC3B7BB3G!J$$S!,Q/Mr!BDIJgj-&H&&sA.r2N&&sA.r2N6<45QzlCI6<45QzlCII  %f&9&9%:;    !;;I:JK''5&66L  N )  '   s*AGG"!G" outer_targetc|jj}|j}t|r3t|r(t j d|dt dtdy t|r:|tjur(t j d|dt dtdy t|r:|tjur(t j d|dt dtdy |tjur3t|r(t j d|dt dtdy |tjur:|tjur(t j d|d t dtdy |tjur:|tjur(t j d|d t dtdy |tjur|tjusA|tjur|tjus|tjur t|ry t j d|d t dtdy ) uEmit ``UserWarning`` at decoration time for unsupported stacking combinations. Only called when ``source`` already carries ``__deprecated__`` metadata (i.e. is itself a ``@deprecated`` wrapper). Supported combinations are silently accepted: - ``ARGS_REMAP`` (outer) + ``ARGS_REMAP`` (inner): multi-step arg renames across versions. - ``ARGS_REMAP`` (outer) + ``NOTIFY`` (inner): lifecycle pattern — rename args first, deprecate the whole function later. - ``NOTIFY`` (outer) + ``callable`` (inner): outer NOTIFY warns callers the function is going away; inner callable handles forwarding. Unsupported combinations (six cases) produce ``UserWarning`` at decoration time; all others are silently accepted. The three supported combinations are: ``ARGS_REMAP`` (outer) + ``ARGS_REMAP`` (inner), ``ARGS_REMAP`` (outer) + ``NOTIFY`` (inner), and ``NOTIFY`` (outer) + ``callable`` (inner). 'z' has a callable target stacked over another callable-target @deprecated. Stacking a callable target over another callable target is not supported. This will raise `TypeError` at call time. Will be `TypeError` in `z`. stacklevelz' has a callable target stacked over @deprecated(ARGS_REMAP). The arg-rename warning will not fire at call time; the inner layer is bypassed. Collapse to: @deprecated(target=, args_mapping={...}). Will be `TypeError` in `a:' has a callable target stacked over @deprecated(NOTIFY). The inner function-deprecated warning will not fire at call time; the inner layer is bypassed while the callable target is still invoked. Collapse to a single @deprecated(target=) and remove the inner @deprecated(NOTIFY). Will be `TypeError` in `z' has @deprecated(ARGS_REMAP) stacked over a callable-target @deprecated. Update the inner @deprecated(target=, args_mapping={...}) instead of stacking. Will be `TypeError` in `z' has duplicate @deprecated(NOTIFY) layers. Update the existing decorator's `deprecated_in`, `remove_in`, or `template_mgs` instead. Will be `TypeError` in `z' has @deprecated(NOTIFY) stacked over @deprecated(ARGS_REMAP). Reverse the decorator order: put @deprecated(ARGS_REMAP, ...) outermost (on top) and @deprecated(NOTIFY, ...) below it. Will be `TypeError` in `zO' has an unsupported @deprecated stacking combination. Will be `TypeError` in `N) __deprecated__r7r:callablewarningsr _V1_BREAK_VERSION UserWarningr ARGS_REMAPNOTIFY)r6r_ inner_targetnames r-_warn_stacking_misconfigurationrns=$((//L ??D (<"8 v():':" >    , LJ4I4I$I v():':" >    , LJ4E4E$E v():':"  >   .. .8L3I v((9':" >    ** *|z?P?P/P v((9':" >    ** *|z?T?T/T v():':" >    .. .<:CXCX3X J11 1ljFWFW6W J-- -(<2H  v((9':" >   c|t|trtj|dSt|tr|St j |rt |dd}|jdd}t|dk(xr|djd  }|jd k(r |jS|r&td |jd |jd |S|S)uNormalise the effective target callable before the wrapper closure captures it. Converts legacy sentinel values to :class:`~deprecate._types.TargetMode` enum members with a deprecation warning, and handles class targets: Legacy sentinel conversion (emits warning at decoration time): - ``target=None`` → :attr:`TargetMode.NOTIFY` + :class:`FutureWarning` - ``target=True`` → :attr:`TargetMode.ARGS_REMAP` + :class:`FutureWarning` - ``target=False`` → :attr:`TargetMode.NOTIFY` + :class:`UserWarning` Class target handling (unchanged from previous behaviour): 1. ``source`` is ``__init__`` → remap ``target=NewCls`` to ``target=NewCls.__init__`` (constructor forwarding; ``self`` is the new instance so the call is valid). 2. ``source`` is a class method (non-``__init__``) → raise :exc:`TypeError`; passing a class as target for a bound method silently passes ``self`` of the wrong type. 3. ``source`` is a module-level function → keep ``target=NewCls`` as-is; calling ``NewCls(**kwargs)`` creates a new instance directly. Args: source: The callable being decorated with ``@deprecated``. target: Raw ``target`` argument from the ``@deprecated`` call. Returns: Normalised target suitable for use inside ``wrapped_fn``. Raises: TypeError: When a class target is used on a non-``__init__`` class method. rrcr<r;r=r>r?rr@r9z3Cannot use a class as `target` for @deprecated on 'z['. Constructor forwarding via target=ClassName is only supported on `__init__`. Use target=z;.__init__ explicitly, or apply the decorator to `__init__`.) isinstanceboolr _from_legacyinspectisclassrDrErFrGr:r9r)r<)r6r7rQrSsource_is_class_methods r-_normalize_targetrwsJ~FD1&&v!<<&*% vv~r:  ''Q/ !$Y1!4!^Yq\=R=RS]=^9^ ??j (?? " !EfFYFYEZ[$oo..ik    MrokwargscJt|Dcgc]}|d }}tj|}|j}|j}|Dcgc] }||vs| }}|r:|8|t d|j d|t d|j d||Scc}wcc}w)uValidate mapped keyword arguments and return the target callable. ``packing()`` normalises the target before ``wrapped_fn`` runs — class targets are remapped to ``target.__init__`` — so by the time this function is called, ``target`` is always a plain callable, never a class. Args: source: Deprecated callable being wrapped. target: Target callable to invoke (shall not be a class). kwargs: Keyword arguments after mapping and defaults. Returns: ``target`` unchanged, after validating that it accepts ``kwargs``. Example: >>> from deprecate.deprecation import _prepare_target_call >>> def source(a: int, b: int) -> int: ... return a + b >>> def target(a: int, b: int) -> int: ... return a - b >>> _prepare_target_call(source, target, {"c": 1}) Traceback (most recent call last): ... TypeError: Failed mapping of `source`, arguments not accepted by target: ['c'] rzFailed mapping of `z%`, arguments not accepted by target: zh`, arguments not accepted by target (target accepts *args but these keyword arguments are not allowed): )rrtgetfullargspecvarargsvarkwr)r:) r6r7rxarg target_argstarget_full_arg_specvar_argsvar_kwmisseds r-_prepare_target_callr\s<&Gv%NOc3q6OKO"11&9#++H ! ' 'F# >cs+'=c >F > &.  1&//1BBghngopq q!&//!2399? B   MP ?s B B B funcfn_args. fn_kwargsc Z|s|Stt|jj}t |}t d|D}|st |t |kDr|Dcgc]+}|jtjjus*|-}}t |t |k(r0t|jdt |dt |dt|jdt |dt |dt |dt|}t|D]m\} } | t |k\r|S|| }|jtjj k(r|S|jt"t$fvs_| ||j&<o|Scc}w)aConvert positional arguments to keyword arguments using function signature. This helper function takes positional arguments and converts them to keyword arguments by matching them with parameter names from the function signature. This enables consistent argument handling in the deprecation wrapper. Args: func: Function whose signature provides parameter names. fn_args: Tuple of positional arguments passed to the function. fn_kwargs: Dictionary of keyword arguments already passed. Returns: Dictionary combining converted positional arguments and existing kwargs, where positional args are now mapped to their parameter names. Conversion stops when encountering var-positional parameters (``*args``) because they cannot be safely represented as keyword arguments. Example: >>> from pprint import pprint >>> def example_func(a, b, c=3): pass >>> pprint(_update_kwargs_with_args(example_func, (1, 2), {'c': 5})) {'a': 1, 'b': 2, 'c': 5} c3jK|]+}|jtjjk(-ywNr1rtrVAR_POSITIONAL.0r4s r- z+_update_kwargs_with_args..s&`PUUZZ7+<+<+K+KK`13z () takes z positional argument(s) but got z positional argument(s)z to )r+r parametersvaluesr5anyrFdefaultrtremptyr)r<dict enumerater1rr2r3rm) rrrr/positional_paramshas_var_positionalr4required_positional_paramsupdated_kwargsindexr}s r-_update_kwargs_with_argsrs.  .&1188: ;F.v6`Y_`` #g,5F1G"G9J%wemm_f_p_p_v_vNve%w"%w ) *c2C.D D$$%Ys3D/E.FFfw<. 79   !3/I+J*K4PSTePfOgh..1'l^;R T  )_N(- s CK    u  ::**99 9   ::/+@A A),N5:: &- '&xs ++F(F(ct|}|Dcic],}|dtjjk7s$|d|d.}}t t |j t |j zScc}w)a?Merge function default values with provided keyword arguments. This helper fills in default parameter values from the function signature for any parameters not explicitly provided. Provided kwargs take precedence over defaults. Args: func: Function whose signature provides default parameter values. fn_kwargs: Dictionary of keyword arguments provided by caller. Returns: Dictionary with defaults merged with provided kwargs, where provided values override defaults. Example: >>> from pprint import pprint >>> def example_func(a=1, b=2, c=3): pass >>> pprint(_update_kwargs_with_defaults(example_func, {'b': 20})) {'a': 1, 'b': 20, 'c': 3} Note: Parameters without defaults (inspect.Parameter.empty) are not included in the result. r?r)rrtrrrr+items)rrfunc_arg_type_valr} fn_defaultss r-_update_kwargs_with_defaultsrsu.:$?->dc#a&GL]L]LcLcBc3q63q6>dKd [&&()D1B,CC DDes %A? A?streamrdextrasc t|}|jd|}td||d|}||z} |||y#t$r ||YywxYw)udIssue a deprecation warning using the specified stream and message template. This is the core warning issuer that formats and emits deprecation warnings. It extracts source function metadata and combines it with provided template variables to generate the final warning message. Args: stream: Callable that outputs the warning (e.g., warnings.warn, logging.warning). source: The deprecated function/method being wrapped. template_mgs: Python format string with placeholders for message variables. stacklevel: Passed to ``warnings.warn`` so the warning points to the user's call site. Default 4 accounts for the ``_raise_warn → _raise_warn_callable/_raise_warn_arguments → wrapped_fn → caller`` chain. **extras: Additional string values to substitute into the template (e.g., deprecated_in="1.0", remove_in="2.0"). Note: Automatically extracts source_name and source_path from the source callable: - For regular functions: uses ``__name__`` - For ``__init__`` methods: extracts class name from ``__qualname__`` Example: >>> import warnings >>> def old_func(): pass >>> _raise_warn( ... warnings.warn, ... old_func, ... "%(source_name)s deprecated in %(version)s", ... version="1.0" ... ) r=)rrrcN)_source_display_namerCrr)) rr6r%rdrrrmsg_argsmsgs r- _raise_warnrsiH'v.K&&'q 6KO OOH  !Csz* s s <AAct|jdk(r|jjddS|jS)zJReturn display name: class name for ``__init__``, function name otherwise.r9r=)r:r<rN)r6s r-rr s517J1N6   $ $S )" -cTZTcTccrorr c t|r$|j}|jd|}t} n d\}}t} t |||xs| |||||y)a Issue deprecation warning for callable (function/class) deprecation. This specialized warning issuer handles deprecation of entire functions or classes that are being replaced by new implementations. It automatically determines the appropriate message template based on whether a target callable is specified. Args: stream: Callable that outputs the warning (e.g., warnings.warn, logging.warning). source: The deprecated function/method being wrapped. target: The replacement implementation: - Callable: Forward to this function/class - None: No forwarding (warning only mode) - bool: Not applicable for this function (use _raise_warn_arguments instead) deprecated_in: Version when the source was marked deprecated (e.g., "1.0.0"). remove_in: Version when the source will be removed (e.g., "2.0.0"). template_mgs: Custom message template. If None, uses :data:`TEMPLATE_WARNING_CALLABLE` when a target callable is provided, otherwise :data:`TEMPLATE_WARNING_NO_TARGET`. stacklevel: Passed through to :func:`_raise_warn`; default 4 points to the user's call site. Template Variables Available: - source_name: Function name (e.g., "old_func") - source_path: Full path (e.g., "mymodule.old_func") - target_name: Target function name (only if target is callable) - target_path: Full target path (only if target is callable) - deprecated_in: Version parameter value - remove_in: Version parameter value Example: >>> import warnings >>> def new_func(): pass >>> def old_func(): pass >>> _raise_warn_callable( ... stream=warnings.warn, ... source=old_func, ... target=new_func, ... deprecated_in="1.0", ... remove_in="2.0" ... ) >>> # Outputs: "The `old_func` was deprecated since v1.0 in favor of >>> # `__main__.new_func`. It will be removed in v2.0." r=)r;r;)rr6r%rdrr r!r"N)rfr:rCTEMPLATE_WARNING_CALLABLETEMPLATE_WARNING_NO_TARGETr) rr6r7rr r%rdr!r" template_warns r-_raise_warn_callablersffoo **+1[M: 1 #) [2 !2]# ro argumentsc dj|jDcgc]\}}t|t|dzc}}} t |||xst |||| ycc}}w)aIssue deprecation warning for deprecated function arguments. This specialized warning issuer handles deprecation of specific function parameters that are being renamed or removed. It generates a mapping string showing the old-to-new argument names. Args: stream: Callable that outputs the warning (e.g., warnings.warn, logging.warning). source: The function/method whose arguments are deprecated. arguments: Mapping from deprecated argument names to new names (e.g., ``{'old_arg': 'new_arg', 'removed_arg': None}``). deprecated_in: Version when arguments were marked deprecated (e.g., "1.0.0"). remove_in: Version when arguments will be removed (e.g., "2.0.0"). template_mgs: Custom message template. If None, uses default template. stacklevel: Passed through to :func:`_raise_warn`; default 4 points to the user's call site. Template Variables Available: - source_name: Function name (e.g., "my_func") - source_path: Full path (e.g., "mymodule.my_func") - argument_map: Formatted string showing mappings (e.g., "`old` -> `new`") - deprecated_in: Version parameter value - remove_in: Version parameter value Example: >>> import warnings >>> def my_func(old_arg=1, new_arg=1): pass >>> _raise_warn_arguments( ... warnings.warn, ... my_func, ... {'old_arg': 'new_arg'}, ... "1.0", ... "2.0" ... ) >>> # Outputs: "The `my_func` uses deprecated arguments: `old_arg` -> `new_arg`. >>> # They were deprecated since v1.0 and will be removed in v2.0." z, )old_argnew_arg)rdrr r#N)joinrTEMPLATE_ARGUMENT_MAPPINGstrrTEMPLATE_WARNING_ARGUMENTS) rr6rrr r%rdabargs_maps r-_raise_warn_argumentsrUsjZyydmdsdsduv\`\]_`3!PSTUPV6WWvwH22#wsA! wrapper_fnnormalized_targetargsdep_cfg).N num_warnssource_has_var_positionalsource_is_stackedc tt|jxjdz c_|jrF|rDj s8t jd|jdtdtdd_t|} t|||}|tjuxs t|} i} |j rO|tj"us t|r2|j j%Dcic] \}}||vs ||} }}| s2| s0|j&r|tj"us| st)d| |id S| rt+fd | Dd }n j,}t.dz}|r|d ks||kr| rFt1||||j2|j4|j6| xj,dz c_ne| rct9||| |j2|j4|j6|| D].}j:j=|d dzj:|<0| r|j r|tj"us t|r|j t?|}jADchc]}|s| c}t?t|rrazr' has an invalid deprecation configuration; verify your `@deprecated(target=...)` arguments. Will be TypeError in r=rbrcTN) short_circuitoriginal_kwargsresolved_kwargsreason_argument target_funcc3VK|] }jj|d"yw)rN) warned_argsrK)rr}states r-rz#_build_call_plan..s$R3**..sA6Rs&)r)r)rr6r7rr r%rd)rr6rrr r%rdr?kr&cH|vxrj|v}|vxr| Sr)rK)rremapped_amrename_sourcesrename_targetstarget_defaultss r-is_default_droppedz,_build_call_plan..is_default_droppeds1.P3771:3P.?x<?roF)*r r_statecalled misconfiguredwarned_misconfiguredrgr r:rhrirrrrkrf args_mappingrjr args_extrarmin warned_callsrrrr r%rrrKsetrrrtrrrrrrupdater) rr6r7rrrxrrrrrrreason_callablerrr nb_warned_stacklevel_to_callerr} caller_keysv full_defaultsrr args_skipvalrrrrrrs @@@@@r-_build_call_planrsZf $j 1 8 8E LLAL0J0J  !VVgUhhi k   &*"6lO %fdF ;F':+<+<<[IZ@[O02O!2j6K6K!KxXiOj,3,@,@,F,F,HXDAqAQWK1a4XX ##(9Z=R=R(R!+"   R/R\]^ && :A= 9q=I $9  !%33!++$110    ! #   !)%33!++$110 ' K).):):)>)>sA)F)J!!#& K   %6*:O:O%OS[\mSn&&Cf+K),;Aa;N XN)* AARS#1vW%6%6%<%<<F# #18HM @c @d @ @(5':':'<jtq![@PTfghTiadjFj1&&AF!2j6K6K!KxXiOj$+$8$8ZS@T@TUX@YSZ ZNTllnu(#s`ckt`t7''++C07C#=uu0J4I4IIXVgMh g(() 15K!"*63DfM ''  EY|< #k[usB QQ QQ=+Q"Q!7Q!Q'Q'1 Q,>"Q,r;r>Fautorrskip_ifupdate_docstringdocstring_style)rrstmkdocsmarkdownc  t  ddttttt t fdtdtf   f d S)uDecorate a function/method with warning message and forward calls to target. This decorator marks a function or method as deprecated and can automatically forward all calls to a replacement implementation. It supports argument mapping, custom warning messages, and flexible warning control. For **generator functions** (``def gen(): yield``) and **async generator functions** (``async def gen(): yield``), the deprecation warning fires at call time — when the (async) generator object is created — not at first iteration. The generator body executes lazily as normal when iterated (``next()`` / ``async for``). Args: target: How to handle the deprecation. Defaults to :attr:`~deprecate.TargetMode.NOTIFY` (warn-only; source body executes unchanged). Pass an explicit value to forward calls or remap arguments: - ``Callable``: Forward all calls to this callable (function, method, or class target). The decorated function's body is **not executed** under normal forwarding — use ``pass`` or ``...`` as the body. **Exception**: when ``skip_if`` evaluates ``True`` at call time, the source body executes as a fallback, so keep a working implementation if you combine ``target=Callable`` with ``skip_if``. - :attr:`~deprecate.TargetMode.ARGS_REMAP` (or legacy ``True``): Self-deprecation — deprecate argument names only, remapping them within the same function body - :attr:`~deprecate.TargetMode.NOTIFY` (default): Warning-only mode — no forwarding, source body executes normally Omitting ``target`` is the preferred way to express warn-only deprecation. Passing ``target=None`` is a legacy synonym that also resolves to :attr:`~deprecate.TargetMode.NOTIFY` but emits a :class:`FutureWarning` directing you to use the enum form. deprecated_in: Version when the function was deprecated (e.g., "1.0.0"). Default is empty string. remove_in: Version when the function will be removed (e.g., "2.0.0"). Default is empty string. stream: Function to output warnings (default: :func:`~deprecate.deprecation.deprecation_warning`, which is :func:`warnings.warn` with ``FutureWarning`` category). Set to ``None`` to disable warnings entirely. num_warns: Number of times to show warning per function or per deprecated argument: - ``1`` (default): Show warning once per function/argument - ``-1``: Show warning on every call - ``0``: Suppress deprecation warnings emitted for the decorated function/argument - ``N > 1``: Show warning N times total template_mgs: Custom warning message template with format specifiers: - ``source_name``: Function name (e.g., "my_func") - ``source_path``: Full path (e.g., "module.my_func") - ``target_name``: Target function name (only for callable targets) - ``target_path``: Full target path (only for callable targets) - ``deprecated_in``: Value of deprecated_in parameter - ``remove_in``: Value of remove_in parameter - ``argument_map``: String showing argument mapping (for args deprecation only) Example: ``"v%(deprecated_in)s: `%(source_name)s` was deprecated."`` args_mapping: Map or skip arguments when forwarding: - ``{'old_arg': 'new_arg'}``: Rename argument - ``{'old_arg': None}``: Skip argument (don't forward it) - ``{}``: Empty mapping (no remapping) Works with both ``target=Callable`` and ``target=True``. args_extra: Additional arguments merged into kwargs before the call. Used when target is a Callable or :attr:`~deprecate._types.TargetMode.ARGS_REMAP` (with ``args_mapping``). Ignored when target is :attr:`~deprecate._types.TargetMode.NOTIFY`. Example: ``{'new_required_arg': 42}`` skip_if: Conditionally skip deprecation warning and forwarding: - ``bool``: Static condition (True = skip deprecation) - ``Callable``: Function returning bool (checked at runtime, must return bool) If condition is True, original function executes without warning. update_docstring: If True, automatically inject a deprecation notice into the function's docstring (inserted before Google/NumPy-style sections when present, otherwise appended at the end). docstring_style: Output style for injected deprecation notice when ``update_docstring=True``. Supported values: - ``"auto"`` (default): Automatically choose a style based on the current environment (e.g., loaded modules, CLI/tooling context). This may resolve to either ``"rst"`` or ``"mkdocs"``/``"markdown"`` at decoration time. - ``"rst"``: Explicitly force Sphinx-style ``.. deprecated::`` directive. - ``"mkdocs"`` or ``"markdown"``: Explicitly force a Markdown admonition of the form ``!!! warning "Deprecated in X"``. Validated eagerly at decoration time regardless of ``update_docstring``. Returns: Decorator function that wraps the source function/method. Warns: UserWarning: If applied directly to a class. The decorator delegates to :func:`~deprecate.proxy.deprecated_class` and emits this warning. Use ``@deprecated_class()`` directly to suppress it. Suppressed when ``stream=None``. UserWarning: If ``deprecated_in`` is absent, ``stream`` is not ``None``, no ``template_mgs`` is set, and the decorated source is not a class. Fired at decoration time (not call time) to catch missing version metadata early. Suppressed by passing ``stream=None`` or ``template_mgs``. Raises: TypeError: If the source is a class method and target is a method on a *different* class (cross-class method forwarding detected at decoration time via ``__qualname__`` comparison). Skipped silently when the target's qualname prefix names a class absent from the target's module globals. TypeError: If skip_if is a callable that doesn't return a bool. TypeError: If arguments in args_mapping don't exist in target function and target doesn't accept **kwargs. Example: >>> # Basic forwarding >>> def new_func(x: int) -> int: ... return x * 2 >>> @deprecated(target=new_func, deprecated_in="1.0", remove_in="2.0") ... def old_func(x: int) -> int: ... pass >>> # Argument mapping >>> @deprecated( ... target=new_func, ... args_mapping={'old_name': 'new_name', 'unused': None} ... ) ... def old_func(old_name: int, unused: str) -> int: ... pass >>> # Self-deprecation >>> from deprecate import TargetMode >>> @deprecated(target=TargetMode.ARGS_REMAP, args_mapping={'old_arg': 'new_arg'}) ... def my_func(old_arg: int = 0, new_arg: int = 0) -> int: ... return new_arg * 2 >>> # Warn-only (default — no target needed) >>> @deprecated(deprecated_in="1.0", remove_in="2.0") ... def legacy_func(x: int) -> int: ... return x r6 _stacklevelr&c  tttfr< j|dz}ttr t|St|Sttrj #j j j k7r j nd}t j  j |dzndjj|Sttrt j|dzSt%sC#A%s?tjs*tjdj dt"|tjrtddl}|j'd}|j(}dj d}$*tj$st$t*s|d z }#tj|t"|$d u}t$t*r$} n`t-$rtj$r$} n=$t$t.rt+j0$|dz} nt*j2} | t*j2uxrt/xs} |xs| } } } | t*j2ur+t+j4| j |dz d} d} || !#| | &| St-$r!tj$s t7$t9$t;rd t=nd d }tt*r7t$t*r't+j4j |dz }t?dtAjBjED$t$t.rt+j0$d}nt$t*r$}n$}$d uxs|}tG!j ||% }|tjHrdtKdtLdtLdtLf"#$f d tOtP}||_)tU|_+&r tYStKdtLdtLdtLf"#$f d tOtP}||_)tU|_+&r tYS)Nr>z`@deprecated` on `z` has no `deprecated_in` set. Deprecation notices and generated documentation will omit the `deprecated_in` version. Pass `deprecated_in` for a meaningful deprecation notice.rcrzdeprecate.proxyz&Direct use of `@deprecated` on class `zy` is deprecated since `v0.6.0`. Use `@deprecated_class(...)` instead. This will become a `TypeError` in a future release.zs Note: non-class `target` values are ignored when deprecating classes; use `@deprecated_class(target=...)` instead.F)rrrd) r7rr rrrrrr_misconfigured_overrideTc3jK|]+}|jtjjk(-ywrrrs r-rz.deprecated..packing..<s*( ?DEJJ'++:: :( r) rr rmr7rrrrr%rrxr&c  Kt r n t }t|tstdt ||r |i|d{St  ||  }|j r6 r |i|jd{S di|jd{S|jP r4|js |jn |j} |i|d{S di|jd{Stj|jr$|jdi|jd{S|jdi|jS77777l7+w)N4User function 'skip_if' shall return bool, but got: rr6r7rrrxrrrrrr) rfrrrqr)typerrrrrrrtiscoroutinefunction)rrx shall_skipplan call_kwargs_dep_cfg_source_is_stacked_targetasync_wrapped_fnrrr6rrr7s r-rz5deprecated..packing..async_wrapped_fnbs*27*;WYg !*d3#&Z[_`j[kZl$mnn!'!8!888 (/!!&-!$!'.G&8 %%0%+T%JT5I5I%JJJ!'!?$*>*>!???##+0BFBVBVd&:&:\`\p\p %+T%A[%AAA!'!?$*>*>!???..t/?/?@!1!1!1!ID4H4H!III't''?$*>*>??C9* K? B?JsnAE:E-=E:E0E:-E2.AE:/E40E: E6 AE: E8 !E:0E:2E:4E:6E:8E:c  t r n t }t|tstdt ||r |i|St  ||   }|j r& r |i|jS di|jS|j@ r,|js |jn |j} |i|S di|jStj|jr0td|jjd jd|jdi|jS)NrrzAsync target `z2` cannot be invoked from a sync wrapper. Declare `z=` as `async def`, or replace the target with a sync callable.r)rfrrrqr)rrrrrrrrtrr:)rrxrrrrrrrrr6rrr7 wrapped_fns r-rz/deprecated..packing..wrapped_fnso&.w&7T']Jj$/"VW[\fWgVh ijjt.v.. $%") #*C"4 D!!,!4@4+?+?@@5 4 455',>B>R>R$"6"6X\XlXlK!47;775 4 455**4+;+;<$T%5%5%>%>$?@!!' 11np$4##;d&:&:; ;ro)-rq classmethod staticmethod__func__propertyfget__doc__fsetfdelrrr.rtrurgr r:ri importlib import_moduledeprecated_classrrfrrrsrk _validater^rwrrnrrrrrrrrr rrerrr)'r6r wrapped_inner explicit_docr  proxy_moduler messageclass_misconfiguredforward_targetnotify_misconfigforce_misconfiguredforward_args_mappingforward_args_extra_function_misconfigured stored_targetrdep_metaasync_wrapped_fn_typedwrapped_fn_typedrrrrrrrrrrnormalized_docstring_stylerpackingr rrr7r%rs'` @@@@@@r-rzdeprecated..packings f{L9 :#FOO[1_EM1;FK1P;}- qVbcpVq q fh '/5kk.AV^^W]WbWbWjWjEj6>>quL9?9P [1_5VZ     fo ."76;; a#HI I |,!3LQXQ`Q`agQh MM$V__$56MM&   ??6 " $223DEL+<< 98IJmm !'//&*A*U[]gJhD! g{{K #)E/ &*-&,&!goof&=!':fd#;",!8!8KZ[O!\!+!2!2 .1B1BBgtLLf\fGg "5"I9I $0 !+ !2!22$$"OO!-)*Q (,$%)" #%+##1-!1 /(;    F GOOF$; ,VV <#FF3  (!%  +FG Z5!+!8!8D!QM  +"M"M%B+B $' %!'6%    & &v . 6]& @c& @S& @S& @& @& @P&**=?O%P "4< " 1,9O " )23CD# # v( s^@";?!KKh \8_TUKK KKKZ Nro)ArrtrHrg functoolsrrrrtypingrrr r r r r deprecate._typesrrrrrrrdeprecate.docstring.injectrrdeprecate.utilsrrrhrr__annotations__rrrrr2r3 FutureWarningdeprecation_warningrr ArgsMappingr$r.r+r5r^rnrrrwrtuplerrrrrrrrkr rror-r+s^  55@@eM%&s&- \ =k++!77d];3 %& ,$sCx.#4,a4(9(9#:atGDUDU?Va ZXZxZDZzV ,?V uU_aiUiOjV osV r< < $h 2 3< :x  <~+ + + cN+ +\181eCHo1RVWZ\_W_R`1eijmorjres1hExEDcNEtTWY\T\~EB4 , , ,, ,  ,  ,^ddcd#'3C C C $h 2 3C C  C 3- CC CX#'36 6 66 6  6 3- 66 6rmc"m S#X m $hsCx0*< =mXc3h/;< m S/ m cN mm Xi( )mm $mmmb7A6G6G!4"&*.+/%*"DJO $h 2 3OOO X  O  O 3- O;'Oc3h(O4> "OO@AOxS!"HS#X$667Oro