^Mh*dZddlmZmZmZddlmZmZddlZgdZ edede fZ Gd d eZ dd e d ee e fdzd e fdZde d e fdZde de d e fdZde de d e fdZdee d efdZd d ee e fded e fdZd ee e fd ee e ffdZd e d e fdZde de de d e fdZdS)!zkUtilities to allow inserting docstring fragments for common parameters into function and method docstrings.)CallableIterableMapping)ProtocolTypeVarN) docformatinherit_docstring_fromindentcount_linesfilldoc unindent_dictunindent_stringextend_notes_in_docstringreplace_notes_in_docstring doc_replace_F.)boundc"eZdZdZdedefdZdS) DecoratorzA decorator of a function.funcreturncdSN)selfrs Q/var/www/html/test/jupyter/venv/lib/python3.11/site-packages/scipy/_lib/doccer.py__call__zDecorator.__call__sN)__name__ __module__ __qualname____doc__rrrrrrrs,$$.R.r......rr docstringdocdictrc|s|S|i}|s|S|}t|dkrd}nt|dd}d|z}i}|D]\}}|} |dg}|ddD]} ||| zd|||<s#t$r|||<YwxYw||zS)abFill a function docstring from variables in dictionary. Adapt the indent of the inserted docs Parameters ---------- docstring : str A docstring from a function, possibly with dict formatting strings. docdict : dict[str, str], optional A dictionary with keys that match the dict formatting strings and values that are docstring fragments to be inserted. The indentation of the inserted docstrings is set to match the minimum indentation of the ``docstring`` by adding this indentation to all lines of the inserted string, except the first. Returns ------- docstring : str string with requested ``docdict`` strings inserted. Examples -------- >>> docformat(' Test string with %(value)s', {'value':'inserted value'}) ' Test string with inserted value' >>> docstring = 'First line\n Second line\n %(value)s' >>> inserted_string = "indented\nstring" >>> docdict = {'value': inserted_string} >>> docformat(docstring, docdict) 'First line\n Second line\n indented\n string' Nr  ) expandtabs splitlineslenr itemsappendjoin IndexError) r"r#linesicountindentindentednamedstrnewlineslines rrrsA@    " " - - / /E 5zzA~~"59-- 6\FHmmoo"" d!!,,.. "azHabb  / / ....!YYx00HTNN " " "!HTNNN " x s'AC..D?Dclsc0dtdtffd }|S)aThis decorator modifies the decorated function's docstring by replacing occurrences of '%(super)s' with the docstring of the method of the same name from the class `cls`. If the decorated method has no docstring, it is simply given the docstring of `cls`s method. Parameters ---------- cls : type or object A class with a method with the same name as the decorated method. The docstring of the method in this class replaces '%(super)s' in the docstring of the decorated method. Returns ------- decfunc : function The decorator function that modifies the __doc__ attribute of its argument. Examples -------- In the following, the docstring for Bar.func created using the docstring of `Foo.func`. >>> class Foo: ... def func(self): ... '''Do something useful.''' ... return ... >>> class Bar(Foo): ... @inherit_docstring_from(Foo) ... def func(self): ... '''%(super)s ... Do it fast. ... ''' ... return ... >>> b = Bar() >>> b.func.__doc__ 'Do something useful. Do it fast. ' rrct|jj}|j}|||_n|t|z}||_|S)N)super)getattrrr!dict)r cls_docstringfunc_docstring new_docstringr8s r_docz$inherit_docstring_from.._docsNT]33;   !(DLL*T -F-F-FFM(DL rr)r8rAs` rr r Xs7X2" Krnotesc4dtdtffd }|S)aThis decorator replaces the decorated function's docstring with the docstring from corresponding method in `cls`. It extends the 'Notes' section of that docstring to include the given `notes`. Parameters ---------- cls : type or object A class with a method with the same name as the decorated method. The docstring of the method in this class replaces the docstring of the decorated method. notes : str Additional notes to append to the 'Notes' section of the docstring. Returns ------- decfunc : function The decorator function that modifies the __doc__ attribute of its argument. rrct|jj}||S|d}|dkr*|d}|dkrt |}|d|z||dz|_|S)N References  Examples r<rr!findr+)rr> end_of_notesr8rCs rrAz'extend_notes_in_docstring.._docsT]33;   K$))*@AA 2  (--.BCCLr!!"=11 -<- (5 0=3O O  rrBr8rCrAs`` rrrs<,2" Krc4dtdtffd }|S)aThis decorator replaces the decorated function's docstring with the docstring from corresponding method in `cls`. It replaces the 'Notes' section of that docstring with the given `notes`. Parameters ---------- cls : type or object A class with a method with the same name as the decorated method. The docstring of the method in this class replaces the docstring of the decorated method. notes : str The notes to replace the existing 'Notes' section with. Returns ------- decfunc : function The decorator function that modifies the __doc__ attribute of its argument. rrcVt|jj}d}||S||}|d}|dkr*|d}|dkrt |}|d|t |zz||dz|_|S)Nz Notes ----- rFrGrHrI)rr> notes_headerstart_of_notesrKr8rCs rrAz(replace_notes_in_docstring.._docsT]33; 7   K&++L99$))*@AA 2  (--.BCCLr!!"=11 >NS->->>> ? LMM* +  rrBrLs`` rrrs<,2"( Krr0ctj}|D]E}|}|r-t|t |t |z }F|tjkrdS|S)aMinimum indent for all lines in line list Parameters ---------- lines : Iterable[str] The lines to find the minimum indent of. Returns ------- indent : int The minimum indent. Examples -------- >>> lines = [' one', ' two', ' three'] >>> indentcount_lines(lines) 1 >>> lines = [] >>> indentcount_lines(lines) 0 >>> lines = [' one'] >>> indentcount_lines(lines) 1 >>> indentcount_lines([' ']) 0 r)sysmaxsizelstripminr+)r0indentnor7strippeds rr r sj8{H@@;;==  @8SYYX%>??H3;q OrTunindent_paramscR|rtdtdtffd }|S)aReturn docstring decorator using docdict variable dictionary. Parameters ---------- docdict : dict[str, str] A dictionary containing name, docstring fragment pairs. unindent_params : bool, optional If True, strip common indentation from all parameters in docdict. Default is False. Returns ------- decfunc : function The decorator function that applies dictionary to its argument's __doc__ attribute. rrcD|jpd}t||_|S)N)r!r)rdocr#s rdecoratezfilldoc..decorate!s%l b g..  r)r r)r#rXr]s` rr r sM")((rb Orcbi}|D]\}}t|||<|S)aUnindent all strings in a docdict. Parameters ---------- docdict : dict[str, str] A dictionary with string values to unindent. Returns ------- docdict : dict[str, str] The `docdict` dictionary but each of its string values are unindented. )r,r )r#can_dictr4r5s rr r *s< "Hmmoo// d(.. Orc|}t|dkr|Sdfd|DS)aqSet docstring to minimum indent for all lines, including first. Parameters ---------- docstring : str The input docstring to unindent. Returns ------- docstring : str The unindented docstring. Examples -------- >>> unindent_string(' two') 'two' >>> unindent_string(' two\n three') 'two\n three' rr(c$g|] }|d Srr).0r7r1s r z#unindent_string..Us!666d677m666r)r)r*r r.)r"r0r1s @rr r =se(  " " - - / /E u % %F {{ 996666666 7 77robjoldvalnewvalcj|jpd||dtdtffd }|S)azDecorator to take the docstring from obj, with oldval replaced by newval Equivalent to ``func.__doc__ = obj.__doc__.replace(oldval, newval)`` Parameters ---------- obj : object A class or object whose docstring will be used as the basis for the replacement operation. oldval : str The string to search for in the docstring. newval : str The string to replace `oldval` with in the docstring. Returns ------- decfunc : function A decorator function that replaces occurrences of `oldval` with `newval` in the docstring of the decorated function. r[rrc|_|Sr)r!)rr\s rinnerzdoc_replace..innerps  r)r!replacer)rdrerfrir\s @rrrXsT, ; " % %ff 5 5CB2 Lrr)T)r!collections.abcrrrtypingrrrR__all__objectrrstrrr rrintr boolr r=r r rrrrrrsK338777777777$$$$$$$$     WT#v+./////////// 8 8 8 wsCx'84'?8 38 8 8 8 v6696666r&6&#&)&&&&R*F*3*9****Z#Xc]#s####LWS#X&:738,c3h&8s8s88886VS#)r