o nnh@sBddlmZddlmZddlZddlZddlZddlZddlZddl Z ddl Z ddl m m ZddlmZddlmZddlmZddlmZddlmZdd lmZmZmZmZdd lm Z m!Z!dd l"m#Z#dd l$m%Z%dd l&m'Z'ddl(m)Z)ddl*m+Z+ddl,m-Z-ddl.m/Z/ddl0m1Z1ddl m2Z2m3Z3ddl4m5Z5m6Z6ddl7m8Z8ddl9m:Z:ddl;mZ>m?Z?m@Z@e<ZAejBdZCgdZDiZEgdZFddddd d!d"d#ZGd$d%d&d&d'ZHd(d)d*d)d+d(d,ZId-d.ZJGd/d0d0eKZLd1d2ZMd3d4ZNGd5d6d6eeLZOd7d8ZPd9d:ZQd>d;d<ZReSd=kreRdSdS)?) annotations)CLIN)Path) constants)context)option_helpers)list_collection_dirs) AnsibleErrorAnsibleOptionsErrorAnsibleParserErrorAnsiblePluginNotFound) to_nativeto_text) is_sequence) json_dump) yaml_dump) string_types) read_docstub) from_yaml) AnsibleDumper) list_plugins) action_loaderfragment_loader)AnsibleCollectionConfigAnsibleCollectionRef)_get_collection_name_from_path)stringc)Display)get_plugin_docs get_docstringget_versioned_doclink)rolekeyword)PlayRoleBlockTaskHandler) inventorylookupmodulezzzzzzz)BLINKBOLDHIDENORMALRESETREVERSE UNDERLINEz*%s*z`%s`z[%s])r,r1MODULEPLUGINyellowmagentacyanz dark gray)r2REFLINKDEPCONSTANTr3c CsLz tt|WdSty%}ztttdt|d}~ww)NzXWe could not convert all the documentation into JSON as there was a conversion issue: %s)displayr TypeErrorvvv traceback format_excr r )texterB:/usr/local/lib/python3.10/dist-packages/ansible/cli/doc.pyjdumpNsrDc@seZdZdZddejDZddejDeZddZddZ d d Z dd d Z dddZ ddZ ddZdddZdddZd S) RoleMixinzA mixin containing all methods relevant to role argument specification functionality. Note: The methods for actual display of role data are not present here. cCg|]}d|qS)mainrB.0rArBrBrC ^zRoleMixin.cCrF)argument_specsrBrHrBrBrCrJ_rKc Cs|r tj|d|d}ntj|d}|D]}tj||}tj|r(|}nq|dur/iSz1t|d!} t| |d} | durMi} WdW| SWdW| S1sYwYW| Sttfyx} z t d||f| dd} ~ ww)a Load and process the YAML for the first found of a set of role files :param str root: The root path to get the files from :param str files: List of candidate file names in order of precedence :param str role_name: The name of the role for which we want the argspec data. :param str collection: collection name or None in case of stand alone roles :returns: A dict that contains the data requested, empty if no data found rolesmetaNr) file_namez$Could not read the role '%s' (at %s)orig_exc) ospathjoinexistsopenrreadIOErrorOSErrorr ) selfrootfiles role_name collection meta_pathspecfile full_pathrTfdatarArBrBrC_load_role_dataas6     zRoleMixin._load_role_datacCs|||j||}|d=|S)a~Load the roles metadata from the source file. :param str role_name: The name of the role for which we want the argspec data. :param str role_path: Path to the role/collection root. :param str collection: collection name or None in case of stand alone roles :returns: A dict of all role meta data, except ``argument_specs`` or an empty dict rL)reROLE_METADATA_FILES)r[r^ role_pathr_rdrBrBrC_load_metadatas zRoleMixin._load_metadatac Csbz|||j||}|di}W|Sty0}zd|t|f|d}WYd}~|Sd}~ww)aLoad the role argument spec data from the source file. :param str role_name: The name of the role for which we want the argspec data. :param str role_path: Path to the role/collection root. :param str collection: collection name or None in case of stand alone roles We support two files containing the role arg spec data: either meta/main.yml or meta/argument_spec.yml. The argument_spec.yml file will take precedence over the meta/main.yml file, if it exists. Data is NOT combined between the two files. :returns: A dict of all data underneath the ``argument_specs`` top-level YAML key in the argspec data file. Empty dict is returned if there is no data. rLzFailed to process role (%s): %s)error exceptionN)reROLE_ARGSPEC_FILESget Exceptionr )r[r^rgr_rdrArBrBrC _load_argspecs zRoleMixin._load_argspecNc Cst}t}|D]G}tj|sqt|D]8}tj||}|jD]+}tj|d|} tj| rM|dus:||vrK||vrK||||d|fnq"qq|S)aFind all non-collection roles that have an argument spec file. Note that argument specs do not actually need to exist within the spec file. :param role_paths: A tuple of one or more role paths. When a role with the same name is found in multiple paths, only the first-found role is returned. :param name_filters: A tuple of one or more role names used to filter the results. :returns: A set of tuples consisting of: role name, full role path rNN) setrSrTisdirlistdirrUrkrVadd) r[ role_paths name_filtersfound found_namesrTentryrgrarbrBrBrC_find_all_normal_roless&     z RoleMixin._find_all_normal_rolesc Cst}t|d}|D]}}t|dd}t|}tj|d}tj|rt|D]^} |j D]X} tj|| d| } tj| r|durK| | ||fn8|D]5} t | ddkrv| d\} }}d| |g|kru| |kru| | ||fqM| | kr| | ||fqMnq-q(q |S) aFind all collection roles with an argument spec file. Note that argument specs do not actually need to exist within the spec file. :param name_filters: A tuple of one or more role names used to filter the results. These might be fully qualified with the collection name (e.g., community.general.roleA) or not (e.g., roleA). :param collection_filter: A list of strings containing the FQCN of a collection which will be used to limit results. This filter will take precedence over the name_filters. :returns: A set of tuples consisting of: role name, collection name, collection path ) coll_filtersurrogate_or_stricterrorsrMrNN.) rorrrrSrTrUrVrqrkrrlensplit)r[rtcollection_filterru b_colldirsb_pathrTcollname roles_dirrwrarbfqcnnscolr!rBrBrC_find_all_collection_roless4      z$RoleMixin._find_all_collection_rolesc Cs~|r |dr |d}nddi}i|d<|r"d||g}||d<n|}|D]}||p/i}|dd|d|<q(||fS) a3Build a summary dict for a role. Returns a simplified role arg spec containing only the role entry points and their short descriptions, and the role collection name (if applicable). :param role: The simple role name. :param collection: The collection containing the role (None or empty string if N/A). :param meta: dictionary with galaxy information (None or empty string if N/A). :param argspec: The complete role argspec data dict. :returns: A tuple with the FQCN role name and a summary dict. galaxy_info description UNDOCUMENTED entry_pointsr}r_short_description)rlrUkeys) r[r!r_rNargspecsummaryrep entry_specrBrBrC_build_summarys    zRoleMixin._build_summaryc Cs|r d||g}n|}i}||d<||d<d|vr#||||fSi|d<|D]}|dus5||krA||p:i} | |d|<q+t|ddkrNd}||fS)Nr}rTr_rirr)rUupdaterr) r[r!rTr_r entry_pointrdocrrrBrBrC _build_docs$     zRoleMixin._build_docTc Cs|}|}|s||}nt}|j|d}i}||BD][\}}} z ||| |} Wn tyM} ztd|t | fdi} WYd} ~ nd} ~ ww| || |} d| vrl|r_| dt d|| dfdq| ||| | \} }||| <q|S)aReturn a dict describing the listing of all roles with arg specs. :param role_paths: A tuple of one or more role paths. :returns: A dict indexed by role name, with 'collection' and 'entry_points' keys per role. Example return: results = { 'roleA': { 'collection': '', 'entry_points': { 'main': 'Short description for main' } }, 'a.b.c.roleB': { 'collection': 'a.b.c', 'entry_points': { 'main': 'Short description for main', 'alternate': 'Short description for alternate entry point' } 'x.y.z.roleB': { 'collection': 'x.y.z', 'entry_points': { 'main': 'Short description for main', } }, } )rz$No metadata for role (%s) due to: %sTNrirjzSkipping role (%s) due to: %s) _get_roles_path_get_collection_filterrxrorrhrmr;r=r rnwarningr)r[fail_on_errors roles_pathrrM collrolesresultr!r_rgrNrArrrrBrBrC_create_role_list2s0   zRoleMixin._create_role_listcCsn|}|j||d}|j|d}i}||BD]\}} } ||| | } ||| | | |\} } | r4| || <q|S)a :param role_names: A tuple of one or more role names. :param role_paths: A tuple of one or more role paths. :param entry_point: A role entry point name for filtering. :param fail_on_errors: When set to False, include errors in the JSON output instead of raising errors :returns: A dict indexed by role name, with 'collection', 'entry_points', and 'path' keys per role. )rt)rrxrrnr)r[ role_namesrrrrMrrr!r_rgrrrrBrBrC_create_role_docos  zRoleMixin._create_role_docN)NN)T)NT)__name__ __module__ __qualname____doc__CYAML_FILENAME_EXTENSIONSrfrkrerhrnrxrrrrrrBrBrBrCrEVs$  %* =rEcCs|ds t|}|S)N)httpz..) startswithr )urlrBrBrC_doclinks rcGs|D]I}|tvr|tvr|tjvrtd|tjr'|tvr&t||}q|tjvr2t||}q|tvr>t|t|}qdt||tdf}q|S)z$ add ascii formatting or delimiters z!Invalid format value supplied: %sz%s%s%sr.) ref_styleupperSTYLEr COLOR_CODESKeyErrorANSIBLE_NOCOLORNOCOLORr)stringargsstylerBrBrC_formats    rcsZeZdZdZdZdZedZedZ edZ edZ edZ ed Z ed Zed Zd Zed eZedeZedeZedeZedZedZedZdZedZedZedZedZfddZeddZeddZ e!dd Z"fd!d"Z#fd#d$Z$d%d&Z%d'd(Z&d)d*Z'ed+d,Z(ed-d.Z)d/d0Z*d1d2Z+d^d5d6Z,d7d8Z-ed9d:Z.fd;d<Z/ed=d>Z0ed?d@Z1edAdBZ2edCdDZ3edEdFZ4edGdHZ5dIdJZ6edKdLZ7ed_dMdNZ8edOdPZ9ed`dRdSZ:edadVdWZ;edbdXdYZZ?S)dDocCLIa displays information on modules installed in Ansible libraries. It displays a terse listing of plugins and their short descriptions, provides a printout of their DOCUMENTATION strings, and it can create a short "snippet" which can be pasted into a playbook. z ansible-doc) r*docuri version_addedversion_added_collectionrnow_date plainexamples returndocsr_ plugin_namez\bI\(([^)]+)\)z\bB\(([^)]+)\)z\bM\(([^)]+)\)z\bP\(([^#)]+)#([a-z]+)\)z\bL\(([^)]+), *([^)]+)\)z\bU\(([^)]+)\)z\bR\(([^)]+), *([^)]+)\)z\bC\(([^)]+)\)z\(((?:[^\\)]+|\\.)+)\)z\bOz\bVz\bEz\bRVz\bHORIZONTALLINE\bz\\(.)z%^([^.]+\.[^.]+\.[^#]+)#([a-z]+):(.*)$zignore:z .. note::z .. seealso::z:\w+?:`z .. \w+?::cstt||t|_dSr)superr__init__ro plugin_list)r[r __class__rBrCrs zDocCLI.__init__cCs tjd|d}d|dS)N\1`')r _UNESCAPEsubgroup)matcherr@rBrBrC_tty_ify_sem_simles zDocCLI._tty_ify_sem_simlec Cs*tjd|d}d}d|vr|dd\}}tj|}|r0|d}|d}|d}n|tjrD|t tjd}d}}nd}}d}d|vrV|dd\}}|dura|d|}|r|r|dvrkdnd }||d |}|d kr|dur|d |d }d|d|dSd|dS)Nrr=r~r:)r!r*playbook plugin r!, z entrypointrz' (of )r) rrrrr_FQCN_TYPE_PREFIX_REmatchr_IGNORE_MARKERr) rr@valuem plugin_fqcn plugin_type entrypoint plugin_suffixpluginrBrBrC_tty_ify_sem_complexs2       zDocCLI._tty_ify_sem_complexcCsR|jtdd|}|jtdd|}|jtdd|}|jd|}|jd|}|jtdd|}|jtdd|}|j td d |}|j |j |}|j |j |}|j|j |}|j|j |}|jd d |}|jd |}|jtdd|}|jd|}|jd|}t|jdd|}t|jdd|}|S)Nrr1r,r2z\1 <\2>z[\1]r3r7z`\1'r:z {0} z -------------z See also:zNote:boldrrcSstdt|ddS)N%srr8)rrrrrBrBrCsz DocCLI.tty_ify..cSs"d|dtt|ddfS)Nz%s <%s>rrr8)rrrrrBrBrCrs")_ITALICrr_BOLD_MODULE_URL_LINK_PLUGIN_REF_CONST_SEM_OPTION_NAMEr_SEM_OPTION_VALUEr_SEM_ENV_VARIABLE_SEM_RET_VALUE_RULERformat _RST_SEEALSO _RST_NOTE _RST_ROLES_RST_DIRECTIVESre)clsr@trBrBrCtty_ifys(zDocCLI.tty_ifyc s@d}tt|jdddt|jt|j|jjddddd |jjd d d d ddt t d|jjddddddd|jjdddt j tj ddtj dd|j}|jdd d!d"d#|jd$d%ddd&d'd(td|jd)d*ddd+d,|d|jd-d.ddd/d0|d|jd1ddd2d3d|jjd4ddd5d6ddS)7Nz[A supplied argument will be used for filtering, can be a namespace or full collection name.zplugin documentation toolzWSee man pages for Ansible CLI options or website for tutorials https://docs.ansible.com)descepilogr*Pluginr)nargshelpmetavarz-tz--typestorer*typezQChoose which plugin type (defaults to "module"). Available plugin types are : {0})actiondefaultdestrchoicesz-jz--json store_trueF json_formatzChange output into json format.)rrrrz-rz --roles-pathrT)pathsepz0The path to the directory containing your roles.)rrrrrz-ez --entry-pointrz#Select the entry point for role(s).)rrz-sz --snippet show_snippetz0Show playbook snippet for these plugin types: %srz-Fz --list_files list_fileszOShow plugin names and their source files without summaries (implies --list). %sz-lz--listlist_dirzList available plugins. %sz--metadata-dumpdumpzT**For internal use only** Dump json metadata for all entries, ignores other options.z--no-fail-on-errorsno_fail_on_errorsz}**For internal use only** Only used for --metadata-dump. Do not fail on errors. Report the error message in the JSON instead.)rr init_parseropt_helpadd_module_optionsparseradd_basedir_options add_argumentrTARGET_OPTIONSrDEFAULT_ROLES_PATH unfrack_pathPrependListActionadd_mutually_exclusive_grouprUSNIPPETS)r[ry exclusiverrBrCrsP         zDocCLI.init_parsercstt||}|jt_|Sr)rrpost_process_args verbosityr;)r[optionsrrBrCrNszDocCLI.post_process_argsc Cstdd|D}tj|d}g}g}tjdrot|D]L}t||}|d}|d dr_|dd kr_|d d vr_|dd d|d<d |}| d |||t ||fq!| d |||t ||fq!n[t|D]T}t ||} t | |kr| d|d } |d}|d dr| dr|dd d|d<d |}| d |||t | | fqu| d |||t | | fqut |dkr| d||t d |dS)Ncs|]}t|VqdSrrrIxrBrBrC Xz-DocCLI.display_plugin_list..rr}_ransibler)builtinlegacyz %-*s %-*.*s...)ansible.builtin.zansible.legacy.z DEPRECATED: )maxrr;columnsrCLIARGSsortedr rrrUappendrrrextendpager) r[resultsdisplace linelimitr@ deprecatedrfilenamepbreakrrBrBrCdisplay_plugin_listUs8   &        zDocCLI.display_plugin_listc Cst|}t}|D]}||dD]}||qq d}d}|r-tdd|D}tj||d}g} t|D]A}||drv| d|| d||d D]\}} t | |krj| d|d } | d ||| fqXq<| d |q.r(%s:z specs:Nr.z %-*s: %srr0)listrrorrr1r;r2r4r5itemsrrr7rU) r[ list_jsonrMentry_point_namesr!r max_role_len max_ep_lenr:r@rrBrBrC_display_available_roless.      zDocCLI._display_available_rolesc Cst|}g}|D]8}z"d||vr#td|||dfdWq |||||7}Wq tyB}ztd||dd}~wwtd|dS)NrizSkipping role '%s' due to: %sTzRole '%srQr0) r@rr;rget_role_man_textr rr7rU)r[ role_jsonrMr@r!rArBrBrC_display_role_docs  zDocCLI._display_role_doccCsttddS)Nr+zkeyword_desc.yml)rpkgutilget_datarBrBrBrC_list_keywordsszDocCLI._list_keywordsc Csi}t}|D]}|drd}n |dkrd}n|}zd||i}g|d<tD]l}|tvrAd|}t|}t||dt|<|t|j vr|d |d|vrt|j |} t| d rdi}t t| d d |d<| d su|d vrzd|d<nt| drd|d<nd|d<dD] } t| | || <qq(t|D] } || dur|| =q|||<Wqtt fy} ztd|t| ftjdkrttWYd} ~ qd} ~ ww|S)Nwith_loopasync async_valr applies_tozansible.playbook.%srprivateisarwhen)untilimplicittemplatestaticexplicit)aliaspriorityz+Skipping Invalid keyword '%s' specified: %sr~)rrLr PB_OBJECTS PB_LOADEDlower importlib import_modulegetattr fattributesr5rlrendswithr@rAttributeErrorr;rrr verboser>r?) rrddescskeyr"kdatapobj obj_class loaded_classfavisiblekrArBrBrC_get_keywords_docssX           zDocCLI._get_keywords_docscCsFd}ttjddkr!tjd}|D]}t|s td|q|S)NrrzGInvalid collection name (must be of the form namespace.collection): {0})rrr3ris_valid_collection_namer r)r[ry coll_namerBrBrCrs  zDocCLI._get_collection_filtercsi}i_t|}}jt|||dkr"|}|S|dkr4fddjD}|SddjD}t_ |S)Ndirr]csi|] }|j|dqS)r)pluginsrIrnr[rBrC sz(DocCLI._list_plugins..cSsi|]}|iqSrBrBrtrBrBrCrvs) rsr _prep_loaderrrr_get_plugin_list_descriptionsrror)r[rcontentr8loaderryrBrurC _list_plugins s  zDocCLI._list_pluginsFTc Cstt|}i}|D]}i}zt|||ttjddk\}} } } WnXty9} z tt | WYd} ~ q d} ~ wt yx} z4|sRddt | i||<WYd} ~ q t t d||t | f} |rjt| nt| WYd} ~ nd} ~ ww|s|sddi||<q t|||| | | }|szt|Wnt y} zddt | i||<WYd} ~ q d} ~ ww|||<q |S)Nr rriz:Missing documentation or could not parse documentation: %szC%s %s missing documentation (or could not parse documentation): %s zNo valid documentation foundz*Cannot serialize documentation as JSON: %s)rrwrrrr3r r;rr rmr=r>r?r _combine_plugin_docr)r[rnamesfail_okrrz plugin_docsrrrrmetadatarAmsgdocsrBrBrC_get_plugins_docssJ &         zDocCLI._get_plugins_docscCsVtjd}tjddur)tjtjdd}tj|r!|f|}|tjdf}|S)ao Add any 'roles' subdir in playbook dir to the roles search path. And as a last resort, add the playbook dir itself. Order being: - 'roles' subdir of playbook dir - DEFAULT_ROLES_PATH (default in cliargs) - playbook dir (basedir) NOTE: This matches logic in RoleDefinition._load_role_path() method. rbasedirNrM)rr3rSrTrUrp)r[rsubdirrBrBrCrHs   zDocCLI._get_roles_pathcCsbttd|}tjddur|jtjdddtjdr,tjdD] }|r+||q"d|_|S)z' return a plugint type specific loader %s_loaderrNT) with_subdir module_path)ra plugin_loaderrr3 add_directory_paths)rrzrTrBrBrCrwYs  zDocCLI._prep_loaderc stt|tjd}tjd}tjdptjd}tjdp&tjd}tjdr/d}n tjdr7d}nd}i}|r@|t_|tvrJt d |tjdrt}i|d <|D]O}t tjd  } |d kr}|j | d } |j | tjd| d |d |<qW|dkrt} t| |d |<qW||d} |j|| |dv| d|d |<qWnQ|r|dkrt}nF|d kr|j dd }n;|||}n4ttjddkrt d|dkrttjd}n|d kr| tjdtjd}n ||tjd}|rt|dSg} |tjvr|r|r||ntjdre|tvr*tddt|D]5\}}z t|||d}Wnty\}ztd|t |WYd}~q.d}~ww| !|q.nV|D](\}}t"|||d|d|d|d}|r| !|qitd|qin(|d krtjdr|r|#|n|r|$|n |rt%t&|} | rt'd| dS) Nrrr rrrr]rrz)Unknown or undocumentable plugin type: %sallrr!)rrr")testfilter)r~rFrrzEMissing name(s), incorrect options passed for detailed documentation.r z>Snippets are only available for the following plugin types: %srrz,Unable to construct a snippet for '{0}': {1}examplesreturnrz.No valid documentation was retrieved from '%s'r)(rrrunrr3r^rplaybook_pathsrr boolrrrrLror{rrrDrDOCUMENTABLE_PLUGINSr>rr rUrAformat_snippet ValueErrorr;rrrr5format_plugin_docrFrIr _dump_yamlr7)r[rrdo_jsonlistingryrptypesptypeno_failrMr} plugin_namesr@rdoc_datatextretrArrBrCrls      $    +            z DocCLI.runcCs>ttd|}|}i}|D] }|t|qt|S)Nr)rar_get_paths_with_contextrrr4r)rrzpathsrs path_contextrBrBrCget_all_plugins_of_types  zDocCLI.get_all_plugins_of_typecCsttd|}|j|dddd}|jstd|||j}|j}zt|t t j ddk||d\}}}}Wnt yLt ttd |||fw|durSdSt|t|||j|d d |d d d S)Nrz.pyT)mod_typeignore_deprecated check_aliasesz$unable to load {0} plugin named {1} r r)recollection_namerzM%s %s at %s has a documentation formatting error or is missing documentation.rUNKNOWNr)name namespacerr)rarfind_plugin_with_contextresolvedr rplugin_resolved_pathplugin_resolved_collectionrrrr3rmr;r=r>r?dictrnamespace_from_plugin_filepath package_pathrl)rrrzrr<rr__rBrBrCget_plugin_metadatas,   zDocCLI.get_plugin_metadatacCs`|ds |d7}||d}tj|d}||ddd}|dd}|dkr.d}|S)N/rrrz/_r})rcreplacerSrTsplitextrsplitstrip)filepathrrrel_pathextension_freenamespace_onlyclean_nsrBrBrCrs   z%DocCLI.namespace_from_plugin_filepathcCs0|dkr|tvr d|d<nd|d<||||dS)Nr*T has_actionF)rrrr)r)rrrrrrrBrBrCr| s  zDocCLI._combine_plugin_doccCsb|dkr|didrtd|g}|dkrt|}nd|vr't|}|dd|S)z9 return heavily commented plugin use to insert into play r(r!rzThe {0} inventory plugin does not take YAML type config source that can be used with the "auto" plugin so a snippet cannot be created.r)rr0)rlrr_do_lookup_snippet_do_yaml_snippetr5rU)rrrr@rBrBrCrs   zDocCLI.format_snippetc Cst|d}||d<||d<||d<z t|||}W|Sty9}ztttd|t|f|dd}~ww)Nr_rrrz5Unable to retrieve documentation from '%s' due to: %srQ) r get_man_textrmr;r=r>r?r r ) rrrrrrrr@rArBrBrCr+s zDocCLI.format_plugin_docc Cs(i}|jD]}d}tt|j|d}d}zt|}Wnty2}z|}WYd}~nd}~ww|duro|dd}|||j} t j D]%} | | } z | rYt| }WqItyn}z|}WYd}~qId}~ww|r{t d||fq|rt|tsd} n|dd} | ||<q|S)Nrr}r)z+%s has a documentation formatting error: %srrzINVALID SHORT DESCRIPTION)rsrrr rrmr with_namesuffixrDOC_EXTENSIONS with_suffixrVr;r isinstancerrlr) r[rzrfrrr<docerrorrAbasebasefile extensiondocfilerrBrBrCrxBs@    z$DocCLI._get_plugin_list_descriptionscCs@g}|jddD]}t|dd}||vr||qtj|S)z; Returns a string suitable for printing of the search path F)subdirsrzr{) _get_pathsrr5rSr rU)finderretirBrBrC print_pathsis   zDocCLI.print_pathscCst||dtddS)Nz'')default_flow_style default_styleDumperr0)rrrstrip)struct flow_stylerBrBrCruszDocCLI._dump_yamlcs$tdfdd|dDS)Nr0csg|]}|qSrBrB)rIlineindentrBrCrJ{rKz(DocCLI._indent_lines..)rrrUr)r@rrBrrC _indent_linesys$zDocCLI._indent_linesNcCs2|dkr d}|dkr dS|rd||f}d|fS)Nansible.builtin ansible-core historicalz%s of %sz version %srB)rrrBrBrC_format_version_added}s  zDocCLI._format_version_addedrrc Ksvg}|dD].}tj||f|d||dddd|}|r,|d|r,||d}|||}d}qd|S)Nz rFT)initial_indentsubsequent_indentbreak_on_hyphensbreak_long_wordsdrop_whitespacerr0)rtextwrapfillrr5rU) r@limitrr initial_extrakwargsr paragraphwrappedrBrBrC warp_fills   zDocCLI.warp_fillc CsBt|D]}t||}|dd} t| tstd| d} d} | r5tjr)d} d|| t|dd f} ntjr:d } d|| t|d f} d |vrLtd | ddt t |t |t |d} |dt |d} | | }t |d rt |d dD]<\}}t|tstd||t|f|dkr| | tjt||| |t | dq}| tjt||||dq}n)t|d tstd|t|d f| | tjt|d || |t | d|d =g}dD]}||vr| |||fq| s |s d|vr d|d<i}dD]I}||vrW||rWdd||D||<tjD],}||D]$}tjdkrKd|vrKt|d|dd|d<||vrS||=q0q*qd |vr|d rg|d <|d D]%}d!|vr|d  |d"d#|d"d$d d%qk|d  |qk|d =|r| ttd&|i||dd}|d'd}t|D]8}|d$rqt ||r| td(|tj||d)d*f|q| tt|||i|q|r|s| d+|t||f|D]\}}| d,||ft||||d||qqdS)-NrequiredFz8Incorrect value for 'Required', a boolean is needed.: %s rr%s%s %srred-r4rzCAll (sub-)options and return values must have a 'description' fieldrrr~rz8Expected string in description of %s at index %s, got %s)rrrrrz,Expected string in description of %s, got %s)r! suboptionscontainsspecr)enviniyamlvarsr"cSsg|]}t|qSrB)r)rIitemrBrBrCrJrKz%DocCLI.add_fields..rrversion_added_collecitonradded_inclioptionrz--%sr*)rrset_viar%s: %sT)rz%sadded in: %sz%s%s:)r4rpoprrr rrrr5r1rr enumeraterrrrrIGNOREr;r rrlrrrr add_fields)r@fieldsr opt_indent return_values base_indentmanooptr opt_leadinrg inline_indent extra_indent sub_indent entry_idxrwrsubkeyconfconfigignorerrrrrnsubdatarBrBrCrs     "            ,    ,$  zDocCLI.add_fieldsc Csg}d}tjd}ttjt|d}|dt|d|df|dD]=}|d|}d} |d r=d |d } |d|d t|d| f|d|d rt|d trd|d } n|d g} | D]} |d t j t | |||dqk|d|dr|tdddt j rdndt ||d|||ddrtjd|d|dddd|d|tdd|dD]-} |d|t j t td| d|d ||d|t t |d| |q|d=d!D]c} | |vr q|dt|| tr4|d"| t j t || |t| d#|d$fqt|| ttfrP|d"| d%|| fq|t t | || idqq&|S)&aGenerate text for the supplied role suitable for display. This is similar to get_man_text(), but roles are different enough that we have a separate method for formatting their display. :param role: The role name. :param role_json: The JSON for the given role as returned from _create_role_doc(). :returns: A array of text suitable for displaying to screen. z 皙?Fz> ROLE: %s (%s)r,rTrrrz- %szENTRY POINT: %s %srrrr!Optionsr (%s indicates it is required):rr attributesFz The role z's argument spec z contains the key "attributes", which will not be displayed by ansible-doc in the future. This was unintentionally allowed when plugin attributes were added, but the feature does not map well to role argument specs.z2.20r)versionr ATTRIBUTES:r?r1)authorrrrr)r;r2r1intr5rrlrr@rrrrrrrr;rrrrrrtuplerU) r[r!rHr@rpadrrrrrfrnrBrBrCrGsf         $  "   ""  $( zDocCLI.get_role_man_textc Cs& t|}tjtjdft_d}d}g}tjd}ttjt|d}| d| t | dd| d ft |d trE| d }n| d g}| d |D]} | tjt| |||d qRtjd kryt| dd| dd|d<|ddr| t dddt |dtrd|dvr| d| dn+d|dvrd|dvr|dd|dd<| d| dn | d| d| ddr| d | t ddd|d dr | d | t d!dd"tjrd#nd$tj|| d ||tjd kd%|d&drY| d | t d'd|d&D].} | d | tjtt d(| d)|d*||d | tt|d&| |q'|d&=|d+dr| d | t d,d|d+D]} | tjt| |d*|dd-d.|d qq|d+=|d/drv| d | t d0d|d/D]} d1| vr&| tjtd2| d1|d*|dd-d.|d | d } | dur| d1d3rd4| d1} | dur| tjt| |d*|d5|d5d | d1d3r$d6| d1d7d8d9}| tjtt||d*|d5|d qd:| vrd;| vr| d;d| d;|| d:f|d*|dd-d.|d | d } | durz| d:d3rzd?| d:| d;|f} | dur| tjt| |d*|d5|d5d | d:d3rd@| d:d7d8d9| d;f}| tjtt||d*|d5|d qdA| vrdB| vrd | vr| tjt| dA|d*|dd-d.|d | tjt| d |d*|d5|d5d | tjt| dB|d*|d5|d5d qdC| vrqd | vrq| tjtdD| dC|d*|dd-d.|d | tjt| d |d*|d5|d5d | tjttdE| dC|d*|d5|d5d q|d/=|dFdr| d dG| dF}| t dHddItjt||dJd|d t|D]s} || r| tjvrq| d t | d}t || t r| dK|tjt|| |t!| d9|dLfn1t || tt"fr| dK|dG|| fn| dM|tt|| dNt!| d9|| =q|dOdrd| d | t dPdt |dOt rA| | dO#n#z| t$| dOd9ddQWnt%yc}zt&dR|dSd}~ww|dTdr| d | t dUdtj|| dT||dVtjd kdW| dXdX|S)YNrz rrrz > %s %s (%s)rrr<rrrrrrrrrr;Fz DEPRECATED: r9removed_at_datezg Reason: %(why)s Will be removed in a release after %(removed_at_date)s Alternatives: %(alternative)sr removed_inz[ Reason: %(why)s Will be removed in: Ansible %(removed_in)s Alternatives: %(alternative)srrz * note:z/ This module has a corresponding action plugin.r!OPTIONSrrr)r rrr?r1rnoteszNOTES:z* seealsoz SEE ALSO:r*z Module %sr/z,The official documentation on the %s module.z zcollections/%s_module.htmlr}rrrr)r*r!rrz*The official documentation on the %s %s%s.zcollections/%s_%s.htmlrlinkrefzAnsible documentation [%s]z/#stq=%s&stp=1 requirementsrz REQUIREMENTS:z%s rr z%s: rrz EXAMPLES:)rrz Unable to parse examples sectionrQrzRETURN VALUES:T)rr r0)'rrrrr3r;r2r1r!r5rrrrr@rrr rrlrrrrrrrrr titlerUr4rrr"rrrmr )rrrrr r@r#rrfrrnnoterr relative_urlrreqheaderrArBrBrCrGs& *            "   "$        &    "  60    "  zDocCLI.get_man_text)FT)Fr)rrr)FrF)rr)@rrrrrrrcompilerrrrrrrr_SEM_PARAMETER_STRINGrrrrrrrrrrrrr staticmethodrr classmethodrrrr>rFrIrLrorr{rrrwrrrrr|rrrxrrrrrrrGr __classcell__rBrBrrCrs                    ! 6/"  C +  l      '      gJrc Cs`g}t|d}|d}|r|d||d|n|d|d|dd}d |d }tj|}t|d D]j}|d |}t |d t rZt|d } n td |d } |dd} t | t sut d| d|}|r| rd| } |d|tj| ||dfqC| rd} n|dd} |d|| tj| ||ddfqC|S)Nrr*z - name: %sz %s:z# %s:rrz# rr!rrrF7Incorrect value for 'Required', a boolean is needed: %sr?z (required) %sz %-20s # %sr z (required)rNonez %s %-9s # %sr~)r max_lines)rrrlr5rjustr;r2r4rrrrUrrr) rr@mdescr*r#subdentrr r rrrrBrBrCrs8        $rc Csg}d|d|d}g}t|dD]Y}|d|}|d||dd|dd f|d vr<|d |7}q|d d }t|tsMtd||rRd}n|dd}|ddvrh|d||f7}q|d||f7}q|d7}|r|||d |||S)Nz lookup('%s', rrr!z # %s(%s): %srrrr)_terms_raw_listz< %s >rFr9z rr:)rstrz , %s='%s'z, %s=%sr)rlr4rr5rrrr6)rr@snippetcommentr r rrrBrBrCrs0 $        rcCst|dSr)r cli_executor)rrBrBrCrG6srG__main__r)T __future__r ansible.clirr_rJrSos.pathrrr>ansible.plugins.loaderrsrzrpathlibrr+rrransible.cli.argumentsrransible.collections.listransible.errorsr r r r +ansible.module_utils.common.text.convertersr r'ansible.module_utils.common.collectionsr ansible.module_utils.common.jsonr ansible.module_utils.common.yamlransible.module_utils.sixransible.parsing.plugin_docsransible.parsing.utils.yamlransible.parsing.yaml.dumperransible.plugins.listrrransible.utils.collection_loaderrr2ansible.utils.collection_loader._collection_finderransible.utils.colorransible.utils.displayransible.utils.plugin_docsrrr r;rrr\r]rrrrrDobjectrErrrrrrGrrBrBrBrCs                   3D- &