^j] .UdZddlZddlZddlZddlZddlmZmZmZddl m Z m Z m Z gdZ gdZdZdZd Zd Zd Zd d dddZeeZeeed<hdZhdZdedefdZdeedefdZdedfdZ dededfdZ!deedededefdZ"deede#eeffd Z$deed!ed"ede#eeffd#Z%deed!ed"ed$ed%edef d&Z&deed'ed(edefd)Z'deed%ed*ede#eeeffd+Z(deed%ed*ede#eeeffd,Z)d-e deefd.Z*d/e+ddfd0Z,y)1aHelpers 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)LiteralOptionalcast)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)su3Deprecated since v%(deprecated_in)s — %(reason)s.uDeprecated — %(reason)s.z# Will be removed in v%(remove_in)s.zno longer usedzuse `%(new_arg)s` insteadautorstmkdocs)r r r markdownSUPPORTED_DOCSTRING_STYLES> args:notes:warns:raises:yields:returns: examples: arguments: attributes: parameters:> other parametersnoteswarnsraisesyieldsmethodsreturnsexamples attributes parameterslinereturncf|j}t|dk\xrtd|DS)zAReturn ``True`` when the line is a NumPy-style section underline.c3&K|] }|dk( yw)-N).0chars e/var/www/ramen.bs-engineer-server.com/venv/lib/python3.12/site-packages/deprecate/docstring/inject.py z%is_numpy_underline..Xs%Gddck%Gs)striplenall)r"strippeds r+is_numpy_underliner1Us,zz|H x=A  G#%Gh%G"GGlinesc&t|D]y\}}|jjtvr|cS|dzt |ks@|jjt vset ||dzsw|cSt |S)z>Find insertion index before first Google/NumPy section header.) enumerater-lowerGOOGLE_DOCSTRING_SECTIONSr.NUMPY_DOCSTRING_SECTIONSr1)r3idxr"s r+find_docstring_insertion_indexr;[su% T ::<   #< <J !Gc%j  ""$(@@"5q>2J u:r2r r ctjjddj}|dvry|dk(rydtj vrytj r$dtj djvryy)uoDetect 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)osenvirongetr7sysmodulesargv) env_styles r+_auto_detect_stylerGism :B?EEGI**E3;; xxH 1 1 33 r2docstring_stylec,t|tstd|dttdt j |j}|td|dttd|dk(r tSttd|S)z/Validate and normalize docstring style aliases.z Invalid `docstring_style` value z. Supported styles are: .r r<) isinstancestr ValueErrorsortedr DOCSTRING_STYLE_ALIASESrBr7rGrr)rHnormalized_styles r+normalize_docstring_stylerQs os + .!!9&A[:\9__` b  /22?3H3H3JK .!!9&A[:\9__` b  6!!## (*: ;;r2new_arg deprecated_in remove_incx|r td|iznt}|rtnt}|||dz}|r|td|izz }|S)uBuild 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)rSreasonrT)TEMPLATE_DOC_ARG_REASON_RENAMEDTEMPLATE_DOC_ARG_REASON_REMOVED!TEMPLATE_DOC_ARG_DEPRECATED_SINCETEMPLATE_DOC_ARG_DEPRECATEDTEMPLATE_DOC_ARG_REMOVE)rRrSrTrVtemplatenotes r+_build_arg_deprecation_noter^sR$HO , 7/C CTsF4A0GbH  H HD '; *BBB Kr2ctjd}t|D]?\}}|j|s|t |t |j z fcSy)uLReturn ``(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 `_ 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)recompiler6matchr.lstrip)r3 _section_reir"s r+_find_google_args_sectionrgs],**9:KU#54   T "c$i#dkkm"444 45 r2 section_startsection_indentcd}t|dzt|D]I}||jst||t||jz }||kDr|}n|dk(ry|dz}t|dzt|D]S}||}|jst|t|jz }||kr||fS||kDsN|}||fS||fS)aReturn ``(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)r3rhri arg_indentrfcurrent_indentcontinuation_indentr"s r+_get_google_arg_indentsrqs"J =1$c%j 1 8>>  q]Sq1B-CCN.+  R$q. =1$c%j 1 Qxzz| TS%77 ^ +  * ** J &"0   * **  * **r2rnarg_namecdt|dzt|D]}||}|jst|t|jz }||kry||k(sK||d}t|t|kDxr|t|dv} ||k(s|j |s| s|cSy)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``. r5Nz :(,r`)rmr.r-rd startswith) r3rhrirnrrrfr"roresthas_arg_boundarys r+_find_google_arg_linerws$=1$c%j 1 Qxzz| TS%77 ^ +   Z ' $D"4y3x=8ZT#h-=PTZ=Z xDOOH$=BR  r2 entry_idx entry_indentc|}t|dzt|D]G}||}|js|St|t|jz |kr|S|}I|S)aReturn 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*). r5rl)r3rxryend_idxrfr"s r+_find_entry_endr|sw*G 9q=#e* -Qxzz|  N t9s4;;=) )\ 9  N  Nr2r]c,t|\}}|dk(r|dfSt|||\}}|dk(r|dfSt|||||}|dk(r|dfSt|||}t fd|||dzDr|dfSd|zz} |d|dz| gz||dzdz} | dfS)utFind *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`Fc3&K|]}|v ywNr(r)lnr]s r+r,z-_annotate_google_style_arg..]s B"42: Br5T N)rgrqrwr|any) r3rrr]rhrirnrp arg_line_idxr{ note_line new_liness ` r+_annotate_google_style_argr6s2%>e$D!M>e|&=e]Tb&c#J#Re|( ~z[cdLre|e\:>G BlWq[ A BBd{))D0Im! $ {2U7Q;=5III d?r2ctjdtj|zdz}d}d}t|D]6\}}|j |}|s|}t |j d}n|dk(r|dfSt|||} tfd||| dzDr|dfSd |d zzz} |d | dz| gz|| dzd z} | dfS) ueFind ``: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`rr5Fc3&K|]}|v ywrr(rs r+r,z-_annotate_sphinx_style_arg..s D"42: DrTrrkN) rarbescaper6rcr.groupr|r) r3rrr]patternparam_line_idx param_indentrfr"mr{rrs ` r+_annotate_sphinx_style_argrds.jj689LLwVWGNLU#4 MM$  Nqwwqz?L  e|e^\BG Dnw{ C DDd{|a'(4/Im! $ {2U7Q;=5III d?r2dep_infocj|jrd|jdnd}d}d}t|jra|jjd|jj}t j |jrdnd}d|d|d}d |d}t|j}|d k(r t}|}nt}|}g} |D]h} | jjd r|s%| jjd r|sG| j| |j||d zj| S)aRender 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). zWill be removed in rJr?classfunczUse :z:`z ` instead.zUse `r z%(remove_text)sz%(target_text)s)rS remove_text target_text)rTcallabletarget __module____name__inspectisclassrQrHTEMPLATE_DOC_DEPRECATED_MKDOCSTEMPLATE_DOC_DEPRECATED_RSTr-endswithappendrS) rrtarget_text_rsttarget_text_mkdocsfull_target_nameref_typerHr\rresultr"s r+_build_general_notice_linesrs?BJASAS'(:(:';1=Y[KO &oo8898??;S;S:TU%oohoo>7F!(2.>-?zJ$%5$6jA/0H0HIO("1( .% F  ::< !2 3K  ::< !2 3K  X%;%;Khst t   Mr2 wrapped_fnct|dr |jsyt|sy|jj}|j}|j rd}|j j D]M\}}t||j|j}t|||\}}|st|||\}}|rLd}O|rF|jtjur*tj dj#||_yt%|}dt&t(dt&t(dt*fd } | ||ryt-d |d dDd |j r|r9|d j/s&|j1|r|d j/s&|j3d |j5fd|Dtj dj#||_y|D cgc]} | z }} t7|} |d| } || d} | r$| d j/r| j3d | j5|| rr| r9| d j/s&| j1| r| d j/s&| r$| dj/r| j3d | j5| tj dj#| |_ycc} w)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. .. 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 syttz }|dkrydj}t|dzD]Cj|k7rtfdttDsCyy)zReturn True if ``block_lines`` appears as a contiguous block in ``doc_lines``. Lines are compared using ``.strip()`` to ignore leading/trailing whitespace. Frr5c3rK|].}|zj|jk(0ywr)r-)r)offsetrrstarts r+r,zU_update_docstring_with_deprecation.._has_deprecation_block..8s;U[ %&.)//1[5H5N5N5PPs47T)r.r-rmr/)rr max_startfirstrs`` @r+_has_deprecation_blockzB_update_docstring_with_deprecation.._has_deprecation_block)s  NS%55 q=A$$&9q=) E%%'50_dehiteu_v  r2c3K|]=}|js|dt|t|jz ?ywr)r-r.rd)r)r"s r+r,z5_update_docstring_with_deprecation..Bs4VD.D C .. /Vs A-Ar5r?r`c3(K|] }|z ywrr()r)r body_indents r+r,z5_update_docstring_with_deprecation..JsB"[2%Bsr)hasattrrr splitlines__deprecated__ args_mappingitemsr^rSrTrrrr ARGS_REMAPrcleandocjoinrlistrLboolnextr-poprextendr;)rr3rall_args_foundrrrRr]founddeprecation_linesrr insert_idxprefixsuffixrs @r+"_update_docstring_with_deprecationrsf :y )1C1C  ,    ) ) +E((H!)!6!6! ' Hg.w8N8NPXPbPbcD5eXtLLE59%4P u!&  ' hoo1F1FF!(!1!1$))E2B!CJ  3H=$s)$s)PT,e%67VE!"IV KE"IOO- IIKE"IOO- R B0ABB$--dii.>? 9JJ"[2-JJ3E: { #z{# fRj&&( MM"  '( !1!1!3 !1!1!3&)//+ b! MM& !$--dii.?@ Ks< K4)-rrr@rarCtypingrrrdeprecate._typesrrrrrrYrZr[rXrWrO frozensetr rL__annotations__r8r9rr1rintr;rGrQr^tuplergrqrwr|rrrobjectrr(r2r+rs\2 **QQ " %]!=?"2"=#)%8Yab-67N-OIcNO  HSHTH $s)  GO40