7GiTdZddlZddlmZmZddlmZmZmZm Z ddl m Z ddl m Z dZdZd Zd Zd Zee e Zd edededefdZd ededefdZdededededdf dZ d)dedede deefdededeeddfdZ d)dededeeefdededeeddfdZdeddfdZd d ed!dddd"d"f de edefdededeed#edeed$eeeefd%eeeefd&e eefd'edefd(Z y)*aDeprecation wrapper and utilities for marking deprecated code. This module provides the main @deprecated decorator for marking functions, methods, and classes as deprecated while optionally forwarding calls to their replacements. Key Components: - 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-2023 Jiri Borovec <...> N)partialwraps)AnyCallableOptionalUnion)warn)!get_func_arguments_types_defaultszThe `%(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.zI .. deprecated:: %(deprecated_in)s %(remove_text)s %(target_text)s )categoryfuncfn_args fn_kwargsreturnc|s|St|}|Dcgc]}|d }}|jtt|||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 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} r)r updatedictzip)r r rfunc_arg_type_valarg arg_namess e/home/nelsen/Projects/HRI/fr-in-the-cloud/.venv/lib/python3.12/site-packages/deprecate/deprecation.py_update_kwargs_with_argsr/sT. 9$?#45CQ5I5 T#i123 6s Act|}|Dcic]"}|dtjk7s|d|d$}}tt |j t |j zScc}w)aAMerge 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._empty) are not included in the result. r)r inspect_emptyrlistitems)r rrr fn_defaultss r_update_kwargs_with_defaultsr Psm2:$?->[c#a&GNNBZ3q63q6>[K[ [&&()D1B,CC DD\s A5 A5streamsource template_mgsextrasc |jdk(r|jjddn |j}|jd|}t d||d|}|||zy)aIssue 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 **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" ... ) __init__.) source_name source_pathN)__name__ __qualname__split __module__r)r!r"r#r$r)r*msg_argss r _raise_warnr1osk<9?:8U&%%++C04[a[j[jK&&'q 6KO OOH <( "#target deprecated_in remove_inc t|r(|j}|jd|}|xst}nd\}}|xst}t |||||||y)amIssue 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 default template based on whether target is callable or None 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')r7)r!r"r#r4r5 target_name target_pathN)callabler,r/TEMPLATE_WARNING_CALLABLETEMPLATE_WARNING_NO_TARGETr1)r!r"r3r4r5r#r8r9s r_raise_warn_callabler=sjdoo **+1[M: #@'@ #) [#A'A !#r2 argumentsc dj|jDcgc]\}}t||dzc}}}|xst}t ||||||ycc}}w)a8Issue 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 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)r4r5 argument_mapN)joinrTEMPLATE_ARGUMENT_MAPPINGTEMPLATE_WARNING_ARGUMENTSr1) r!r"r>r4r5r#abargs_maps r_raise_warn_argumentsrIs`Xyy_h_n_n_pqW[WXZ[3!PQ6RRqrH=#=L MU^muvrsA wrapped_fnct|dr |jsy|jj}t|di}|j dd}|j d}|rd|dnd}t |rd |j d|jd nd}|jt|j d d||d zd j||_y)aAppend deprecation notice to function's docstring in reStructuredText format. This helper automatically generates and appends a Sphinx-compatible deprecation notice to the wrapped function's docstring. The notice includes version information and target replacement (if applicable), making it visible in generated API documentation. The appended notice follows the Sphinx deprecated directive format: .. deprecated:: Will be removed in . Use `` instead. Args: wrapped_fn: Function whose docstring should be updated. Must have __deprecated__ attribute set with deprecation metadata Returns: None. Modifies the function's __doc__ attribute in-place. Metadata Used: The function's __deprecated__ attribute should contain: - deprecated_in: Version when deprecated - remove_in: Version when will be removed - target: Replacement callable (optional) Example: >>> def new_func(): pass >>> def old_func(): ... '''Original docstring.''' ... pass >>> old_func.__deprecated__ = { ... 'deprecated_in': '1.0', ... 'remove_in': '2.0', ... 'target': new_func ... } >>> _update_docstring_with_deprecation(old_func) >>> print(old_func.__doc__) # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE Original docstring. .. deprecated:: 1.0 Will be removed in 2.0. Use `deprecate.deprecation.new_func` instead. .. note: Does nothing if the function has no docstring or no __deprecated__ attribute. __doc__N__deprecated__r5r7r3zWill be removed in r'zUse `z ` instead.r4)r4 remove_text target_text ) hasattrrL splitlinesgetattrgetr:r/r,appendTEMPLATE_DOC_DEPRECATEDrC)rJlinesdep_info remove_in_val target_valrNrOs r"_update_docstring_with_deprecationr[s^ :y )1C1C    ) ) +Ez#3R8HLLb1Mh'J&&  5)Jr2r7F num_warns args_mapping args_extraskip_ifupdate_docstringc P dtdtf f d } | S)a Decorate a function or class with warning message and forward calls to target. This decorator marks a function or class as deprecated and can automatically forward all calls to a replacement implementation. It supports argument mapping, custom warning messages, and flexible warning control. Args: target: How to handle the deprecation: - ``Callable``: Forward all calls to this function/class - ``True``: Self-deprecation mode (deprecate arguments within same function) - ``None``: Warning-only mode (no forwarding, function body executes normally) deprecated_in: Version when the function was deprecated (e.g., "1.0.0"). remove_in: Version when the function will be removed (e.g., "2.0.0"). stream: Function to output warnings (default: FutureWarning). Set to ``None`` to disable warnings entirely. num_warns: Number of times to show warning per function call: - ``1`` (default): Show warning once per function - ``-1``: Show warning on every call - ``N``: Show warning N times 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 - ``target_path``: Full target path - ``deprecated_in``: Value of deprecated_in parameter - ``remove_in``: Value of remove_in parameter - ``argument_map``: String showing argument mapping (for args deprecation) 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) Works with both ``target=Callable`` and ``target=True``. args_extra: Additional arguments to pass to target function. Example: ``{'new_required_arg': 42}`` skip_if: Conditionally skip deprecation: - ``bool``: Static condition - ``Callable``: Function returning bool (checked at runtime) If True/returns True, no warning is shown and original function executes. update_docstring: If True, automatically append deprecation information to the function's docstring. Useful for documentation generation tools. Returns: Decorator function that wraps the source function/class. Raises: 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:: >>> @deprecated(target=True, args_mapping={'old_arg': 'new_arg'}) ... def my_func(old_arg: int = 0, new_arg: int = 0) -> int: ... return new_arg * 2 r"rc  tdtdtdtf f d td d r tS)Nargskwargsrc p trn t}t|tstdt ||r|i|St dd}t d|dzt||}duxs t}i}r*r(jDcic] \}}||vs ||}}}|s |sd i|S|r)|Dcgc]}t d|d} }t| } n t dd} rsdks| kri|r!tt d| dznF|rDt||Dcgc]}d| } }| D]} t | t | ddz|r t|}rOrMDcgc] }|r | } }|jDcic]\}}|| vs j|||}}}rr|jtsd i|Stj r j"n}t%|Dcgc]}|d }}tj&|}|j(}|Dcgc] }||vs| }}|r|tdj*d||d i|Scc}}wcc}wcc}wcc}wcc}}wcc}wcc}w) Nz7User function `shall_skip` shall return bool, but got: _calledrr\_warned__warnedzFailed mapping of `z'`, arguments missing in target source: r+)r:bool isinstance TypeErrortyperSsetattrrrminr=rIr rTrrisclassr&r getfullargspecvarkwr,)rdre shall_skip nb_calledreason_callablereason_argumentrFrGr arg_warns nb_warned attrib_namesn args_skipval target_func target_argstarget_full_arg_specrrmissedr_r^r4r]r5r`r"r!r3r#rJs rrJz/deprecated..packing..wrapped_fns'/w&7T']Jj$/"YZ^_iZjYk lmmt.v.. Iq9I J 9q= 9-fdFCF$n@0@O O4@4F4F4H"XDAqAQWK1a4"X"X#'''Raa#WZ8C51A1Ea a N $J 1= 9q=I ,A"(PY[ghJ 9q=A$)&&/=Zceqr@O#Phse$4#PL#P)N Awz1a/H1/LMN5ffE,8RS S@QSR RKQ,,.qhc3\_gp\p,**34c9qqf j)F#'''.5__V-D&//&K-N{-[\c3q6\K\$+#9#9+#F (..E&,Fcs+/EcFFF%-"5foo5FFmntmu vww(( (u#Yb$QSr]GsB$ J1J J J J#J#, J(9J() J. J3&J3rM)r4r5r3r^)rrrnr[) r"rJr_r^r4r]r5r`r!r3r#ras `@rpackingzdeprecated..packingsn vK )cK )SK )SK )K ) K )\   !.& ,     .z :r2)r) r3r4r5r!r]r#r^r_r`rars `````````` r deprecatedrJs)f^^X^^@ Nr2)N)!rLr functoolsrrtypingrrrrwarningsr deprecate.utilsr r;rErDr<rV FutureWarningdeprecation_warningtuplerrr strr1rjr=rIr[intrr+r2rrss $11=- \ =k d];8eQUBExEDETE>!$!$(!$#!$QT!$Y]!$T#' A A A $h& 'A A  A 3- A AT#' .w .w .wCH~.w .w  .w 3- .w .wb?*8?*?*H!4"&-1+/%*"s $h& 'sss X  s  s 3- s4S>*sc3h(s4> "sssr2