lcpdZddlZddlZddlZddlZddlZddlmZddlm Z dZ dZ dd Z dd Z d Zd ZdS)zFCommon functions for working with docstrings. For internal use only. N) compression) transportz* smart_open/doctools.py magic goes herec |sgStj|d}g}|r/|ddkr#|d|r |ddk#|sgS|d|d|r|dr|ddd\}}g}|rr|ddrW||d|r|ddWd|vr<||||f|r|d|S)a_Extract keyword argument documentation from a function's docstring. Parameters ---------- docstring: str The docstring to extract keyword arguments from. Returns ------- list of (str, str, list str) str The name of the keyword argument. str Its type. str Its documentation as a list of lines. Notes ----- The implementation is rather fragile. It expects the following: 1. The parameters are under an underlined Parameters section 2. Keyword parameters have the literal ", optional" after the type 3. Names and types are not indented 4. Descriptions are indented with 4 spaces 5. The Parameters section ends with an empty line. Examples -------- >>> docstring = '''The foo function. ... Parameters ... ---------- ... bar: str, optional ... This parameter is the bar. ... baz: int, optional ... This parameter is the baz. ... ... ''' >>> kwargs = extract_kwargs(docstring) >>> kwargs[0] ('bar', 'str, optional', ['This parameter is the bar.'])  r Parameters:r optional)inspectcleandocsplitpop startswithappendstrip) docstringlinesretvalnametype_ descriptions 3lib/python3.11/site-packages/smart_open/doctools.pyextract_kwargsrs\   Y ' ' - -d 3 3E F E!H , !  E!H ,   IIaLLL IIaLLL FE!HFiill((a00 e  5a++F33 5   uyy||1133 4 4 4 5a++F33 5   F MM4::<< D E E E FE!HF Mctj}|D]C\}}}|||d|d|D]}||d|dD|S)aReconstruct a docstring from keyword argument info. Basically reverses :func:`extract_kwargs`. Parameters ---------- kwargs: list Output from the extract_kwargs function lpad: str, optional Padding string (from the left). Returns ------- str The docstring snippet documenting the keyword arguments. Examples -------- >>> 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: rr )ioStringIOwritegetvalue)kwargslpadbufrrrlines r to_docstringr&fs> +--C$*33 e[ $$eee4555 3 3D IIdddDDD1 2 2 2 2 3 <<>>rr ctjtjt}tj|dd} t |5}t|}dddn #1swxYwY|d}|d}||dz|dz }dfd |DS#t$rd zcYSwxYw) aOExtract examples from this project's README.rst file. Parameters ---------- indent: str Prepend each line with this string. Should contain some number of spaces. Returns ------- str The examples. Notes ----- Quite fragile, depends on named labels inside the README.rst file. z..z README.rstNz.. _doctools_before_examples: z.. _doctools_after_examples: rcBg|]}tjdd|zS)z^ r)resub).0r%indents r z4extract_examples_from_readme_rst..s,KKKTr4!8!88KKKrzSee README.rst) ospathdirnameabspath__file__joinopenlistindex Exception)r.curr_dir readme_pathfinrstartends` r extract_examples_from_readme_rstr?s;"wrwx8899H',,x|<>kk:;;eAgc!em$wwKKKKUKKKLLL )))((((()s7%C64B C6BC6BAC66DDc tj}t}tjtjt }tj|5tdtttj D] \}}|tjks||vr||tj|j|}|d|d}td|ztddt#|zztd|jddztt)|jj}|rtt-|d  td td ttt/td tdtt1jD]} td| zttddddn #1swxYwY|jr9|jt6||_dSdS)Nz; smart_open supports the following transport mechanisms:)r=z ()z %s~rrr )r#z Examplesz --------zJ This function also supports transparent compression and decompression z using the following codecs: * %szR The function depends on the file extension to determine the appropriate codec.)rrsetr0r1r2r4 contextlibredirect_stdoutprintsortedr _REGISTRYitems NO_SCHEMEaddrelpathlen__doc__rrr6r&r?rget_supported_extensionsreplace PLACEHOLDERr!) fr$seen root_pathscheme submodulerMheadingr" extensions rtweak_open_docstringrZs +--C 55D 9 9::I  #C ( (dd KLLL !' (;(A(A(C(C!D!D : : FI,,  T0A  HHY   gooi&8 oJJG#)667773G (W$ % % % (cCLL01 2 2 2 (Y.44T::1== > > > GGG#IN$:;;F :l6888999 n n  .00111 Z[[[ /000 $=?? * *I *y( ) ) ) )  bccc=dddddddddddddddF yCI%%k3<<>>BB CCs7H JJJcLtj}t}g}g}ttjD]o\}}|tjks||vr||| | | |j `#t$rYlwxYwtj|5tdt|D]}td|zttdt|D]}td|z dddn #1swxYwY|jr9|jt$||_dSdS)Nz Supported URI schemes are:rCz Valid URI examples::)rrrDrHrrIrJrKrrLextend URI_EXAMPLESAttributeErrorrErFrGrOrQrRr!)rSr$rTschemesexamplesrVrWexamples rtweak_parse_uri_docstringrbs +--C 55DGH#I$7$=$=$?$?@@   Y( ( I,=  v   OOI2 3 3 3 3    D   #C ( ( ( ( .///  ' 'F *v% & & & &  ()))  ( (G *w& ' ' ' ' ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( ( yCI%%k3<<>>BB CCs%B11 B>=B>A7EE E)r)r )rOrEr ros.pathr0r+rrrrRrr&r?rZrbrrres   : IIIX$$$$N))))<*C*C*CZCCCCCr