暾jdZddlmZddlZddlZddlZddlZddlmZddl m Z m Z m Z ddl mZmZe rddlmZej$d k\rd Zd Znd Zd ZddZdddZdddZddZddZy)zFCommon functions for working with docstrings. For internal use only. ) annotationsN)Path) TYPE_CHECKINGAnycast) compression transport)Callable) z&smart_open/doctools.py magic goes herez* smart_open/doctools.py magic goes here cp|sgStj|jd}t|D]"\}}|j dk(s||dzd}ngSg}|D]}|j s|S|j drt|j dsc|dd}d|vrB|jdd\}}|j|j d |j r|j gngg|j ds|s|d d j|j |S) a8Extract keyword argument documentation from a Google-style ``Args:`` section. Args: docstring: The docstring to extract keyword arguments from. Returns: A list of ``[name, type, description_lines]`` triples. ``type`` is always an empty string since Google-style docstrings in this codebase don't carry argument types, and ``description_lines`` is a list of lines. Note: The implementation expects: 1. The parameters are under an ``Args:`` header 2. Argument lines start with 4 spaces of indent (`` name: desc``) 3. Continuation lines for a description are indented with 8 spaces 4. The ``Args:`` section ends with an empty line or another section header. Example: >>> docstring = '''The foo function. ... Args: ... bar: This parameter is the bar. ... baz: This parameter is the baz. ... ... ''' >>> kwargs = extract_kwargs(docstring) >>> kwargs[0] ['bar', '', ['This parameter is the bar.']]  zArgs:rNrz :r)inspectcleandocsplit enumeraterstripstrip startswithappend) docstringlinesidxlinekwargsstrippednamedescs ]/home/spazio/kingdom_calls/work5/transenv/lib/python3.12/site-packages/smart_open/doctools.pyextract_kwargsr&'s1>    Y ' - -d 3Eu% T ;;=G ##')$E    F 0zz|  M ??6 "4??:+FABxH("!Q/JD$ MM4::<tzz|djjl^QST U  ??: &6 2JrN ! !$**, / 0 Mctj}|D]V\}}}|r|j||d|dn|j||d|D]}|j|d|dX|jS)aReconstruct a docstring from keyword argument info. Basically reverses :func:`extract_kwargs`. Args: kwargs: Output from the :func:`extract_kwargs` function. lpad: Padding string (from the left). Returns: The docstring snippet documenting the keyword arguments. Example: >>> kwargs = [ ... ("bar", "str, optional", ["This parameter is the bar."]), ... ("baz", "int, optional", ["This parameter is the baz."]), ... ] >>> print(to_docstring(kwargs), end="") bar: str, optional This parameter is the bar. baz: int, optional This parameter is the baz. z: rz: r)ioStringIOwritegetvalue)r!lpadbufr#type_ descriptionr s r% to_docstringr1es. ++-C$*- e[  IItfBugR0 1 IItfC( ) -D IId4&+ , - - <<>r'ctttjjjdz } |j d}|j ddd}|j ddd}|j dddjd dd}|jd j d }d jfd |DS#t$rd zcYSwxYw)a`Extract examples from this project's README.md file. Args: indent: Prepend each line with this string. Should contain some number of spaces. Returns: The examples as a single string. Note: Quite fragile, depends on the example markers and the fenced code block inside the README.md file. z README.mdzutf-8)encodingz!rz rz ```pythonz```rrc3.K|] }|zdzyw)rN).0r indents r% z/extract_examples_from_readme..s>v}t+>sz See README.md) LPADr__file__resolveparent read_textrrsplitrjoin Exception)r7 readme_pathtextbodyrs` r%extract_examples_from_readmerDs~x.((*1188;FK ($$g$6zz=qA!Dzz>>> (''(sBCC.-C.c tj}t}ttj j }t dz}tt d|t|ttjjD]:\}}|tjk(s||vr|j| |j}tt!d|jj#|}dj%dj'||} t|| |t|dt)| z|t||j*xsdj-t/d d |t|t1|j2j*} | s#tt5| | |=tt d |t|tt7| |tt d|t|t|d|t|d|t|t9j:D]} t|d| |t|t|d||j*r4|j*j=t>|jA|_yy#t$r|g}YwxYw)zJInject transport, compression and example sections into ``f``'s docstring.rz Transports:filestrz{} ({})/~r r)r- Examples:)r7zCodecs:zGsmart_open supports transparent compression and decompression for fileszwith the following extensions:* z2The codec is selected based on the file extension.N)!r)r*setrr:r<r9printsortedr _REGISTRYitems NO_SCHEMEaddSCHEMESAttributeErrorr relative_toformatr?len__doc__rchrr&openr1rDr get_supported_extensionsreplace PLACEHOLDERr,) fr.seen root_pathbody_padscheme submoduleschemesrelpathheadingr! extensions r%tweak_open_docstringrjsr ++-C 5DX%%,,If}H TF+ S) sO#I$7$7$=$=$?@A Y(( (I,=   ''GtE9#5#567CCIN""388G#4g>  7)$3/  3W-./c:  I--3::3r7CAFGHsS 3  6 67  ,vH5C @'A* TF) 3' sO &h 7cB TF' % sO XJ] ^ehi XJ4 5C@ sO 99;4   "YK(s34 sO XJH IPST  yyII%%k3<<>B ? hG s K K+*K+ctj}t}g}g}ttj j D]\}}|tjk(s||vr|j|tjt5|j|jddd |j|jt dz}t#t d|t#||D]}t#|d||t#|t#t d|t#||D]}t#|d|||j$r4|j$j't(|j+|_yy#1swYxYw#t$r|j|Y{wxYw)zAInject supported schemes and example URIs into ``f``'s docstring.NrzSchemes:rFrMrL)r)r*rNrPr rQrRrSrT contextlibsuppressrVextend URI_EXAMPLESrUrr9rOrZr^r_r,) r`r.rarfexamplesrdrercexamples r%tweak_parse_uri_docstringrrs ++-C 5DGH#I$7$7$=$=$?@ # Y(( (I,=     0 4 OOI22 3 4 # NN9,, - #f}H TF( #& sO1  "VH%C01 sO TF) 3' sO2  "WI&S12 yyII%%k3<<>B ) 4 4  # NN6 " #sF7F(F% (GG)r str | Nonereturnzlist[list[Any]])r)r!z list[Any]r-rHrtrH)N)r7rsrtrH)r`zCallable[..., Any]rtNone)rZ __future__rrlrr)syspathlibrtypingrrrrr r collections.abcr version_infor_r9r&r1rDrjrrr5r'r%r|so # ++$( w:K D>K D;|D(:1Ch"Cr'