o nnh!@sddlmZddlZddlZddlmZddlmZm Z ddl m Z m Z ddl mZddlmZeZdd d d d Zd dZddZdddZdddZdddZdddZddZdS)) annotationsN) constants) AnsibleErrorAnsibleParserError)to_text to_native) AnsibleLoader)Displaydoc plainexamples returndocsmetadata) DOCUMENTATIONEXAMPLESRETURNANSIBLE_METADATAcCs&tD] \}}||kr|SqdS)z" reverse lookup of the dict above N)string_to_varsitems)valuekvrF/usr/local/lib/python3.10/dist-packages/ansible/parsing/plugin_docs.py _var2strings rcCsddtDS)z? initialize a return dict for docs with the expected structure cSsi|]}|dqS)Nr).0rrrr #sz"_init_doc_dict..)rvaluesrrrr_init_doc_dict!srTc Cst}i}z!t|d}t||d}Wdn1s wYWn)tyO}zd|t|f}|s>t||d|rEt |WYd}~nd}~ww|rat D] }| |d|t |<qT|S)z5 Read docs from 'sidecar' yaml file doc for a plugin rb file_nameNz"Unable to parse yaml file '%s': %sorig_exc) ropenrreadget_single_data Exceptionrrdisplayerrorrget) filenameverbose ignore_errorsdata file_datayamlfileemsgkeyrrrread_docstring_from_yaml_file&s&   r3c Cstt}t}d}t|}t|j}|D]}|jtjkr3|jdkr3|j t vr3|j |vr3t |j }q|dur|jtj kr| |j |j } | drP| d} | drZ| d} |dkret| ||<n9z t| |d||<Wn,ty} z d t||t| f} |st| | d |rt| WYd} ~ nd} ~ wwd}qWdn1swY|st|||}|S) z Use tokenization to search for assignment of the documentation variables in the given file. Parse from YAML and return the resulting python structure or None together with examples as plain text. N)rbr)'"z'"r rz1Unable to parse docs '%s' in python file '%s': %sr!)setrtokenizer#generate_tokensreadlinetypeNAMEstartstringrSTRINGadd startswithlstripstriprrr%r&rrrr'r(read_docstring_from_python_file) r*r+r,seenr- next_stringftokenstokenrr0r1rrr!read_docstring_from_python_module=sH           . rLc Cslt}zt|d}t|}Wdn1swY|jD]^}t|tjr|jD]R}z|j }Wnt yGt d||fYq.w|t vrt |} t|jtjr`t|j|| <n|dkrmt|jj|| <n t|jj|d|| <t d| q.q#W|Sty} z%d|t| f} |st| | d|rt | WYd} ~ |SWYd} ~ |Sd} ~ ww) z Use ast to search for assignment of the DOCUMENTATION and EXAMPLES variables in the given file. Parse DOCUMENTATION from YAML and return the YAML doc or None together with EXAMPLES, as plain text. rNzBBuilding documentation, failed to assign id for %s on %s, skippingrrzDocumentation assigned: %sz5Unable to parse documentation in python file '%s': %sr!)rr#astparser$body isinstanceAssigntargetsidAttributeErrorr'warningrrDict literal_evalrrr%debugr&rrr() r*r+r,r- b_module_dataMchildttheidvarkeyr0r1rrrrF{sH         rFcCsp|tjrt|||d}n|tjrt|||d}n |s&tdt||s2|s2tdt|d|d<|S)zC returns a documentation dictionary from Ansible plugin docstrings )r+r,z Unknown documentation format: %sz%Unable to parse documentation for: %sNseealso)endswithCYAML_DOC_EXTENSIONSr3PYTHON_DOC_EXTENSIONSrLrr)r*r+r, docstringrrrread_docstrings  rec Csd}d}d}g}t|dQ}|D]F}|rG|r!||r!||q|r*||s*n-|drFd}dt|t|d}||q|drVd |vsTd |vrVd}qWd n1sawYd|d }t||d  }|S)z Quickly find short_description using string methods instead of node parsing. This does not return a full set of documentation strings and is intended for operations like ansible-doc -l. Fr5zshort_description:T r4r=:N.r) r#rCappendrDlenjoinrErstriprr%) r*in_documentation capturingindent_detectiondoc_stub t_module_datalineshort_descriptionr-rrr read_docstubs.   rv)TT) __future__rrMr:ansiblerraansible.errorsrr+ansible.module_utils.common.text.convertersrransible.parsing.yaml.loaderransible.utils.displayr r'rrrr3rLrFrervrrrrs*       > /