§
    >²¸jÎ]  ã                   ó¢  — U d Z ddlZddlZddlZddlZddlmZmZmZ ddl	m
Z
mZmZ g d¢Zg d¢ZdZdZd	Zd
ZdZdddddœZ ee¦  «        Zee         ed<   h d£Zh d£Zdedefd„Zdee         defd„Zded         fd„Z deded         fd„Z!dee         dededefd„Z"dee         de#eef         fd „Z$dee         d!ed"ede#eef         fd#„Z%dee         d!ed"ed$ed%edefd&„Z&dee         d'ed(edefd)„Z'dee         d%ed*ede#ee         ef         fd+„Z(dee         d%ed*ede#ee         ef         fd,„Z)d-e
dee         fd.„Z*d/e+ddfd0„Z,dS )1aÌ  Helpers for annotating function docstrings with deprecation information.

This module owns all logic that reads or modifies a callable's ``__doc__``
attribute during deprecation decoration.  It supports both Google-style
(``Args:`` / ``Arguments:``), NumPy-style (``Parameters`` + underline),
and Sphinx-style (``:param ...:``) docstrings, plus MkDocs/Markdown output.

Key Components:
    - String constants (``TEMPLATE_DOC_*``) for reusable message fragments.
    - Style normalizer: :func:`normalize_docstring_style`, :func:`_auto_detect_style`
    - Section-aware insertion helpers: :func:`find_docstring_insertion_index`,
      :func:`is_numpy_underline`
    - Per-argument note builder: :func:`_build_arg_deprecation_note`
    - Google-style section helpers: :func:`_find_google_args_section`,
      :func:`_get_google_arg_indents`, :func:`_find_google_arg_line`
    - Shared continuation-line helper: :func:`_find_entry_end`
    - Annotators: :func:`_annotate_google_style_arg`,
      :func:`_annotate_sphinx_style_arg`
    - Notice builder: :func:`_build_general_notice_lines`
    - Orchestrator: :func:`_update_docstring_with_deprecation`

Copyright (C) 2020-2026 Jiri Borovec <6035284+Borda@users.noreply.github.com>

é    N)ÚLiteralÚOptionalÚcast)ÚDeprecationConfigÚ
TargetModeÚ_has_deprecation_meta)z!.. deprecated:: %(deprecated_in)sz   %(remove_text)sz   %(target_text)s)z-!!! warning "Deprecated in %(deprecated_in)s"z    %(remove_text)sz    %(target_text)su3   Deprecated since v%(deprecated_in)s â€” %(reason)s.u   Deprecated â€” %(reason)s.z# Will be removed in v%(remove_in)s.zno longer usedzuse `%(new_arg)s` insteadÚautoÚrstÚmkdocs)r	   r
   r   ÚmarkdownÚSUPPORTED_DOCSTRING_STYLES>
   úargs:únotes:úwarns:úraises:úyields:úreturns:ú	examples:ú
arguments:úattributes:úparameters:>
   úother parametersÚnotesÚwarnsÚraisesÚyieldsÚmethodsÚreturnsÚexamplesÚ
attributesÚ
parametersÚlineÚreturnc                 ó‚   — |                       ¦   «         }t          |¦  «        dk    ot          d„ |D ¦   «         ¦  «        S )zAReturn ``True`` when the line is a NumPy-style section underline.é   c              3   ó"   K  — | ]
}|d k    V — ŒdS )ú-N© )Ú.0Úchars     új/root/private/project/pallet_detection_v2/.venv/lib/python3.11/site-packages/deprecate/docstring/inject.pyú	<genexpr>z%is_numpy_underline.<locals>.<genexpr>X   s&   è è € Ð%GÐ%G°d d¨c¢kÐ%GÐ%GÐ%GÐ%GÐ%GÐ%Gó    )ÚstripÚlenÚall)r"   Ústrippeds     r+   Úis_numpy_underliner2   U   s<   € à�zŠz‰|Œ|€HÝˆx‰=Œ=˜AÒÐG¥#Ð%GÐ%G¸hÐ%GÑ%GÔ%GÑ"GÔ"GÐGr-   Úlinesc                 ój  — t          | ¦  «        D ]•\  }}|                     ¦   «                              ¦   «         t          v r|c S |dz   t	          | ¦  «        k     rI|                     ¦   «                              ¦   «         t
          v rt          | |dz            ¦  «        r|c S Œ–t	          | ¦  «        S )z>Find insertion index before first Google/NumPy section header.é   )Ú	enumerater.   ÚlowerÚGOOGLE_DOCSTRING_SECTIONSr/   ÚNUMPY_DOCSTRING_SECTIONSr2   )r3   Úidxr"   s      r+   Úfind_docstring_insertion_indexr;   [   s¬   € å˜uÑ%Ô%ð ð ‰	ˆˆTØ�:Š:‰<Œ<×ÒÑÔÕ#<Ð<Ð<ØˆJˆJˆJà�!‰G•c˜%‘j”jÒ Ð Ø—
’
‘”×"Ò"Ñ$Ô$Õ(@Ð@Ð@Ý" 5¨¨q©¤>Ñ2Ô2ð Að ˆJˆJˆJøÝˆu‰:Œ:Ðr-   ©r
   r   c                  ó  — t           j                             dd¦  «                             ¦   «         } | dv rdS | dk    rdS dt          j        v rdS t          j        r(dt          j        d                              ¦   «         v rdS dS )uo  Detect documentation engine from environment or process name.

    Resolution order:

    1. ``DEPRECATE_DOCSTRING_STYLE`` env var â€” explicit override, takes highest priority.
    2. ``sys.modules`` â€” ``mkdocs`` imported â†’ MkDocs build in progress.
    3. ``sys.argv[0]`` full path â€” ``mkdocs`` anywhere in the path string.
    4. Default â†’ ``"rst"``.

    ÚDEPRECATE_DOCSTRING_STYLEÚ )r   r   r   r
   r   )ÚosÚenvironÚgetr7   ÚsysÚmodulesÚargv)Ú	env_styles    r+   Ú_auto_detect_stylerG   i   s‰   € õ ”
—’Ð:¸BÑ?Ô?×EÒEÑGÔG€IØÐ*Ð*Ð*ØˆxØ�EÒÐØˆuà•3”;ÐÐØˆxÝ
„xð �H¥¤¨¤× 1Ò 1Ñ 3Ô 3Ð3Ð3ØˆxØˆ5r-   Údocstring_stylec                 ó†  — t          | t          ¦  «        s(t          d| ›dt          t          ¦  «        ›d�¦  «        ‚t
                               |                      ¦   «         ¦  «        }|€(t          d| ›dt          t          ¦  «        ›d�¦  «        ‚|dk    rt          ¦   «         S t          t          d         |¦  «        S )z/Validate and normalize docstring style aliases.z Invalid `docstring_style` value z. Supported styles are: ú.Nr	   r<   )Ú
isinstanceÚstrÚ
ValueErrorÚsortedr   ÚDOCSTRING_STYLE_ALIASESrB   r7   rG   r   r   )rH   Únormalized_styles     r+   Únormalize_docstring_stylerQ   �   sõ   € å�o¥sÑ+Ô+ð 
ÝðbØðbð bÝ:@ÕA[Ñ:\Ô:\ðbð bð bñ
ô 
ð 	
õ /×2Ò2°?×3HÒ3HÑ3JÔ3JÑKÔKÐØÐÝðbØðbð bÝ:@ÕA[Ñ:\Ô:\ðbð bð bñ
ô 
ð 	
ð ˜6Ò!Ð!Ý!Ñ#Ô#Ð#Ý•˜Ô(Ð*:Ñ;Ô;Ð;r-   Únew_argÚdeprecated_inÚ	remove_inc                 ó‚   — | rt           d| iz  nt          }|rt          nt          }|||dœz  }|r|t          d|iz  z  }|S )uë  Build an inline deprecation note string for a single deprecated argument.

    Args:
        new_arg: Replacement argument name, or ``None`` when the argument is simply removed.
        deprecated_in: Version string when the argument was deprecated (e.g. ``"1.8"``).
        remove_in: Version string when the argument will be removed (e.g. ``"1.9"``).

    Returns:
        A one-line deprecation note suitable for embedding in a docstring.

    Example:
        >>> _build_arg_deprecation_note(None, "1.8", "1.9")
        'Deprecated since v1.8 â€” no longer used. Will be removed in v1.9.'
        >>> _build_arg_deprecation_note("new_arg", "1.8", "1.9")
        'Deprecated since v1.8 â€” use `new_arg` instead. Will be removed in v1.9.'

    rR   )rS   ÚreasonrT   )ÚTEMPLATE_DOC_ARG_REASON_RENAMEDÚTEMPLATE_DOC_ARG_REASON_REMOVEDÚ!TEMPLATE_DOC_ARG_DEPRECATED_SINCEÚTEMPLATE_DOC_ARG_DEPRECATEDÚTEMPLATE_DOC_ARG_REMOVE)rR   rS   rT   rV   ÚtemplateÚnotes         r+   Ú_build_arg_deprecation_noter^   “   sg   € ð$ HOÐsÕ,°	¸7Ð/CÑCÐCÕTs€FØ4AÐbÕ0Ð0ÕGb€HØ¨ÀÐHÐHÑH€DØð CØÕ'¨;¸	Ð*BÑBÑBˆØ€Kr-   c                 óì   — t          j        d¦  «        }t          | ¦  «        D ]O\  }}|                     |¦  «        r5|t	          |¦  «        t	          |                     ¦   «         ¦  «        z
  fc S ŒPdS )uL  Return ``(section_start, section_indent)`` for a Google-style ``Args:`` header.

    Scans *lines* for an ``Args:`` or ``Arguments:`` header and returns its line
    index and leading indentation.  Returns ``(-1, 0)`` when not found.

    The match is intentionally strict: a line qualifies only when it consists
    of optional leading spaces followed by exactly ``Args:`` or ``Arguments:``
    with nothing else on the line (no trailing text).  This avoids accidental
    matches inside prose paragraphs.

    See `Google Python Style Guide â€” Functions and Methods
    <https://google.github.io/styleguide/pyguide.html#383-functions-and-methods>`_
    for the ``Args:`` section specification.

    Args:
        lines: Docstring already split into individual lines.

    Returns:
        A 2-tuple ``(section_start, section_indent)``.

    z^\s*(Args|Arguments):\s*$)éÿÿÿÿr   )ÚreÚcompiler6   Úmatchr/   Úlstrip)r3   Ú_section_reÚir"   s       r+   Ú_find_google_args_sectionrg   ­   s{   € õ, ”*Ð9Ñ:Ô:€KÝ˜UÑ#Ô#ð 5ð 5‰ˆˆ4Ø×Ò˜TÑ"Ô"ð 	5Ø•c˜$‘i”i¥# d§k¢k¡m¤mÑ"4Ô"4Ñ4Ð4Ð4Ð4Ð4ð	5àˆ5r-   Úsection_startÚsection_indentc                 ó6  — d}t          |dz   t          | ¦  «        ¦  «        D ]c}| |                              ¦   «         rGt          | |         ¦  «        t          | |                              ¦   «         ¦  «        z
  }||k    r|} nŒd|dk    rdS |dz   }t          |dz   t          | ¦  «        ¦  «        D ]b}| |         }|                     ¦   «         sŒt          |¦  «        t          |                     ¦   «         ¦  «        z
  }||k    r n||k    r|} nŒc||fS )a›  Return ``(arg_indent, continuation_indent)`` for a Google-style Args section.

    *arg_indent* is the column at which individual argument entries begin.
    *continuation_indent* is the column used for continuation lines within an
    argument entry (defaults to ``arg_indent + 4`` when not detectable).
    Returns ``(-1, -1)`` when the section has no non-empty child lines.

    Args:
        lines: Docstring already split into individual lines.
        section_start: Line index of the ``Args:`` / ``Arguments:`` header.
        section_indent: Leading indentation of that header line.

    Returns:
        A 2-tuple ``(arg_indent, continuation_indent)``.

    r`   r5   )r`   r`   é   ©Úranger/   r.   rd   )r3   rh   ri   Ú
arg_indentrf   Úcurrent_indentÚcontinuation_indentr"   s           r+   Ú_get_google_arg_indentsrq   Ê   s<  € ð" €JÝ�= 1Ñ$¥c¨%¡j¤jÑ1Ô1ð ð ˆØ�Œ8�>Š>ÑÔð 	Ý   q¤™]œ]­S°°q´·²Ñ1BÔ1BÑ-CÔ-CÑCˆNØ Ò.Ð.Ø+�
ØˆEð		ð �RÒÐØˆvà$ q™.ÐÝ�= 1Ñ$¥c¨%¡j¤jÑ1Ô1ð 	ð 	ˆØ�QŒxˆØ�zŠz‰|Œ|ð 	ØÝ˜T™œ¥S¨¯ª©¬Ñ%7Ô%7Ñ7ˆØ˜^Ò+Ð+ØˆEØ˜JÒ&Ð&Ø"0ÐØˆEð 'ð Ð*Ð*Ð*r-   rn   Úarg_namec                 óÈ  — t          |dz   t          | ¦  «        ¦  «        D ]À}| |         }|                     ¦   «         sŒt          |¦  «        t          |                     ¦   «         ¦  «        z
  }||k    r ni||k    rb||d…         }t          |¦  «        t          |¦  «        k    o|t          |¦  «                 dv }	||k    s|                     |¦  «        r|	r|c S ŒÁdS )a'  Return the line index of *arg_name* inside a Google-style Args section.

    Returns ``-1`` when *arg_name* is not found within the section.

    Args:
        lines: Docstring already split into individual lines.
        section_start: Line index of the ``Args:`` / ``Arguments:`` header.
        section_indent: Leading indentation of that header line.
        arg_indent: Leading indentation of argument entry lines.
        arg_name: Name of the argument to locate.

    Returns:
        Line index of the matching argument entry, or ``-1``.

    r5   Nz :(,r`   )rm   r/   r.   rd   Ú
startswith)
r3   rh   ri   rn   rr   rf   r"   ro   ÚrestÚhas_arg_boundarys
             r+   Ú_find_google_arg_linerw   õ   së   € õ$ �= 1Ñ$¥c¨%¡j¤jÑ1Ô1ð ð ˆØ�QŒxˆØ�zŠz‰|Œ|ð 	ØÝ˜T™œ¥S¨¯ª©¬Ñ%7Ô%7Ñ7ˆØ˜^Ò+Ð+ØˆEØ˜ZÒ'Ð'Ø˜
˜˜Ô$ˆDÝ" 4™yœy­3¨x©=¬=Ò8ÐZ¸TÅ#ÀhÁ-Ä-Ô=PÐTZÐ=ZÐØ�xÒÐ D§O¢O°HÑ$=Ô$=ÐÐBRÐØ���øØˆ2r-   Ú	entry_idxÚentry_indentc                 óþ   — |}t          |dz   t          | ¦  «        ¦  «        D ]Y}| |         }|                     ¦   «         s n:t          |¦  «        t          |                     ¦   «         ¦  «        z
  |k    r n|}ŒZ|S )aö  Return the index of the last continuation line for a docstring entry.

    Scans forward from *entry_idx + 1* and stops at the first blank line or
    the first line whose indentation is ``<= entry_indent``.

    Note:
        A blank line within a multi-paragraph argument description is treated
        as the entry boundary.  Only the content up to that blank line receives
        the deprecation note; subsequent paragraphs are considered outside the
        entry.

    Args:
        lines: Docstring already split into individual lines.
        entry_idx: Line index of the entry's opening line.
        entry_indent: Leading indentation of that opening line.

    Returns:
        Index of the last line belonging to the entry (>= *entry_idx*).

    r5   rl   )r3   rx   ry   Úend_idxrf   r"   s         r+   Ú_find_entry_endr|     s�   € ð* €GÝ�9˜q‘=¥# e¡*¤*Ñ-Ô-ð ð ˆØ�QŒxˆØ�zŠz‰|Œ|ð 	ØˆEÝˆt‰9Œ9•s˜4Ÿ;š;™=œ=Ñ)Ô)Ñ)¨\Ò9Ð9ØˆEØˆˆØ€Nr-   r]   c                 ó~  ‡— t          | ¦  «        \  }}|dk    r| dfS t          | ||¦  «        \  }}|dk    r| dfS t          | ||||¦  «        }|dk    r| dfS t          | ||¦  «        }t	          ˆfd„| ||dz   …         D ¦   «         ¦  «        r| dfS d|z  ‰z   }	| d|dz   …         |	gz   | |dz   d…         z   }
|
dfS )ut  Find *arg_name* in a Google-style ``Args:`` section and insert *note* below it.

    Supports both ``Args:`` and ``Arguments:`` section headers.  Returns the
    original list unchanged when no matching section or argument entry is found.

    Args:
        lines: Docstring already split into individual lines.
        arg_name: Name of the deprecated argument to locate.
        note: Text to insert as a continuation line under the matched entry.

    Returns:
        A 2-tuple ``(new_lines, found)`` where *found* is ``True`` when the
        argument was located and the note was successfully inserted.

    The note is inserted as a continuation line directly after the matched entry:

    .. code-block:: text

    Args:
            lr (float): Learning rate.
            old_cfg (object): Old config.
                Deprecated â€” use cfg instead.  # <-- inserted here

    r`   Fc              3   ó    •K  — | ]}‰|v V — Œ	d S ©Nr(   ©r)   Úlnr]   s     €r+   r,   z-_annotate_google_style_arg.<locals>.<genexpr>]  s'   øè è € Ð
BÐ
B˜"ˆ4�2ˆ:Ð
BÐ
BÐ
BÐ
BÐ
BÐ
Br-   r5   Tú N)rg   rq   rw   r|   Úany)r3   rr   r]   rh   ri   rn   rp   Úarg_line_idxr{   Ú	note_lineÚ	new_liness     `        r+   Ú_annotate_google_style_argr‡   6  s  ø€ õ2 %>¸eÑ$DÔ$DÑ!€M�>Ø˜ÒÐØ�eˆ|Ðå&=¸eÀ]ÐTbÑ&cÔ&cÑ#€JÐ#Ø�RÒÐØ�eˆ|Ðå(¨°¸~ÈzÐ[cÑdÔd€LØ�rÒÐØ�eˆ|Ðå˜e \°:Ñ>Ô>€Gå
Ð
BÐ
BÐ
BÐ
B  l°W¸q±[Ð&@Ô AÐ
BÑ
BÔ
BÑBÔBð Ø�dˆ{ÐØÐ)Ñ)¨DÑ0€IØ�m˜ !™�mÔ$¨	 {Ñ2°U¸7ÀQ¹;¸=¸=Ô5IÑI€IØ�dˆ?Ðr-   c                 óî  ‡— t          j        dt          j        |¦  «        z   dz   ¦  «        }d}d}t          | ¦  «        D ]B\  }}|                     |¦  «        }|r&|}t          |                     d¦  «        ¦  «        } nŒC|dk    r| dfS t          | ||¦  «        }	t          ˆfd„| ||	dz   …         D ¦   «         ¦  «        r| dfS d	|d
z   z  ‰z   }
| d|	dz   …         |
gz   | |	dz   d…         z   }|dfS )ue  Find ``:param arg_name:`` in a Sphinx-style docstring and insert *note* below it.

    Supports both ``:param arg_name:`` and ``:param SomeType arg_name:`` forms.
    Returns the original list unchanged when no matching ``:param`` field is found.

    Args:
        lines: Docstring already split into individual lines.
        arg_name: Name of the deprecated argument to locate.
        note: Text to insert as a continuation line under the matched field.

    Returns:
        A 2-tuple ``(new_lines, found)`` where *found* is ``True`` when the
        parameter was located and the note was successfully inserted.

    The note is inserted as a continuation line directly after the matched field::

        :param lr: Learning rate.
        :param old_cfg: Old config.
            Deprecated â€” use cfg instead.  # <-- inserted here
        :returns: Result.

    z^(\s*):param\s+(?:\S+\s+)?z\s*:r`   r   r5   Fc              3   ó    •K  — | ]}‰|v V — Œ	d S r   r(   r€   s     €r+   r,   z-_annotate_sphinx_style_arg.<locals>.<genexpr>‹  s'   øè è € Ð
DÐ
D˜"ˆ4�2ˆ:Ð
DÐ
DÐ
DÐ
DÐ
DÐ
Dr-   Tr‚   rk   N)	ra   rb   Úescaper6   rc   r/   Úgroupr|   rƒ   )r3   rr   r]   ÚpatternÚparam_line_idxÚparam_indentrf   r"   Úmr{   r…   r†   s     `         r+   Ú_annotate_sphinx_style_argr�   d  s9  ø€ õ. ŒjÐ6½¼À8Ñ9LÔ9LÑLÈwÑVÑWÔW€Gà€NØ€LÝ˜UÑ#Ô#ð ð ‰ˆˆ4Ø�MŠM˜$ÑÔˆØð 	ØˆNÝ˜qŸwšw q™zœz™?œ?ˆLØˆEð	ð
 ˜ÒÐØ�eˆ|Ðå˜e ^°\ÑBÔB€Gå
Ð
DÐ
DÐ
DÐ
D  n°wÀ±{Ð&BÔ CÐ
DÑ
DÔ
DÑDÔDð Ø�dˆ{ÐØ�| aÑ'Ñ(¨4Ñ/€IØ�m˜ !™�mÔ$¨	 {Ñ2°U¸7ÀQ¹;¸=¸=Ô5IÑI€IØ�dˆ?Ðr-   Údep_infoc                 ó>  — | j         rd| j         › d�nd}d}d}t          | j        ¦  «        rG| j        j        › d| j        j        › �}t          j        | j        ¦  «        rdnd}d|› d|› d�}d	|› d�}t          | j        ¦  «        }|d
k    r
t          }|}n	t          }|}g }	|D ]w}
|
                     ¦   «                              d¦  «        r|sŒ,|
                     ¦   «                              d¦  «        r|sŒV|	                     |
| j        ||dœz  ¦  «         Œx|	S )a  Render the general deprecation notice lines for the given style.

    Selects the RST (``.. deprecated::``) or MkDocs (``!!! warning``) template
    based on ``dep_info.docstring_style``, substitutes ``deprecated_in``,
    ``remove_in``, and the target reference, and omits template lines whose
    placeholder resolves to an empty string.

    Args:
        dep_info: Frozen deprecation metadata attached to the decorated callable.

    Returns:
        A list of rendered notice lines (without leading body indentation).

    zWill be removed in rJ   r?   ÚclassÚfunczUse :z:`z
` instead.zUse `r   z%(remove_text)sz%(target_text)s)rS   Úremove_textÚtarget_text)rT   ÚcallableÚtargetÚ
__module__Ú__name__ÚinspectÚisclassrQ   rH   ÚTEMPLATE_DOC_DEPRECATED_MKDOCSÚTEMPLATE_DOC_DEPRECATED_RSTr.   ÚendswithÚappendrS   )r‘   r•   Útarget_text_rstÚtarget_text_mkdocsÚfull_target_nameÚref_typerH   r\   r–   Úresultr"   s              r+   Ú_build_general_notice_linesr¦   ’  sx  € ð BJÔASÐ[Ð=¨Ô(:Ð=Ð=Ð=Ð=ÐY[€KØ€OØÐÝ�”Ñ Ô ð BØ&œoÔ8ÐUÐU¸8¼?Ô;SÐUÐUÐÝ%œo¨h¬oÑ>Ô>ÐJ�7�7ÀFˆØJ (ÐJÐJÐ.>ÐJÐJÐJˆØAÐ%5ÐAÐAÐAÐå/°Ô0HÑIÔI€OØ˜(Ò"Ð"Ý1ˆØ(ˆˆå.ˆØ%ˆà€FØð 
ð 
ˆØ�:Š:‰<Œ<× Ò Ð!2Ñ3Ô3ð 	¸Kð 	ØØ�:Š:‰<Œ<× Ò Ð!2Ñ3Ô3ð 	¸Kð 	ØØ�ŠØ XÔ%;ÈKÐhsÐtÐtÑtñ	
ô 	
ð 	
ð 	
ð €Mr-   Ú
wrapped_fnc                 ó¼  ‡— t          | d¦  «        r| j        sdS t          | ¦  «        sdS | j                             ¦   «         }| j        }|j        r­d}|j                             ¦   «         D ]N\  }}t          ||j        |j	        ¦  «        }t          |||¦  «        \  }}|st          |||¦  «        \  }}|sd}ŒO|rA|j        t          j        u r.t          j        d                     |¦  «        ¦  «        | _        dS t%          |¦  «        }dt&          t(                   dt&          t(                   dt*          fd	„}	 |	||¦  «        rdS t-          d
„ |dd…         D ¦   «         d¦  «        Š|j        r°|rJ|d                              ¦   «         s0|                     ¦   «          |r|d                              ¦   «         ¯0|                     d¦  «         |                     ˆfd„|D ¦   «         ¦  «         t          j        d                     |¦  «        ¦  «        | _        dS ˆfd„|D ¦   «         }t7          |¦  «        }
|d|
…         }||
d…         }|r/|d                              ¦   «         r|                     d¦  «         |                     |¦  «         |r’|rJ|d                              ¦   «         s0|                     ¦   «          |r|d                              ¦   «         ¯0|r/|d                              ¦   «         r|                     d¦  «         |                     |¦  «         t          j        d                     |¦  «        ¦  «        | _        dS )uÈ  Annotate a function's docstring with deprecation information.

    Two paths are taken depending on whether ``args_mapping`` is set:

    - **Inline arg path** (``args_mapping`` present): each deprecated argument is
      located in the ``Args:`` / ``Arguments:`` (Google style) or ``:param``
      (Sphinx style) section and a one-line deprecation note is inserted directly
      beneath it.  When ``target`` is ``True`` (self-deprecation) and all deprecated
      args are found, the function returns early and no general notice block is
      added.  When ``target`` is a callable or ``None``, the general block is
      always added after the inline annotations because the function itself is
      deprecated.
    - **General notice path** (no ``args_mapping``, or at least one arg was not
      found in the docstring): a deprecation notice is inserted before the first
      Google/NumPy section header (e.g. ``Args:``, ``Parameters``) when detected,
      otherwise appended at the end of the docstring.  The notice format depends
      on ``docstring_style``: Sphinx ``.. deprecated::`` directive (default
      ``"rst"``) or MkDocs/Markdown admonition (``"mkdocs"``/``"markdown"``).

    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 be a
        :class:`~deprecate._types.DeprecationConfig` instance with:
        - deprecated_in: Version when deprecated
        - remove_in: Version when will be removed
        - target: Replacement callable (optional)
        - args_mapping: Mapping of old â†’ new argument names (optional)

    Example:
        General notice path â€” no ``args_mapping``:

        >>> def new_func(): pass
        >>> def old_func():
        ...     '''Original docstring.'''
        ...     pass
        >>> old_func.__deprecated__ = DeprecationConfig(
        ...     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.
        <BLANKLINE>
        .. deprecated:: 1.0
           Will be removed in 2.0.
           Use :func:`...new_func` instead.

        Inline arg path â€” self-deprecation (``target=True``) with all args found:

        >>> def fn_with_args(x: int, old_arg: str = "") -> str:
        ...     '''Do something.
        ...
        ...     Args:
        ...         x: The main input.
        ...         old_arg: The old argument.
        ...     '''
        ...     return str(x)
        >>> fn_with_args.__deprecated__ = DeprecationConfig(
        ...     deprecated_in='1.0',
        ...     remove_in='2.0',
        ...     target=TargetMode.ARGS_REMAP,
        ...     args_mapping={'old_arg': None},
        ... )
        >>> _update_docstring_with_deprecation(fn_with_args)
        >>> 'Deprecated since v1.0' in fn_with_args.__doc__
        True
        >>> '.. deprecated::' in fn_with_args.__doc__
        False

    Note:
        Does nothing if the function has no docstring or no ``__deprecated__`` attribute.
        To preserve Google/NumPy parsing, the general notice is inserted before the
        first section header (e.g. ``Args:`` or ``Parameters``) when detected.

    Ú__doc__NTFú
Ú	doc_linesÚblock_linesr#   c           	      ór  ‡ ‡‡— ‰sdS t          ‰ ¦  «        t          ‰¦  «        z
  }|dk     rdS ‰d                              ¦   «         }t          |dz   ¦  «        D ][Š‰ ‰                              ¦   «         |k    rŒ!t          ˆˆ ˆfd„t          t          ‰¦  «        ¦  «        D ¦   «         ¦  «        r dS Œ\dS )z®Return True if ``block_lines`` appears as a contiguous block in ``doc_lines``.

        Lines are compared using ``.strip()`` to ignore leading/trailing whitespace.

        Fr   r5   c              3   óŠ   •K  — | ]=}‰‰|z                                  ¦   «         ‰|                               ¦   «         k    V — Œ>d S r   )r.   )r)   Úoffsetr¬   r«   Ústarts     €€€r+   r,   zU_update_docstring_with_deprecation.<locals>._has_deprecation_block.<locals>.<genexpr>8  s_   øè è € ð ð ØU[�	˜% &™.Ô)×/Ò/Ñ1Ô1°[ÀÔ5H×5NÒ5NÑ5PÔ5PÒPðð ð ð ð ð r-   T)r/   r.   rm   r0   )r«   r¬   Ú	max_startÚfirstr°   s   ``  @r+   Ú_has_deprecation_blockzB_update_docstring_with_deprecation.<locals>._has_deprecation_block)  sò   øøø€ ð ð 	Ø�5Ý˜	‘N”N¥S¨Ñ%5Ô%5Ñ5ˆ	Ø�qŠ=ˆ=Ø�5Ø˜A”×$Ò$Ñ&Ô&ˆÝ˜9 q™=Ñ)Ô)ð 	ð 	ˆEØ˜Ô×%Ò%Ñ'Ô'¨5Ò0Ð0ØÝð ð ð ð ð ð Ý_dÕehÐitÑeuÔeuÑ_vÔ_vðñ ô ñ ô ð ð �t�tðð ˆur-   c              3   ó°   K  — | ]Q}|                      ¦   «         ¯|d t          |¦  «        t          |                     ¦   «         ¦  «        z
  …         V — ŒRd S r   )r.   r/   rd   )r)   r"   s     r+   r,   z5_update_docstring_with_deprecation.<locals>.<genexpr>B  sU   è è € ÐVÐV°DÈÏÊÉÌÐVˆÐ.•�D‘	”	�C §¢¡¤Ñ.Ô.Ñ.Ð.Ô	/ÐVÐVÐVÐVÐVÐVr-   r5   r?   r`   c              3   ó"   •K  — | ]	}‰|z   V — Œ
d S r   r(   ©r)   r�   Úbody_indents     €r+   r,   z5_update_docstring_with_deprecation.<locals>.<genexpr>J  s(   øè è € ÐBÐB¨"�[ 2Ñ%ÐBÐBÐBÐBÐBÐBr-   c                 ó   •— g | ]}‰|z   ‘ŒS r(   r(   r¶   s     €r+   ú
<listcomp>z6_update_docstring_with_deprecation.<locals>.<listcomp>N  s   ø€ ÐJÐJÐJ°"˜[¨2Ñ-ÐJÐJÐJr-   r   )Úhasattrr©   r   Ú
splitlinesÚ__deprecated__Úargs_mappingÚitemsr^   rS   rT   r‡   r�   r˜   r   Ú
ARGS_REMAPr›   ÚcleandocÚjoinr¦   ÚlistrL   ÚboolÚnextr.   Úpopr    Úextendr;   )r§   r3   r‘   Úall_args_foundrr   rR   r]   ÚfoundÚdeprecation_linesr³   Ú
insert_idxÚprefixÚsuffixr·   s                @r+   Ú"_update_docstring_with_deprecationrÍ   ¾  s¥  ø€ õf �:˜yÑ)Ô)ð °Ô1Cð ØˆÝ  Ñ,Ô,ð ØˆØÔ×)Ò)Ñ+Ô+€EØÔ(€HàÔð ØˆØ!)Ô!6×!<Ò!<Ñ!>Ô!>ð 	'ð 	'ÑˆH�gÝ.¨w¸Ô8NÐPXÔPbÑcÔcˆDÝ5°e¸XÀtÑLÔL‰LˆE�5Øð QÝ9¸%ÀÈ4ÑPÔP‘��uØð 'Ø!&�øð ð 	˜hœoµÔ1FÐFÐFÝ!(Ô!1°$·)²)¸EÑ2BÔ2BÑ!CÔ!CˆJÔØˆFå3°HÑ=Ô=Ðð­$­s¬)ð Å$ÅsÄ)ð ÕPTð ð ð ð ð, Ð˜eÐ%6Ñ7Ô7ð ØˆÝØVÐV¸EÀ!À"À"¼IÐVÑVÔVØ
ñô €Kð Ôð Aàð 	˜E "œIŸOšOÑ-Ô-ð 	Ø�IŠI‰KŒKˆKð ð 	˜E "œIŸOšOÑ-Ô-ð 	à�Š�RÑÔÐØ�ŠÐBÐBÐBÐBÐ0AÐBÑBÔBÑBÔBÐBÝ$Ô-¨d¯iªi¸Ñ.>Ô.>Ñ?Ô?ˆ
ÔÐÐð KÐJÐJÐJÐ8IÐJÑJÔJÐÝ3°EÑ:Ô:ˆ
Ø�{˜
�{Ô#ˆØ�z�{�{Ô#ˆØð 	�f˜R”j×&Ò&Ñ(Ô(ð 	Ø�MŠM˜"ÑÔÐØ�ŠÐ'Ñ(Ô(Ð(Øð 	"Øð  ¨¤×!1Ò!1Ñ!3Ô!3ð Ø—
’
‘”�ð ð  ¨¤×!1Ò!1Ñ!3Ô!3ð àð "˜& œ)Ÿ/š/Ñ+Ô+ð "Ø—’˜bÑ!Ô!Ð!Ø�MŠM˜&Ñ!Ô!Ð!Ý$Ô-¨d¯iªi¸Ñ.?Ô.?Ñ@Ô@ˆ
ÔÐÐr-   )-r©   r›   r@   ra   rC   Útypingr   r   r   Údeprecate._typesr   r   r   rž   r�   rY   rZ   r[   rX   rW   rO   Ú	frozensetr   rL   Ú__annotations__r8   r9   rÃ   r2   rÂ   Úintr;   rG   rQ   r^   Útuplerg   rq   rw   r|   r‡   r�   r¦   ÚobjectrÍ   r(   r-   r+   ú<module>rÕ      s¾  ððð ð ð2 €€€Ø 	€	€	€	Ø 	€	€	€	Ø 
€
€
€
Ø *Ð *Ð *Ð *Ð *Ð *Ð *Ð *Ð *Ð *à QÐ QÐ QÐ QÐ QÐ QÐ QÐ QÐ QÐ Qðð ð Ð ð"ð "ð "Ð ð %]Ð !à=Ð à?Ð à"2Ð à"=Ð à#)°%À8ÐYaÐbÐbÐ Ø-6¨YÐ7NÑ-OÔ-OÐ ˜I cœNÐ OÐ OÑ Oðð ð Ð ðð ð Ð ðH˜Sð H Tð Hð Hð Hð Hð¨$¨s¬)ð ¸ð ð ð ð ð˜G OÔ4ð ð ð ð ð0<¨sð <°w¸Ô7Oð <ð <ð <ð <ð$¨°#¬ð Àsð ÐWZð Ð_bð ð ð ð ð4 T¨#¤Yð °5¸¸c¸´?ð ð ð ð ð:(+ 4¨¤9ð (+¸Sð (+ÐRUð (+ÐZ_Ð`cÐehÐ`hÔZið (+ð (+ð (+ð (+ðVØ�Œ9ðØ%(ðØ:=ðØKNðØZ]ðàðð ð ð ðB˜4 œ9ð °ð ÀCð ÈCð ð ð ð ð@+ d¨3¤ið +¸3ð +Àcð +ÈeÐTXÐY\ÔT]Ð_cÐTcÔNdð +ð +ð +ð +ð\+ d¨3¤ið +¸3ð +Àcð +ÈeÐTXÐY\ÔT]Ð_cÐTcÔNdð +ð +ð +ð +ð\)Ð*;ð )ÀÀSÄ	ð )ð )ð )ð )ðX]A°6ð ]A¸dð ]Að ]Að ]Að ]Að ]Að ]Ar-   