3 d"+@s~dZddlZddlmZddlmZddd Zd d Zdd d ZddZ ddZ dddZ dgfddZ dddZ ddZdS)zUtilities to pull in documentation from command-line tools. Examples -------- # Instantiate bet object from nipype.interfaces import fsl from nipype.utils import docparse better = fsl.Bet() docstring = docparse.get_doc(better.cmd, better.opt_map) N) CommandLine) is_containerTcCsLtj|tjtjdd}|j\}}|r@|jr@d||f}t||rH|S|S)a Run cmd without args and grab documentation. Parameters ---------- cmd : string Command line string trap_error : boolean Ensure that returncode is 0 Returns ------- doc : string The command line documentation T)stdoutstderrshellz(Attempting to run %s. Returned Error: %s) subprocessPopenPIPE communicate returncodeIOError)cmd trap_errorprocrrmsgr7/tmp/pip-build-7vycvbft/nipype/nipype/utils/docparse.pygrab_docs   rcCsRi}xHt|jD]8\}}t|r*|d}|dkr|dk r|||jd<qW|S)atReverse the key/value pairs of the option map in the interface classes. Parameters ---------- opt_map : dict Dictionary mapping the attribute name to a command line flag. Each interface class defines these for the command it wraps. Returns ------- rev_opt_map : dict Dictionary mapping the flags to the attribute name. rflagsN)listitemsrsplit)opt_mapZrevdictkeyvaluerrrreverse_opt_map6srcCsd}d}|jd||jd|dj|}g}dj|}|rd}d}|jd||jd||jdddj|}dj||g}|S)aFormat the parameters according to the nipy style conventions. Since the external programs do not conform to any conventions, the resulting docstrings are not ideal. But at a minimum the Parameters section is reasonably close. Parameters ---------- paramlist : list List of strings where each list item matches exactly one parameter and it's description. These items will go into the 'Parameters' section of the docstring. otherlist : list List of strings, similar to paramlist above. These items will go into the 'Other Parameters' section of the docstring. Returns ------- doc : string The formatted docstring. Z Parametersz ----------r zOthers Parametersz-----------------)insertjoin)Z paramlistZ otherlisthdrdelimparamsZ otherparamsdocrrr format_paramsUs         r&cCsl|jd}|dd}|j||j|ddg}x |D]}|j||jdq>> from nipype.utils.docparse import insert_doc >>> doc = '''Parameters ... ---------- ... outline : ... something about an outline''' >>> new_items = ['infile : str', ' The name of the input file'] >>> new_items.extend(['outfile : str', ' The name of the output file']) >>> newdoc = insert_doc(doc, new_items) >>> print(newdoc) Parameters ---------- infile : str The name of the input file outfile : str The name of the output file outline : something about an outline rNrrr)rextendappendpopr!)r%Z new_itemsdoclistZtmpdocnewdoclinerrr insert_doc~s%      r.c Cs|jd}g}g}x|D]}|j}|s*qd|dkrJ|djdd}n|d}|j|}|dk rdt||d<dj|} |j| q|djr|j|qWt||S)aBuild docstring from doc and options Parameters ---------- rep_doc : string Documentation string opts : dict Dictionary of option attributes and keys. Use reverse_opt_map to reverse flags and attrs from opt_map class attribute. Returns ------- newdoc : string The docstring with flags replaced with attribute names and formated to match nipy standards (as best we can). r,rNz %s :  )rgetstrr!r)isspacer&) r%optsr+r,Z flags_docr-linelistflagattrnewlinerrr build_docs$       r9cCsxtd|jdddddj}|jjj}|dkrJtd|jdd|r\dj||f}t||}t |}t ||S) aGet the docstring from our command and options map. Parameters ---------- cmd : string The command whose documentation we are fetching opt_map : dict Dictionary of flags and option attributes. help_flag : string Provide additional help flag. e.g., -h trap_error : boolean Override if underlying command returns a non-zero returncode Returns ------- doc : string The formated docstring zwhich %sr0rF allatonce)resource_monitorterminal_outputrzCommand %s not found) rrrunruntimerstrip Exceptionr!rrr9)rr help_flagrrescmd_pathr%r4rrrget_docs   rD--c s|jd}i}tttfr"gx|D]}|j}fddt|Dr(tdkr|fddDjd}dnXg}x8D]0}x*tD]\}} |j| r|j|PqWqW|jt |t |}d|j|d<q(W|S) zParses a help doc for inputs Parameters ---------- doc : string Documentation string style : string default ['--'] The help command style (--, -) Returns ------- optmap : dict of input parameters rcs>g|]6\}|dkrtfddDrtdkrqS)rcsg|]}j|qSr) startswith).0s)itemrr %sz)_parse_doc...r)anylen)rGi)style)rIrrJ#sz_parse_doc..rcsg|]}dj|qS)r)rF)rGrH)r6rrrJ)sTrz%s %%s) r isinstancer2bytes enumeraterLindexrFr)min) r%rNr+Zoptmapr-r5Z style_idxfrMrHr)r6rNr _parse_doc s,          rUcCsptd|jdddddj}|jjj}|dkrJtd|jdd|r\dj||f}t||}t ||S) a9Auto-generate option map from command line help Parameters ---------- cmd : string The command whose documentation we are fetching style : string default ['--'] The help command style (--, -). Multiple styles can be provided in a list e.g. ['--','-']. help_flag : string Provide additional help flag. e.g., -h trap_error : boolean Override if underlying command returns a non-zero returncode Returns ------- optmap : dict Contains a mapping from input to command line variables zwhich %sr0rFr:)r;r<rzCommand %s not found) rrr=r>rr?r@r!rrU)rrNrArrBrCr%rrrget_params_from_doc8s   rVcCs*x$t|jD]\}}|j||}qW|S)amReplace flags with parameter names. This is a simple operation where we replace the command line flags with the attribute names. Parameters ---------- rep_doc : string Documentation string opts : dict Dictionary of option attributes and keys. Use reverse_opt_map to reverse flags and attrs from opt_map class attribute. Returns ------- rep_doc : string New docstring with flags replaces with attribute names. Examples -------- doc = grab_doc('bet') opts = reverse_opt_map(fsl.Bet.opt_map) rep_doc = replace_opts(doc, opts) )rrreplace)Zrep_docr4rvalrrr replace_opts[srY)T)N)NT)rENT)__doc__r Zinterfaces.baserZmiscrrrr&r.r9rDrUrVrYrrrrs   ! )55 #- #