^j UdZddlZddlZddlmZddlmZmZmZm Z m Z ddl m Z m Z mZddlmZmZmZmZmZmZddlmZmZdZeed <Gd d Z d%d d d eddddddd dedededede edde ede eee efde eeefdededdedee gd ffdZ!d d d d edddd d!ed"edededede edde ed#ede eeefdd fd$Z"y)&aYProxy utilities for deprecating Python object instances and classes. Provides :func:`~deprecate.proxy.deprecated_instance` for wrapping any Python object with transparent deprecation warnings and optional read-only enforcement, and :func:`~deprecate.proxy.deprecated_class` as a class-level decorator with optional target redirection. Typical use cases: - Deprecating module-level config dicts, constants, or legacy singletons while still allowing reads during a migration window. - Deprecating an Enum or dataclass in favor of a replacement type, with automatic forwarding of all attribute, item, and call access. Example: >>> import warnings >>> cfg = {"threshold": 0.5} >>> proxy = deprecated_instance(cfg, deprecated_in="1.0", remove_in="2.0", stream=None) >>> proxy["threshold"] 0.5 >>> proxy.get("threshold") 0.5 N)Iterator)AnyCallableLiteralOptionalcast)DeprecationConfig TargetMode _ProxyConfig)TEMPLATE_ARGUMENT_MAPPINGTEMPLATE_WARNING_ARGUMENTSTEMPLATE_WARNING_CALLABLETEMPLATE_WARNING_NO_TARGET_validate_template_mgsdeprecation_warning)"_update_docstring_with_deprecationnormalize_docstring_style_DEFAULT_STACKLEVEL_TO_CALLERceZdZdZddddddeddddd ded ed ed eeeeefd eeeefd edede dee ddeede dede ddfdZ e defdZe defdZdddeeddfdZdeddfdZe defdZdefd Zd!eeefdeeeffd"Zd!eeefdeeeffd#Zed ede fd$Zd edefd%Zd ed&eddfd'Zd eddfd(Zd)edefd*Zd)ed&eddfd+Zd)eddfd,Zde fd-Z de!efd.Z"d/ede fd0Z#d1ed!edefd2Z$d3e%de fd4Z&d3e%de fd5Z'de fd6Z(defd7Z)defd8Z*de fd9Z+d:e%de fd;Z,d_DeprecatedProxyuU Transparent proxy that emits deprecation warnings on attribute and item access. Wraps any Python object and forwards all read operations (attribute lookup, subscript, iteration, calls) to the underlying object — or to an optional *target* replacement — while emitting a configurable :class:`FutureWarning`. In *read-only* mode any attempt to mutate the proxied object via ``__setitem__``, ``__delitem__``, or ``__setattr__`` raises :class:`AttributeError`. Use :func:`~deprecate.proxy.deprecated_instance` or :func:`~deprecate.proxy.deprecated_class` to create instances rather than instantiating this class directly. Args: obj: The deprecated object to wrap (the *source*). name: Display name used in the warning message. deprecated_in: Version string when the object was deprecated. remove_in: Version string when the object will be removed. num_warns: Maximum number of warnings to emit. ``1`` (default) warns once; ``-1`` warns on every access. stream: Callable used to emit warnings. Defaults to :data:`~deprecate.deprecation.deprecation_warning` (:class:`FutureWarning`). Pass ``None`` to suppress warnings. **Note:** the built-in stacklevel budget assumes *stream* is :func:`warnings.warn` itself or a C-level :func:`functools.partial` of it; a Python-defined wrapper interposes an extra frame and the warning will appear to originate inside :mod:`deprecate.proxy` rather than the caller. template_mgs: Optional custom warning message template that overrides the built-in templates. When ``None`` (default), the built-in template for the active scenario is used (callable-target, no-target, or per-argument). See :func:`~deprecate.proxy.deprecated_class` for the available ``%``-style placeholders. read_only: If ``True``, raise :class:`AttributeError` on any write attempt through the proxy. Only the following standard collection mutator names are intercepted: ``append``, ``clear``, ``discard``, ``extend``, ``insert``, ``pop``, ``remove``, ``setdefault``, ``update``, ``add``. Custom method names (e.g. ``register()``, ``reload()``, ``set_value()``) are not blocked. target: Optional replacement object. When set, all attribute, item, and call access is forwarded to *target* instead of *obj*. args_mapping: Optional dict remapping keyword argument names when the proxy is called. Keys are old argument names; values are new names, or ``None`` to drop the argument entirely. NFauto) target args_mapping args_extra deprecated_in remove_in num_warnsstream template_mgs read_onlydocstring_style_misconfigured_overrideobjnamerrrrrr r!.Nr"r#r$r%returnc t| |duxs| }t|trtj||d}||rtj }t|tr|tj ||||dz}t|| || || }tj|d|t|||||||t| | }tj|d |t|d d}|rtj|d |yy) aInitialise the proxy with typed runtime/config dataclasses. ``__config`` stores private mutable runtime state in :class:`~deprecate._types._ProxyConfig` (obj, stream, num_warns, read_only, args_extra, warned counter). ``__deprecated__`` is the public metadata interface consumed by audit tools (:func:`~deprecate.audit.validate_deprecation_wrapper`, :func:`~deprecate.audit.find_deprecation_wrappers`, etc.) as a :class:`~deprecate._types.DeprecationConfig` instance aligned with the ``@deprecated`` schema. ``_misconfigured_override`` is a private hook used by :func:`~deprecate.deprecated` when it delegates to :func:`~deprecate.deprecated_class` for class targets: it lets the caller pre-compute misconfig signals (raw ``target=False`` plus NOTIFY+args_mapping / NOTIFY+args_extra detected upstream) before the proxy rewrites them away, so the final frozen :class:`~deprecate._types.DeprecationConfig` records every signal in one place. Fr)r stacklevelN)rrr+)r&r!r r#rr"_DeprecatedProxy__config) rrr'rrr misconfiguredr$r"__deprecated____doc__) r isinstanceboolr _from_legacy_proxy ARGS_REMAP _validater object __setattr__r rgetattr)selfr&r'rrrrrr r!r"r#r$r%r.cfgdep_meta_docs Z/var/www/ramen.bs-engineer-server.com/venv/lib/python3.12/site-packages/deprecate/proxy.py__init__z_DeprecatedProxy.__init__VsH |,%B+B fd #226 abcF >l**F fj ) Z11'>tEU'VWWr?arg_namerGc|j}|j}|sy|;|jj|d}|jdk\r9||jk\r*y|jdk\r|j |jk\ry|j }|j}|j}|j}|S|rQ||vrM||} t|t| dz} |xst} | |j|j|j| dz} nt!|rQ|j"} |j$d| }|xst&} | |j|j|j| |dz} n1|xst(} | |j|j|jdz} || t*|-|jj|dd z|j|<y|xj d z c_y#t,$r || YXwxYw) uVEmit a deprecation warning if the warn budget is not exhausted. Args: arg_name: When given, use per-argument warning tracking (``cfg.warned_args``) instead of the global ``cfg.warned`` counter. The warning is suppressed when the per-argument count has already reached ``cfg.num_warns``. When provided alongside an ``args_mapping`` entry, the emitted message uses the per-argument template (`old -> new`) rather than the generic callable template — matching the decorator's argument-deprecation form. Nr)old_argnew_arg) source_namerr argument_map.)rKrr target_name target_path)rKrrr+r)rCr! warned_argsgetr warnedrErrr"r strr r'rrcallable__name__ __module__rrr TypeError)r9rGr:r! arg_countdeprrcustom_templaterJrLtemplatemsgrNrOs r=_warnz_DeprecatedProxy._warnsii   ++Ha8I}}!i3==&@}}!cjjCMM&Aiijj'' **  LX5M"8,G48X[\cXd7eeL&D*DH"xx!$!2!2 ]] , C f  //K#../q >K&C*CH"xx!$!2!2 ]]** C'D*DH"xx!$!2!2 ]]C  3#@ A  (+(;(;Ha(H1(LCOOH % JJ!OJ   3K sG((G<;G< operationc|jjr(|jj}t d|d|dy)zRaise AttributeError when the proxy is in read-only mode. Raises: AttributeError: If ``read_only=True`` was set at construction time. 'z' is deprecated and read-only. z/ is not allowed. Migrate away from this object.N)rCr#rEr'AttributeError)r9r_r's r=_check_read_onlyz!_DeprecatedProxy._check_read_only sD 99   D D68 Crs  r?c.|jjS)zHThe deprecated source object this proxy wraps (audit contract accessor).)rCr&rBs r=wrappedz_DeprecatedProxy.wrappedsyy}}r?c|jj}|t|ts|S|jj S)z@Return the active object: *target* when set, otherwise *source*.)rErr1r rCr&)r9rs r= _get_activez_DeprecatedProxy._get_actives3!!  j&DMyy}}r?kwargsc|jj}|r|s|S|jDchc] \}}| | }}}|jDcic] \}}||vs |j|xs||"c}}Scc}}wcc}}w)zHApply args_mapping to *kwargs*, renaming or dropping keys as configured.)rEritemsrR)r9rhrkv args_to_drops r=_apply_args_mappingz$_DeprecatedProxy._apply_args_mapping%syy-- 6M&2&8&8&:HdaaiH H:@,,.b$!QAUaLa!!!$)A-bbIbs A>A> B"Bcr|jj}|s|St|}|j||S)zFMerge :attr:`_ProxyConfig.args_extra` into *kwargs*; extra values win.)rCrdictupdate)r9rhrmergeds r=_merge_args_extraz"_DeprecatedProxy._merge_args_extra-s3YY)) Mf j! r?chd}||vS)zHeuristic to detect common mutating methods on built-in collections. This is intentionally conservative and only covers the most common mutating APIs on built-in container types (lists, dicts, sets). > addpopclearappendextendinsertremoverqdiscard setdefault)r'mutating_namess r=_is_potential_mutatorz&_DeprecatedProxy._is_potential_mutator6s  ~%%r?cjtj}jjr3t |r(j rdtdtddffd }|S|S)a?Forward attribute lookup to the active object, emitting a deprecation warning. In read-only mode, common mutating methods on built-in collections (for example, ``append`` or ``update``) are wrapped so that calling them raises :class:`AttributeError` instead of mutating the underlying object. argsrhr)Nc0jddy)NzCalling mutating method 'ra)rc)rrhr'r9s r=_guarded_mutatorz6_DeprecatedProxy.__getattr__.._guarded_mutator\s%%(A$q&IJr?)r^r8rgrCr#rUrr)r9r'attrrs`` r= __getattr__z_DeprecatedProxy.__getattr__Pso t'')40 99  8D>d6P6PQU6V K Ks Kt K$ # r?valuecd|jd|dt|j||y)zForward attribute mutation to the active object, raising in read-only mode. Raises: AttributeError: If the proxy is in read-only mode. zSetting attribute 'raN)rcsetattrrg)r9r'rs r=r7z_DeprecatedProxy.__setattr__bs1  3D6;<  "D%0r?cb|jd|dt|j|y)zForward attribute deletion to the active object, raising in read-only mode. Raises: AttributeError: If the proxy is in read-only mode. zDeleting attribute 'raN)rcdelattrrg)r9r's r= __delattr__z_DeprecatedProxy.__delattr__ls/  4TF!<=  "D)r?keycH|j|j|S)zNForward subscript lookup to the active object, emitting a deprecation warning.)r^rgr9rs r= __getitem__z_DeprecatedProxy.__getitem__zs !#&&r?cT|jd|d||j|<y)zForward subscript mutation to the active object, raising in read-only mode. Raises: AttributeError: If the proxy is in read-only mode. zSetting item 'raNrcrg)r9rrs r= __setitem__z_DeprecatedProxy.__setitem__s. se156"'3r?cP|jd|d|j|=y)zForward subscript deletion to the active object, raising in read-only mode. Raises: AttributeError: If the proxy is in read-only mode. zDeleting item 'raNrrs r= __delitem__z_DeprecatedProxy.__delitem__s, uA67    s #r?c4t|jS)z>Return length of the active object without emitting a warning.)lenrgrBs r=__len__z_DeprecatedProxy.__len__s4##%&&r?cT|jt|jS)z?Iterate over the active object, emitting a deprecation warning.)r^iterrgrBs r=__iter__z_DeprecatedProxy.__iter__s D$$&''r?itemc&||jvS)zACheck membership in the active object without emitting a warning.)rg)r9rs r= __contains__z_DeprecatedProxy.__contains__st'')))r?rctj|d}tj|d}|jtjurb|j xsi}|D]}|vs|j ||j}|j|}|j|i|St|jr|j r|j xsi}|D]}|vs|j |tfd|Ds|j |j}|j|}|j|i|S|j t|jr!|j|i|jS|jtjur|j|iS|j|i|jS)aQCall the active object, emitting a deprecation warning conditionally based on target mode. Branching logic: - :attr:`~deprecate._types.TargetMode.ARGS_REMAP`: warn only when a deprecated kwarg name is present in the call; remap, merge ``args_extra``, and call ``obj``. - Callable target with ``args_mapping``: warn per deprecated kwarg present; if none of the old names were passed still warn at the callable level (class is deprecated); remap, merge ``args_extra``, and forward to target. - Callable target without ``args_mapping``: warn (global budget), merge ``args_extra``, and forward to target. - :attr:`~deprecate._types.TargetMode.NOTIFY`: always warn (global budget) and forward kwargs unchanged; ``args_extra`` is intentionally ignored (misconfig). r/r-rFc3&K|]}|v ywNr~).0old_keyrhs r= z,_DeprecatedProxy.__call__..s@Ww&(@s)r6rArr r4rr^rnrsr&rUanyNOTIFYrg)r9rrhrZr:mappingr mapped_kwargss ` r=__call__z_DeprecatedProxy.__call__s%%d,<=%%d,FG ::.. .&&,"G" 1f$JJJ0 1!44Vpropertyr rCr rEr^rcrergrnrs staticmethodrrr7rrrrrrrrrr6rrrrrrrrrr~r?r=rr1sD"R;?/30C&*%(-Q6 Q6Q6  Q6 tC#$678 Q6T#s(^,Q6Q6Q6Q6),-Q6smQ6Q6Q6"&Q6 !Q6p]l]]X'XX26I#I$IV # $ Sc$sCx.cT#s(^cS#X4S>&C&D&&2$11C1D1***'s's' (s(3(4($s$t$''((3-( ***.Kc.KS.KS.Kh"F"t"&F&t&######""($( & T  $ 4 r?rrrFr) rrr r!r"rrupdate_docstringr$r%rrrr r!r(r"rrrr$)rrstmkdocsmarkdownr%r)c L dtddf  f d } | S)uDecorator factory for deprecating class definitions with optional target redirection. Apply ``@deprecated_class(...)`` to an Enum or dataclass to wrap the class in a :class:`~deprecate.proxy._DeprecatedProxy`. All attribute, item, and call access on the resulting object will emit a deprecation warning and, if *target* is provided, will be forwarded to the replacement class. Args: target: Optional replacement class to redirect all access to. deprecated_in: Version string when the class was deprecated. remove_in: Version string when the class will be removed. num_warns: Maximum number of warnings to emit per proxy instance. ``1`` warns once; ``-1`` warns on every access. stream: Callable used to emit warnings. Defaults to :data:`~deprecate.deprecation.deprecation_warning`. template_mgs: Optional custom warning message template that overrides the built-in templates. When ``None`` (default), the built-in template for the active scenario is used (callable-target, no-target, or per-argument for ``args_mapping``). Available ``%``-style placeholders: - ``%(source_name)s`` — the deprecated class name (taken from ``cls.__name__``) - ``%(deprecated_in)s`` — value of the ``deprecated_in`` argument - ``%(remove_in)s`` — value of the ``remove_in`` argument - ``%(target_name)s`` — target class name (only when *target* is callable) - ``%(target_path)s`` — fully-qualified target path (only when *target* is callable) - ``%(argument_map)s`` — formatted ``\`old\` -> \`new\``` string (only for per-argument warnings emitted by ``args_mapping``) Example: ``"v%(deprecated_in)s: ``%(source_name)s`` -> ``%(target_name)s``"``. args_mapping: Optional dict remapping keyword argument names when the decorated class is called. Keys are old argument names; values are new names, or ``None`` to drop the argument entirely. When provided without an explicit callable *target*, the mode auto-resolves to :attr:`~deprecate._types.TargetMode.ARGS_REMAP`: the proxy warns **only when an old argument name is actually used** in the call, matching the per-argument warning behaviour of ``@deprecated(target=TargetMode.ARGS_REMAP, args_mapping=...)``. Passing ``args_mapping`` together with ``target=TargetMode.NOTIFY`` is a misconfiguration and emits a :class:`UserWarning` at decoration time (will be :class:`TypeError` in v1.0). Similarly, ``target=TargetMode.ARGS_REMAP`` without ``args_mapping`` emits a :class:`UserWarning` at decoration time. args_extra: Optional dict of extra keyword arguments merged into the forwarded call after ``args_mapping`` has been applied. Caller-supplied values override entries with the same key. Ignored when ``target`` is :attr:`~deprecate._types.TargetMode.NOTIFY` (passing both emits a :class:`UserWarning` at decoration time; will be :class:`TypeError` in v1.0). update_docstring: If ``True``, inject a deprecation notice into the class docstring at decoration time (same behaviour as ``@deprecated(update_docstring=True)``). docstring_style: Output style for the injected notice when ``update_docstring=True``. ``"auto"`` detects the doc engine at decoration time; ``"rst"`` emits a ``.. deprecated::`` directive; ``"mkdocs"`` / ``"markdown"`` emit a ``!!! warning`` admonition. Returns: A decorator that wraps the class in a :class:`~deprecate.proxy._DeprecatedProxy`. Examples: >>> from enum import Enum >>> class NewColor(Enum): ... RED = 1 >>> @deprecated_class(target=NewColor, deprecated_in="1.0", remove_in="2.0", stream=None) ... class OldColor(Enum): ... RED = 1 >>> OldColor.RED is NewColor.RED True >>> OldColor(1) is NewColor.RED True When only argument names changed, omit *target* and supply ``args_mapping``. The proxy auto-resolves to :attr:`~deprecate._types.TargetMode.ARGS_REMAP` and warns **only when the old argument name is passed**: >>> class Config: ... def __init__(self, timeout: int = 0) -> None: ... self.timeout = timeout >>> LegacyConfig = deprecated_class( ... args_mapping={"time_limit": "timeout"}, ... deprecated_in="1.5", remove_in="2.0", stream=None, ... )(Config) >>> LegacyConfig(timeout=30).timeout # new name — no remap needed 30 >>> LegacyConfig(time_limit=30).timeout # old name — remapped to timeout 30 clsr)rcr .s, s*tjd|jdtdt ||j  d  } rat j tj|d|j}t|tj|d|j|S) Nz`@deprecated_class` on `` has no `deprecated_in` set. Deprecation notices and generated documentation will omit the `deprecated_in` version. Pass `deprecated_in` for a meaningful deprecation notice.rPF) r&r'rrr r!r"r#rrrr$r%r0)r0r/) warningswarnrV UserWarningrtypesSimpleNamespacer6rArErr7r0)rproxyshimr%rrrr$r rr!rr"rs r= decoratorz#deprecated_class..decoratorys  mL MM*3<<.9MM  !'%%!+$;  ((1H1HPY1ZkpkukuvD .t 4   ui > r?)r) rrrr r!r"rrrr$r%rs ``````````` r=deprecated_classrs'vt 2B r?)r'rrr r!r"r#rr&r'r#c |xst|j} |$|s"|s tjd| dtdt || ||||||| S)u Wrap any Python object with deprecation warnings. Returns a :class:`~deprecate.proxy._DeprecatedProxy` that transparently forwards all read access to *obj* while emitting a :class:`FutureWarning`. In *read-only* mode any write attempt through the proxy raises :class:`AttributeError`. Args: obj: The object to deprecate (dict, list, custom object, …). name: Display name for *obj* used in the warning message. When omitted, the type name of *obj* is used (e.g. ``"dict"``). deprecated_in: Version string when *obj* was deprecated. remove_in: Version string when *obj* will be removed. num_warns: Maximum number of warnings to emit. ``1`` (default) warns once; ``-1`` warns on every access. stream: Callable used to emit warnings. Defaults to :data:`~deprecate.deprecation.deprecation_warning` (:class:`FutureWarning`). Pass ``None`` to suppress warnings. template_mgs: Optional custom warning message template that overrides the built-in templates. When ``None`` (default), the built-in template for the active scenario is used. See :func:`~deprecate.proxy.deprecated_class` for the available ``%``-style placeholders. read_only: If ``True``, raise :class:`AttributeError` on any write attempt through the proxy. Only the following standard collection mutator names are intercepted: ``append``, ``clear``, ``discard``, ``extend``, ``insert``, ``pop``, ``remove``, ``setdefault``, ``update``, ``add``. Custom method names (e.g. ``register()``, ``reload()``, ``set_value()``) are not blocked. args_extra: Optional dict of extra keyword arguments merged into the forwarded call when the proxy is invoked. Caller-supplied values override entries with the same key. Returns: A :class:`~deprecate.proxy._DeprecatedProxy` wrapping *obj*. Example: >>> cfg = {"threshold": 0.5, "enabled": True} >>> proxy = deprecated_instance( ... cfg, ... name="config_dict", ... deprecated_in="1.0", ... remove_in="2.0", ... stream=None, ... ) >>> proxy["threshold"] 0.5 >>> proxy.get("enabled") True z`deprecated_instance()` on `rrrP) r&r'rrr r!r"r#r)rrVrrrr) r&r'rrr r!r"r#r resolved_names r=deprecated_instancerstn.DI..M -  *=/:I I      #!  r?r)#r0rrcollections.abcrtypingrrrrrdeprecate._typesr r r deprecate.deprecationr r rrrrdeprecate.docstring.injectrrrr__annotations__rrTrpr2rrrr~r?r=rs4 $99HHe &'s&jj\|,?"&7;+/"DJ$)| || |  | Xi( ) |3-|4Xc] 234|c3h(||@A|"|tf(()|D,?"&+/J J J J  J  J Xi( )J3-JJc3h(JJr?