
    ^j                         U d Z ddlZddlZddlmZ ddlmZmZmZm	Z	m
Z
 ddlmZmZmZ ddlmZmZmZmZmZmZ ddlmZmZ dZeed	<    G d
 d      Z	 d%dddeddddddd
dedededede	ed      de	e   de	eee	e   f      de	eeef      deded   dedee gdf   fdZ!ddddedddd d!ed"edededede	ed      de	e   d#ede	eeef      ddfd$Z"y)&aY  Proxy 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)AnyCallableLiteralOptionalcast)DeprecationConfig
TargetMode_ProxyConfig)TEMPLATE_ARGUMENT_MAPPINGTEMPLATE_WARNING_ARGUMENTSTEMPLATE_WARNING_CALLABLETEMPLATE_WARNING_NO_TARGET_validate_template_mgsdeprecation_warning)"_update_docstring_with_deprecationnormalize_docstring_style   _DEFAULT_STACKLEVEL_TO_CALLERc                      e Zd ZdZddddddedddddded	ed
edeeeee   f      deeeef      dedede	dee
d      dee   dedededdfdZedefd       Zedefd       Zdddee   ddfdZdeddfdZedefd       Zdefd Zd!eeef   deeef   fd"Zd!eeef   deeef   fd#Zed	edefd$       Zd	edefd%Zd	ed&eddfd'Zd	eddfd(Zd)edefd*Zd)ed&eddfd+Zd)eddfd,Zde	fd-Z de!e   fd.Z"d/edefd0Z#d1ed!edefd2Z$d3e%defd4Z&d3e%defd5Z'de	fd6Z(defd7Z)defd8Z*defd9Z+d:e%defd;Z,d<e-defd=Z.y)>_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.

    N    Fauto)targetargs_mapping
args_extradeprecated_in	remove_in	num_warnsstreamtemplate_mgs	read_onlydocstring_style_misconfigured_overrideobjnamer   r   r   r   r   r    r!   .Nr"   r#   r$   r%   returnc                   t        |
       |du xs |}t        |t              rt        j                  ||d      }||rt        j
                  }t        |t              r|t        j                  ||||d      z  }t        ||	||||
      }t        j                  | d|       t        |||||||t        |      |
		      }t        j                  | d
|       t        |dd      }|rt        j                  | d|       yy)a  Initialise 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   )r   r   r+   )r&   r!   r    r#   r   r"   _DeprecatedProxy__config)	r   r   r'   r   r   r   misconfiguredr$   r"   __deprecated____doc__)r   
isinstanceboolr
   _from_legacy_proxy
ARGS_REMAP	_validater   object__setattr__r	   r   getattr)selfr&   r'   r   r   r   r   r   r    r!   r"   r#   r$   r%   r.   cfgdep_meta_docs                     Z/var/www/ramen.bs-engineer-server.com/venv/lib/python3.12/site-packages/deprecate/proxy.py__init__z_DeprecatedProxy.__init__V   s   H 	|, %B+Bfd#226abcF>l**F fj)Z11<J[\ M
 !%
 	4!;SA$'%!'5oF%

 	4!18< sIt,tY5     c                 J    t        t        t        j                  | d            S )u   Private mutable runtime state (warn counter, stream, read-only flag, wrapped object).

        Private to this class — not part of the public API and not consumed by audit tools.

        r-   )r   r   r6   __getattribute__r9   s    r=   _cfgz_DeprecatedProxy._cfg   s     L&"9"9$@Z"[\\r?   c                 J    t        t        t        j                  | d            S )u  Static deprecation metadata (versions, name, target, args_mapping).

        Stored as ``__deprecated__`` (dunder, not name-mangled) — audit tools and external code may read it directly;
        this property simply provides a typed view of the same object.

        r/   )r   r	   r6   rA   rB   s    r=   _depz_DeprecatedProxy._dep   s      %v'>'>tEU'VWWr?   arg_namerG   c                   | j                   }|j                  }|sy|;|j                  j                  |d      }|j                  dk\  r9||j                  k\  r*y|j                  dk\  r|j
                  |j                  k\  ry| j                  }|j                  }|j                  }|j                  }|S|rQ||v rM||   }	t        |t        |	      dz  }
|xs t        }||j                  |j                  |j                  |
dz  }nt!        |      rQ|j"                  }|j$                   d| }|xs t&        }||j                  |j                  |j                  ||dz  }n1|xs t(        }||j                  |j                  |j                  dz  }	  ||t*               |-|j                  j                  |d      d	z   |j                  |<   y|xj
                  d	z  c_        y# t,        $ r  ||       Y Xw xY w)
uV  Emit 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_argnew_arg)source_namer   r   argument_map.)rK   r   r   target_nametarget_path)rK   r   r   r+   r   )rC   r!   warned_argsgetr    warnedrE   r   r   r"   r   strr   r'   r   r   callable__name__
__module__r   r   r   	TypeError)r9   rG   r:   r!   	arg_countdepr   r   custom_templaterJ   rL   templatemsgrN   rO   s                  r=   _warnz_DeprecatedProxy._warn   s    ii++Ha8I}}!i3==&@ }}!cjjCMM&Aiijj''
 ** LX5M"8,G48X[\cXd7eeL&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	s   G( (G<;G<	operationc                     | j                   j                  r(| j                  j                  }t	        d| d| d      y)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)rC   r#   rE   r'   AttributeError)r9   r_   r'   s      r=   _check_read_onlyz!_DeprecatedProxy._check_read_only  sD     99		D D68Crs  r?   c                 .    | j                   j                  S )zHThe deprecated source object this proxy wraps (audit contract accessor).)rC   r&   rB   s    r=   wrappedz_DeprecatedProxy.wrapped  s     yy}}r?   c                     | j                   j                  }|t        |t              s|S | j                  j
                  S )z@Return the active object: *target* when set, otherwise *source*.)rE   r   r1   r
   rC   r&   )r9   r   s     r=   _get_activez_DeprecatedProxy._get_active  s3    !!j&DMyy}}r?   kwargsc                    | j                   j                  }|r|s|S |j                         D ch c]
  \  }}|	| }}}|j                         D ci c]   \  }}||vs|j                  |      xs ||" c}}S c c}}w c c}}w )zHApply args_mapping to *kwargs*, renaming or dropping keys as configured.)rE   r   itemsrR   )r9   rh   r   kvargs_to_drops         r=   _apply_args_mappingz$_DeprecatedProxy._apply_args_mapping%  s    yy--6M&2&8&8&:HdaaiHH:@,,.b$!QAUaLa!!!$)A-bb Ibs   
A>A>B"Bc                 r    | j                   j                  }|s|S t        |      }|j                  |       |S )zFMerge :attr:`_ProxyConfig.args_extra` into *kwargs*; extra values win.)rC   r   dictupdate)r9   rh   r   mergeds       r=   _merge_args_extraz"_DeprecatedProxy._merge_args_extra-  s3    YY))
Mfj!r?   c                     h d}| |v S )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).

        >
   addpopclearappendextendinsertremoverq   discard
setdefault )r'   mutating_namess     r=   _is_potential_mutatorz&_DeprecatedProxy._is_potential_mutator6  s    
 ~%%r?   c                       j                          t         j                               } j                  j                  r3t        |      r( j                        rdt        dt        ddf fd}|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.

        argsrh   r)   Nc                  0    j                  d d       y )NzCalling mutating method 'ra   )rc   )r   rh   r'   r9   s     r=   _guarded_mutatorz6_DeprecatedProxy.__getattr__.<locals>._guarded_mutator\  s    %%(A$q&IJr?   )r^   r8   rg   rC   r#   rU   r   r   )r9   r'   attrr   s   ``  r=   __getattr__z_DeprecatedProxy.__getattr__P  so     	

t'')40998D>d6P6PQU6VK Ks Kt K $#r?   valuec                 d    | j                  d| d       t        | j                         ||       y)zForward attribute mutation to the active object, raising in read-only mode.

        Raises:
            AttributeError: If the proxy is in read-only mode.

        zSetting attribute 'ra   N)rc   setattrrg   )r9   r'   r   s      r=   r7   z_DeprecatedProxy.__setattr__b  s1     	 3D6;<  "D%0r?   c                 b    | j                  d| d       t        | j                         |       y)zForward attribute deletion to the active object, raising in read-only mode.

        Raises:
            AttributeError: If the proxy is in read-only mode.

        zDeleting attribute 'ra   N)rc   delattrrg   )r9   r'   s     r=   __delattr__z_DeprecatedProxy.__delattr__l  s/     	 4TF!<=  "D)r?   keyc                 H    | j                          | j                         |   S )zNForward subscript lookup to the active object, emitting a deprecation warning.)r^   rg   r9   r   s     r=   __getitem__z_DeprecatedProxy.__getitem__z  s    

!#&&r?   c                 T    | j                  d| 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.

        zSetting item 'ra   Nrc   rg   )r9   r   r   s      r=   __setitem__z_DeprecatedProxy.__setitem__  s.     	se156"'3r?   c                 P    | j                  d| 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.

        zDeleting item 'ra   Nr   r   s     r=   __delitem__z_DeprecatedProxy.__delitem__  s,     	uA67s#r?   c                 4    t        | j                               S )z>Return length of the active object without emitting a warning.)lenrg   rB   s    r=   __len__z_DeprecatedProxy.__len__  s    4##%&&r?   c                 T    | j                          t        | j                               S )z?Iterate over the active object, emitting a deprecation warning.)r^   iterrg   rB   s    r=   __iter__z_DeprecatedProxy.__iter__  s    

D$$&''r?   itemc                 &    || j                         v S )zACheck membership in the active object without emitting a warning.)rg   )r9   r   s     r=   __contains__z_DeprecatedProxy.__contains__  s    t'')))r?   r   c                    t         j                  | d      }t         j                  | d      }|j                  t        j                  u rb|j
                  xs i }|D ]  }|v s| j                  |        | j                        }| j                  |      } |j                  |i |S t        |j                        r|j
                  r|j
                  xs i }|D ]  }|v s| j                  |        t        fd|D              s| j                          | j                        }| j                  |      } |j                  |i |S | j                          t        |j                        r! |j                  |i | j                        S |j                  t        j                  u r | j                         |i S  | j                         |i | j                        S )aQ  Call 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-   rF   c              3   &   K   | ]  }|v  
 y wNr~   ).0old_keyrh   s     r=   	<genexpr>z,_DeprecatedProxy.__call__.<locals>.<genexpr>  s     @Ww&(@s   )r6   rA   r   r
   r4   r   r^   rn   rs   r&   rU   anyNOTIFYrg   )r9   r   rh   rZ   r:   mappingr   mapped_kwargss     `     r=   __call__z_DeprecatedProxy.__call__  s    %%d,<=%%d,FG::...&&,"G" 1f$JJJ01 !44V<M 22=AM377D2M22CJJC$4$4&&,"G" 1f$JJJ01 @@@

 44V<M 22=AM3::t5}55 	

CJJ3::tFt'='=f'EFF::***%4##%t6v66 "t!4J4+A+A&+IJJr?   otherc                     | j                   j                  }t        |t              r|j                   j                  }t	        ||k(        S )z'Compare the source object for equality.)rC   r&   r1   r   r2   )r9   r   r&   s      r=   __eq__z_DeprecatedProxy.__eq__  s6    iimme-.JJNNEC5L!!r?   c                 &    | j                  |       S )zReturn the inverse of equality.)r   )r9   r   s     r=   __ne__z_DeprecatedProxy.__ne__  s    ;;u%%%r?   c                 @    t        | j                  j                        S )z%Return the hash of the source object.)hashrC   r&   rB   s    r=   __hash__z_DeprecatedProxy.__hash__      DIIMM""r?   c                 @    t        | j                  j                        S )z!Return repr of the source object.)reprrC   r&   rB   s    r=   __repr__z_DeprecatedProxy.__repr__  r   r?   c                 @    t        | j                  j                        S )z Return str of the source object.)rT   rC   r&   rB   s    r=   __str__z_DeprecatedProxy.__str__  s    499==!!r?   c                 4    t        | j                               S )z<Return bool of the active object without emitting a warning.)r2   rg   rB   s    r=   __bool__z_DeprecatedProxy.__bool__  s    D$$&''r?   instancec                 \    | j                         }t        |t              rt        ||      S y)uQ  Support ``isinstance(x, proxy)`` by delegating to the active class.

        Allows a proxy used as a deprecated class alias to work transparently with ``isinstance`` without emitting a
        warning — type checks are structural, not a use of the deprecated API.

        Returns False when the active object is not a type.

        F)rg   r1   type)r9   r   actives      r=   __instancecheck__z"_DeprecatedProxy.__instancecheck__  s,     !!#fd#h//r?   subclassc                 \    | j                         }t        |t              rt        ||      S y)u   Support ``issubclass(X, proxy)`` by delegating to the active class.

        Same rationale as :meth:`~deprecate.proxy._DeprecatedProxy.__instancecheck__` — no warning emitted.

        Returns False when the active object is not a type.

        F)rg   r1   r   
issubclass)r9   r   r   s      r=   __subclasscheck__z"_DeprecatedProxy.__subclasscheck__  s.     !!#fd# h//r?   )/rV   rW   __qualname__r0   r   r   rT   r   rp   intr   r2   r>   propertyr   rC   r	   rE   r^   rc   re   rg   rn   rs   staticmethodr   r   r7   r   r   r   r   r   r   r   r   r   r6   r   r   r   r   r   r   r   r   r   r~   r?   r=   r   r   1   sD   "R ;?/30C&*%(-Q6Q6 Q6
 Q6 tC#$678Q6 T#s(^,Q6 Q6 Q6 Q6 ),-Q6 smQ6 Q6 Q6 "&Q6  
!Q6p ]l ] ] X' X X 26 I# I$ IV# $    S c$sCx. cT#s(^ cS#X 4S>  &C &D & &2  $1 1C 1D 1* * *'s 's '
(s (3 (4 ($s $t $' '((3- (
* * *.Kc .KS .KS .Kh"F "t "&F &t &## ### #" "($ (& T $ 4 r?   r   r   r   Fr   )
r   r   r    r!   r"   r   r   update_docstringr$   r%   r   r   r   r    r!   r(   r"   r   r   r   r$   )r   rstmkdocsmarkdownr%   r)   c       
         L    	
 dt         ddf
	 fd}|S )u  Decorator 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)   r   c                 r   
.s,s*t        j                  d| j                   dt        d       t	        | | j                  	
d      }rat        j                  t        j                  |d      |j                        }t        |       t        j                  |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.   rP   F)r&   r'   r   r   r    r!   r"   r#   r   r   r   r$   r%   r0   )r0   r/   )warningswarnrV   UserWarningr   typesSimpleNamespacer6   rA   rE   r   r7   r0   )r   proxyshimr%   r   r   r   r$   r    r   r!   r   r"   r   s      r=   	decoratorz#deprecated_class.<locals>.decoratory  s    mLMM*3<<. 9M M  !'%%!+$;
  ((1H1HPY1ZkpkukuvD.t4ui>r?   )r   )r   r   r   r    r!   r"   r   r   r   r$   r%   r   s   ``````````` r=   deprecated_classr     s'    vt  2  B r?   )r'   r   r   r    r!   r"   r#   r   r&   r'   r#   c                    |xs t        |       j                  }	|$|s"|s t        j                  d|	 dt        d       t        | |	|||||||	      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 `r   r   rP   )	r&   r'   r   r   r    r!   r"   r#   r   )r   rV   r   r   r   r   )
r&   r'   r   r   r    r!   r"   r#   r   resolved_names
             r=   deprecated_instancer     st    n .DI..M-*=/ :I I 	
 #!
 
r?   r   )#r0   r   r   collections.abcr   typingr   r   r   r   r   deprecate._typesr	   r
   r   deprecate.deprecationr   r   r   r   r   r   deprecate.docstring.injectr   r   r   r   __annotations__r   rT   rp   r2   r   r   r   r~   r?   r=   <module>r      s  4   $ 9 9 H H  e
 &' s &j j\ | ,?"&7;+/"DJ$)|| | 	|
 | Xi()| 3-| 4Xc] 234| c3h(| | @A| "| tf(()|D ,?"&+/J	J J 	J
 J J Xi()J 3-J J c3h(J Jr?   