관리-도구
편집 파일: doc.cpython-39.opt-1.pyc
a �)g� � @ s d dl mZmZmZ eZd dlmZ d dlZd dl Z d dl Z d dl Z d dl Z d dl Z d dlm mZ d dlmZ d dlmZ d dlmZ d dlmZ d dlm Z d d l m Z m Z m Z m!Z! d d l"m#Z#m$Z$ d d l%m&Z& d d l'm(Z( d d l)m*Z* d dl+m,Z, d dl-m.Z. d dl/m0Z0 d dl1m2Z2 d dl3m4Z4 d dl5m6Z6 d dlm7Z7m8Z8 d dl9m:Z:m;Z; d dl<m=Z= d dl>m?Z? d dl@mAZAmBZBmCZC e?� ZDejEd ZFg d�ZGi ZHg d�ZId+d d �ZJd d � ZKG d d!� d!eL�ZMG d"d#� d#eeM�ZNd$d%� ZOd&d'� ZPd,d(d)�ZQeRd*k�reQ� dS )-� )�absolute_import�division�print_function)�CLIN)�Path)� constants)�context)�option_helpers)�list_collection_dirs)� AnsibleError�AnsibleOptionsError�AnsibleParserError�AnsiblePluginNotFound)� to_native�to_text)� is_sequence)� json_dump)� yaml_dump)� importlib)� string_types)� read_docstub)� from_yaml)� AnsibleDumper)� list_plugins)� action_loader�fragment_loader)�AnsibleCollectionConfig�AnsibleCollectionRef)� _get_collection_name_from_path)�Display)�get_plugin_docs� get_docstring�get_versioned_doclink)�role�keyword)ZPlayZRoleZBlockZTask)� inventory�lookup�modulec C s" t jddd� | �t||�� d S )NzJadd_collection_plugins method, use ansible.plugins.list functions instead.�2.17��version)�display� deprecated�updater )� plugin_list� plugin_type� coll_filter� r1 �3/usr/lib/python3.9/site-packages/ansible/cli/doc.py�add_collection_plugins6 s r3 c C sZ zt � t| �� W nB tyT } z*t �t�� � tdt|� ��W Y d }~n d }~0 0 d S )NzXWe could not convert all the documentation into JSON as there was a conversion issue: %s)r+ r � TypeError�vvv� traceback� format_excr r )�text�er1 r1 r2 �jdump; s r: c @ sr e Zd ZdZdd� ejD �dd� ejD � Zddd�Zddd �Zdd d �Z d d � Z dd� Z ddd�Z ddd�Z dS )� RoleMixinz�A mixin containing all methods relevant to role argument specification functionality. Note: The methods for actual display of role data are not present here. c C s g | ] }d | �qS )�argument_specsr1 ��.0r9 r1 r1 r2 � <listcomp>K � zRoleMixin.<listcomp>c C s g | ] }d | �qS )�mainr1 r= r1 r1 r2 r? K r@ Nc C s |rt j�|d|d�}n |r,t j�|d�}n td| ��d}| jD ]&}t j�||�}t j�|�rB|} qjqB|du rvi S zXt|d��:}t|�� |d�} | du r�i } | � di �W d � W S 1 s�0 Y W nB t t f�y } z$t d|t | �f | d ��W Y d} ~ n d} ~ 0 0 dS ) aC Load 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 collection_path: Path to the collection containing the role. This will be None for standard roles. :param str role_path: Path to the standard role. This will be None for collection 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. �roles�metaz7A path is required to load argument specs for role '%s'N�r)� file_namer< z8An error occurred while trying to read the file '%s': %s�Zorig_exc)�os�path�joinr �ROLE_ARGSPEC_FILES�exists�openr �read�get�IOError�OSErrorr r ) �selfZ role_name�collection_path� role_path� meta_pathrH �specfile� full_path�f�datar9 r1 r1 r2 � _load_argspecM s* 0zRoleMixin._load_argspecc C s� t � }t � }|D ]�}tj�|�s"qt�|�D ]n}tj�||�}| jD ]T}tj�|d|�} tj�| �rD|du st||v r�||vr�|�||f� |�|� q,qDq,q|S )a� Find 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 rC N) �setrG rH �isdir�listdirrI rJ rK �add) rQ Z role_paths� name_filters�foundZ found_namesrH �entryrS rU rV r1 r1 r2 �_find_all_normal_roles{ s z RoleMixin._find_all_normal_rolesc C s t � }t|d�}|D � ]�}t|dd�}t|�}tj�|d�}tj�|�rt�|�D ]�} | j D ]�} tj�|| d| �} tj�| �r\|du r�|� | ||f� np|D ]j} t | � d��dkr�| � d�\} }}d�| |g�|kr�| |kr�|� | ||f� q�| | kr�|� | ||f� q� qRq\qRq|S ) a� Find 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 string 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 )r0 �surrogate_or_strict��errorsrB rC N�.� ) rZ r r r rG rH rI rK r\ rJ r] �len�split)rQ r^ �collection_filterr_ Z b_colldirs�b_pathrH ZcollnameZ roles_dirr` rU rV �fqcn�ns�colr# r1 r1 r2 �_find_all_collection_roles� s, z$RoleMixin._find_all_collection_rolesc C sb |rd� ||g�}n|}i }||d< i |d< |�� D ]$}|| pBi }|�dd�|d |< q4||fS )a� Build 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 argspec: The complete role argspec data dict. :returns: A tuple with the FQCN role name and a summary dict. re � collection� entry_points�short_description� )rI �keysrN )rQ r# ro �argspecrk �summary�ep� entry_specr1 r1 r2 �_build_summary� s zRoleMixin._build_summaryc C s� |rd� ||g�}n|}i }||d< ||d< i |d< |�� D ],}|d u sP||kr<|| pZi } | |d |< q<t|d �� �dkr�d }||fS )Nre rH ro rp r )rI rs rg ) rQ r# rH ro rt � entry_pointrk �docrv rw r1 r1 r2 � _build_doc� s zRoleMixin._build_docTc C s: | � � }| �� }|s | �|�}ng }| j|d�}i }|D ]t\}}z,| j||d�} | �|d| �\} } | || < W q8 ty� } z&|r�� ddt| � i||< W Y d} ~ q8d} ~ 0 0 q8|D ]�\}} }z,| j||d�} | �|| | �\} } | || < W q� t�y2 } z0|�r� ddt| � i|d| |f < W Y d} ~ q�d} ~ 0 0 q�|S ) a� Return 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', } }, } )ri �rS rr �errorz*Error while loading role argument spec: %sN�rR �%s.%s)�_get_roles_path�_get_collection_filterra rn rY rx � Exceptionr )rQ �fail_on_errors� roles_pathri rB � collroles�resultr# rS rt rk ru r9 ro rR r1 r1 r2 �_create_role_list� s8 � �(zRoleMixin._create_role_listc C s. | � � }| j||d�}| j|d�}i }|D ]v\}} z4| j|| d�} | �|| d| |�\} } | rd| || < W q* ty� } z ddt| � i||< W Y d} ~ q*d} ~ 0 0 q*|D ]�\}}}z4| j||d�} | �|||| |�\} } | r�| || < W q� t�y& } z(ddt| � i|d||f < W Y d} ~ q�d} ~ 0 0 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. )r^ r| rr r} z Error while processing role: %sNr~ r )r� ra rn rY r{ r� r )rQ Z role_namesry r� r� rB r� r� r# rS rt rk rz r9 ro rR r1 r1 r2 �_create_role_doc5 s. � �(zRoleMixin._create_role_doc)NN)N)NN)T)NT)�__name__� __module__� __qualname__�__doc__�CZYAML_FILENAME_EXTENSIONSrJ rY ra rn rx r{ r� r� r1 r1 r1 r2 r; C s . " * Br; c s� e Zd ZdZdZdZe�d�Ze�d�Z e�d�Z e�d�Z e�d�Z e�d �Z e�d �Ze�d �Ze�d �Ze�d �Ze�d�Ze�d�Z� fdd�ZedPdd��Zedd� �Z� fdd�Z� fdd�Zdd � Zd d � Zd d � Z e d!d"� �Z e d#d$� �Z d%d&� Z d'd(� Z!dQd+d,�Z"d-d.� Z#e d/d0� �Z$� fd1d2�Z%e d3d4� �Z&e d5d6� �Z'e d7d8� �Z(e d9d:� �Z)e d;d<� �Z*e d=d>� �Z+d?d@� Z,e dAdB� �Z-e dRdCdD��Z.e dEdF� �Z/e dSdGdH��Z0e dTdJdK��Z1dLdM� Z2e dUdNdO��Z3� Z4S )V�DocCLIa 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' Zdocuri� version_added�version_added_collectionrq Znow_date� plainexamples� returndocsro z\bI\(([^)]+)\)z\bB\(([^)]+)\)z\bM\(([^)]+)\)z\bL\(([^)]+), *([^)]+)\)z\bU\(([^)]+)\)z\bR\(([^)]+), *([^)]+)\)z\bC\(([^)]+)\)z\bHORIZONTALLINE\bz .. note::z .. seealso::z:\w+?:`z .. \w+?::c s t t| ��|� t� | _d S �N)�superr� �__init__rZ r. )rQ �args�� __class__r1 r2 r� y s zDocCLI.__init__Nc C s t jddd� t|||g��� S )Nz^find_plugins method as it is incomplete/incorrect. use ansible.plugins.list functions instead.r( r) )r+ r, r rs )�clsrH Zinternalr/ r0 r1 r1 r2 � find_plugins~ s zDocCLI.find_pluginsc C s� | j �d|�}| j�d|�}| j�d|�}| j�d|�}| j�d|�}| j�d|�}| j�d|�}| j�d� d�|�}| j �d|�}| j �d |�}| j �d |�}| j �d |�}|S ) Nz`\1'z*\1*z[\1]z\1z\1 <\2>z {0} z -------------z See also:zNote:�`rr )�_ITALIC�sub�_BOLD�_MODULE�_URL�_LINK�_REF�_CONST�_RULER�format� _RST_SEEALSO� _RST_NOTE� _RST_ROLES�_RST_DIRECTIVES)r� r8 �tr1 r1 r2 �tty_ify� s zDocCLI.tty_ifyc s@ d}t t| �jddd� t�| j� t�| j� | jjddddd � | jjd d d d dd�t �t d� | jjddddddd� | jjdddt j tj dd �tj d d � | j�� }|jd d d!d"d#� |jd$d%ddd&d'd(�t� d� |jd)d*ddd+d,| d� |jd-d.ddd/d0| d� |jd1ddd2d3d� | jjd4ddd5d6d� d S )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)�desc�epilogr� �*ZPlugin�plugin)�nargs�help�metavarz-tz--type�storer' �typezQChoose which plugin type (defaults to "module"). Available plugin types are : {0})�action�default�destr� �choicesz-jz--json� store_trueF� json_formatz Change output into json format.)r� r� r� r� z-rz --roles-pathr� T)�pathsepz0The path to the directory containing your roles.)r� r� r� r� r� z-ez --entry-pointry z#Select the entry point for role(s).)r� r� z-sz --snippet� show_snippetz0Show playbook snippet for these plugin types: %s�, z-Fz --list_files� list_fileszOShow plugin names and their source files without summaries (implies --list). %sz-lz--list�list_dirzList available plugins. %sz--metadata-dump�dumpzT**For internal use only** Dump json metadata for all entries, ignores other options.z--no-fail-on-errors�no_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.)r� r� � init_parser�opt_helpZadd_module_options�parserZadd_basedir_options� add_argumentr� �TARGET_OPTIONSr� ZDEFAULT_ROLES_PATHZ unfrack_pathZPrependListAction� add_mutually_exclusive_grouprI �SNIPPETS)rQ r0 Z exclusiver� r1 r2 r� � sR � ��� � � ��� ��zDocCLI.init_parserc s t t| ��|�}|jt_|S r� )r� r� �post_process_args� verbosityr+ )rQ �optionsr� r1 r2 r� � s zDocCLI.post_process_argsc C s� t dd� |�� D ��}tj| d }g }g }tjd r�t|�� �D ]�}t|| �}|�d�}|d � d�r�|d d kr�|d d v r�|d d d � |d< d� |�}|� d |||t |�|f � qB|� d |||t |�|f � qBn�t|�� �D ]�}t �|| �} t | �|k�r| d |� d } |�d�}|d � d��rp|d d d � |d< d� |�}|� d |||t | �| f � q�|� d |||t | �| f � q�t |�dk�r�|� d� |�|� t �d� |�� d S )Nc s s | ]}t |�V qd S r� �rg �r> �xr1 r1 r2 � <genexpr>� r@ z-DocCLI.display_plugin_list.<locals>.<genexpr>� r� re ����_r �ansible� )Zbuiltin�legacyz %-*s %-*.*s�...z DEPRECATED:� )�maxrs r+ �columnsr �CLIARGS�sortedr rh � startswithrI �appendrg r� r� �extend�pager) rQ �resultsZdisplace� linelimitr8 r, r� �filenameZpbreakr� r1 r1 r2 �display_plugin_list� s6 & zDocCLI.display_plugin_listc C s� t |�� �}t� }|D ]$}|| d �� D ]}|�|� q*qd}d}|rZtdd� |D ��}|rptdd� |D ��}tj| | d }g } t|�D ]R}|| d �� D ]<\}} t | �|kr�| d|� d } | � d ||||| f � q�q�t � d � | �� dS ) z�Display all roles we can find with a valid argument specification. Output is: fqcn role name, entry point, short description rp r c s s | ]}t |�V qd S r� r� r� r1 r1 r2 r� r@ z2DocCLI._display_available_roles.<locals>.<genexpr>c s s | ]}t |�V qd S r� r� r� r1 r1 r2 r� r@ r� Nr� z %-*s %-*s %sr� )�listrs rZ r] r� r+ r� r� �itemsrg r� r� r� rI ) rQ Z list_jsonrB Zentry_point_namesr# ry Z max_role_lenZ max_ep_lenr� r8 r� r1 r1 r2 �_display_available_roles s, � z DocCLI._display_available_rolesc C sB t |�� �}g }|D ]}|| �||| �7 }qt�d�|�� d S )Nr� )r� rs �get_role_man_textr� r� rI )rQ � role_jsonrB r8 r# r1 r1 r2 �_display_role_doc! s zDocCLI._display_role_docc C s t t�dd��S )Nr� zkeyword_desc.yml)r �pkgutil�get_datar1 r1 r1 r2 �_list_keywords* s zDocCLI._list_keywordsc C s� i }t �� }| D �]�}|�d�r&d}n|dkr4d}n|}�z*d|| i}g |d< tD ]�}|tvr�d|�� }t�|�}t||d �t|< |t| j v rT|d � |� d|vrTt| j � |�} t| d �r�i }t �t| d d �|d< |� d �s�|d v r�d|d< n t| d��rd|d< nd|d< dD ]} t| | �|| < �qqTt|�� �D ]} || d u �r>|| = �q>|||< W q tt f�y� } z<t�d|t| �f � tjdk�r�t�t�� � W Y d } ~ qd } ~ 0 0 q|S )NZwith_Zloop�asyncZ async_val� descriptionZ applies_tozansible.playbook.%sr� ZprivateZisa�stringZwhen)ZuntilZimplicit�templateZstaticZexplicit)�alias�priorityz+Skipping Invalid keyword '%s' specified: %srf )r� r� r� � PB_OBJECTS� PB_LOADED�lowerr � import_module�getattrZ fattributesr� rN �KeyError�endswithr� rs �AttributeErrorr+ �warningr r� �verboser6 r7 ) rs rX �descs�keyr$ ZkdataZpobjZ obj_classZ loaded_class�faZvisible�kr9 r1 r1 r2 �_get_keywords_docs. sP &zDocCLI._get_keywords_docsc C s\ d }t tjd �dkrXtjd d }t�|�s>td�|���nt tjd �dkrXtd��|S )Nr� r� r zGInvalid collection name (must be of the form namespace.collection): {0}z-Only a single collection filter is supported.)rg r r� r Zis_valid_collection_namer r� r )rQ r0 r1 r1 r2 r� r s z DocCLI._get_collection_filterc s� i }i � _ t�|�}� �� }� j �t||�� |dkrB� �|�}n>|dkrd� fdd�� j �� D �}n dd� � j �� D �}t� � _ |S )N�dir�filesc s i | ]}|� j | d �qS )r )�plugins�r> r �rQ r1 r2 � <dictcomp>� r@ z(DocCLI._list_plugins.<locals>.<dictcomp>c S s i | ] }|i �qS r1 r1 r r1 r1 r2 r � r@ ) r r� � _prep_loaderr� r- r � _get_plugin_list_descriptionsrs rZ r. )rQ r/ �contentr� �loaderr0 r1 r r2 � _list_plugins~ s zDocCLI._list_pluginsFTc C s� t �|�}i }|D �]z}i }z&t|||ttjd dk�\}} } } W n� ty� } z&t�t | �� W Y d } ~ qW Y d } ~ n�d } ~ 0 t y� } zh|s�ddt | � i||< W Y d } ~ qt� t � � � d||t | �f } |r�t�| � nt| ��W Y d } ~ n d } ~ 0 0 |�s|sddi||< qt �|||| | | �}|�s�z t|� W nF t �y� } z,ddt | � i||< W Y d } ~ qW Y d } ~ n d } ~ 0 0 |||< q|S )Nr� r r} z:Missing documentation or could not parse documentation: %szC%s %s missing documentation (or could not parse documentation): %s z No valid documentation foundz*Cannot serialize documentation as JSON: %s)r� r r r r r� r r+ r� r r� r5 r6 r7 r �_combine_plugin_docr )rQ r/ �names�fail_okr� r Z plugin_docsr� rz r� r� �metadatar9 �msg�docsr1 r1 r2 �_get_plugins_docs� s> & " zDocCLI._get_plugins_docsc C sV t jd }t jd durRtj�t jd d�}tj�|�rB|f| }|t jd f }|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. r� �basedirNrB )r r� rG rH rI r[ )rQ r� Zsubdirr1 r1 r2 r� � s zDocCLI._get_roles_pathc C sb t td| �}tjd dur0|jtjd dd� tjd rXtjd D ]}|rD|�|� qDd|_|S )z' return a plugint type specific loader � %s_loaderr NT)Z with_subdirZ module_path)r� � plugin_loaderr r� Z add_directoryZ_paths)r/ r rH r1 r1 r2 r � s zDocCLI._prep_loaderc s� t t| ��� tjd }tjd �� }tjd p8tjd }tjd pLtjd }tjd r^d}ntjd rnd}nd }i }|r�|t_|tvr�t d | ��tjd �rTt}i |d < |D ]�}t tjd �} |d kr�| j | d �} | j | � � tjd | d �|d |< q�|dk�r&t�� } t�| � � �|d |< q�| �|d �} | j|| |dv | d�|d |< q�n�|�r�|dk�rnt�� }n |d k�r�| � � }n | �||�}nnttjd �dk�r�t d��|dk�r�t�tjd �}n6|d k�r�| � tjd tjd �}n| �|tjd �}|�rt|� �n�g } |tjv �r.|�r8|�r8| �|� n�tjd �r�|tv�r`tdd�t� ��|�� D ]h\}}zt�|||d �}W n< t �y� } z"t � d� |t |��� W Y d }~nd }~0 0 | �!|� �qhnX|�� D ]N\}}t�"|||d |d |d |d �}|�r| �!|� nt � d | � �q�nP|d k�rhtjd �rV|�rV| �#|� n|�r~| �$|� n|�r~t�%t�&|��} | �r�t�'d �| �� dS ) Nr r� r� r� r� r� r r z)Unknown or undocumentable plugin type: %s�allr� r# )r� ry r$ )�test�filter)r r� r� r zEMissing name(s), incorrect options passed for detailed documentation.r� z>Snippets are only available for the following plugin types: %sr� rz z,Unable to construct a snippet for '{0}': {1}�examples�returnr z.No valid documentation was retrieved from '%s'rr )(r� r� �runr r� r� r Zplaybook_pathsr� r �boolr� r� rs r� r r r rg r: r� �DOCUMENTABLE_PLUGINSr� r� r rI r� �format_snippet� ValueErrorr+ r� r� r r� �format_plugin_docr� r� r� � _dump_yamlr� )rQ r r/ Zdo_jsonZlistingr r ZptypesZptypeZno_failrB r Z plugin_namesr8 r� Zdoc_dataZtextretr9 r� r1 r2 r � s� $ " �� � z DocCLI.runc C s> t td| �}|�� }i }|D ]}|�t| �� q t|�� �S )Nr )r� r Z_get_paths_with_contextr- r r� rs )r/ r �pathsr Z path_contextr1 r1 r2 �get_all_plugins_of_typeM s z DocCLI.get_all_plugins_of_typec C s� t td| �}|j|dddd�}|js6td�| |���|j}|j}z(t|t t j d dk|| d�\}}}}W n2 t y� t �t�� � td | ||f ��Y n0 |d u r�d S t|t�|||j�|�d d �|�d d �d �S )Nr z.pyT)�mod_typeZignore_deprecatedZ check_aliasesz$unable to load {0} plugin named {1} r� r )r� �collection_namer/ zM%s %s at %s has a documentation formatting error or is missing documentation.rq ZUNKNOWNr� )�name� namespacer� r� )r� r Zfind_plugin_with_contextZresolvedr r� Zplugin_resolved_pathZplugin_resolved_collectionr! r r r� r� r+ r5 r6 r7 �dictr� � namespace_from_plugin_filepath� package_pathrN )r/ � plugin_namer r� r� r& rz �__r1 r1 r2 �get_plugin_metadataV s* � �zDocCLI.get_plugin_metadatac C s` |� d�s|d7 }| �|d�}tj�|�d }|�|d�d �d�}|�dd�}|dkr\d }|S )N�/rr r r� z/_re )r� �replacerG rH �splitext�rsplit�strip)�filepathr, r Zrel_pathZextension_freeZnamespace_onlyZclean_nsr1 r1 r2 r* r s z%DocCLI.namespace_from_plugin_filepathc C s0 |dkr"| t v rd|d< nd|d< ||||d�S )Nr' T� has_actionF)rz r r r )r )r� r/ rz r� r� r r1 r1 r2 r s zDocCLI._combine_plugin_docc C sb |dkr(|� di �� d�r(td�| ���g }|dkr>t|�}nd|v rNt|�}|�d� d�|�S )z9 return heavily commented plugin use to insert into play r% r� r� z�The {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& rr r� )rN r r� �_do_lookup_snippet�_do_yaml_snippetr� rI )r� r/ rz r8 r1 r1 r2 r � s � zDocCLI.format_snippetc C s� |d }||d< ||d< ||d< zt �|||�}W nJ ty| } z2t�t�� � td| t|�f |d��W Y d }~n d }~0 0 |S )Nro r� r� r z5Unable to retrieve documentation from '%s' due to: %srF ) r� � get_man_textr� r+ r5 r6 r7 r r ) r� r/ rz r� r� r r& r8 r9 r1 r1 r2 r! � s .zDocCLI.format_plugin_docc C s0 i }| j �� D �]}d }tt| j | d ��}d }z t|�}W n( tyf } z|}W Y d }~n d }~0 0 |d u r�|�d�d }|�||j �} t j D ]L} | � | �} z| � � r�t| �}W q� ty� } z|}W Y d }~q�d }~0 0 q�|r�t �d||f � q|�r t|t��sd} n|�dd��� } | ||< q|S )Nr re r� z+%s has a documentation formatting error: %sZ UNDOCUMENTEDrq zINVALID SHORT DESCRIPTION)r rs r r r r� rh � with_name�suffixr� ZDOC_EXTENSIONS� with_suffixrK r+ r� � isinstancer) rN r3 ) rQ r r� r� rz r� Zdocerrorr9 �baseZbasefile� extensionZdocfiler� r1 r1 r2 r � s6 z$DocCLI._get_plugin_list_descriptionsc C s@ g }| j dd�D ]"}t|dd�}||vr|�|� qtj�|�S )z; Returns a string suitable for printing of the search path F)�subdirsrb rc )Z _get_pathsr r� rG r� rI )�finder�ret�ir1 r1 r2 � print_paths� s zDocCLI.print_pathsc C s t | |dtd��d�S )Nz'')�default_flow_styleZ default_styleZDumperr� )r r �rstrip)�struct� flow_styler1 r1 r2 r" � s zDocCLI._dump_yamlc s$ t �d�� fdd�| �d�D ���S )Nr� c s g | ] }� | �qS r1 r1 )r> �line��indentr1 r2 r? � r@ z(DocCLI._indent_lines.<locals>.<listcomp>)r� r� rI rh )r8 rJ r1 rI r2 � _indent_lines� s zDocCLI._indent_linesc C s2 |dkrd}| dkrdS |r(d| |f } d| f S )Nzansible.builtinz ansible-coreZ historicalz%s of %sz version %sr1 )r� r� r1 r1 r2 �_format_version_added� s z DocCLI._format_version_addedrr c C sx t |�D �]h}t|| �}|�dd�}t|t�s<td| ��|rFd} nd} | �d|| |f � d|vrntd��t|d �r�t|d d �D ]F\} } t| t �s�td || t | �f ��| �t j t �| �|||d �� q�nHt|d t �s�td |t |d �f ��| �t j t �|d �|||d �� |d= g } d D ]$} | |v �r(| �| |�| �f� �q(|�sl|�sld|v�rld |d< i }dD ]`}||v �rt|| �rtdd� |�|�D �||< t jD ]&}|| D ]}||v �r�||= �q��q��qtd|v �rJ|d �rJg |d< |d D ]H}d|v�r2|d �|d d|d �dd� d�� n|d �|� �q�|d= |�rl| �t �t �d|i�|�� |�dd �}|�dd �}t |�D ]n}|�d��r��q�t|| ��r�| �t �d|t j|| d d �f |�� n | �t �t �||| i�|�� �q�|�r | �d |t �||�f � | D ]B\} }| �d � | �d || �� f � t �| |||d! ||� �q | s| �d � qd S )"N�requiredFz8Incorrect value for 'Required', a boolean is needed.: %s�=�-z%s%s %sr� zCAll (sub-)options and return values must have a 'description' fieldr� z8Expected string in description of %s at index %s, got %s��initial_indent�subsequent_indentz,Expected string in description of %s, got %s)r� � suboptions�contains�specr� )�envZiniZyaml�varsr$ c S s g | ] }t |��qS r1 )r) )r> �itemr1 r1 r2 r? * r@ z%DocCLI.add_fields.<locals>.<listcomp>�cli�optionr' z--%sr� )r' rZ Zset_viar� r� �%s: %sT)rG z%sadded in: %s rr z%s%s: z )r� r) �popr< r r r� r � enumerater r� �textwrap�fillr� r� �IGNOREr0 rK r" r� rL �upper� add_fields)r8 �fields�limit� opt_indent� return_valuesZ base_indent�o�optrM Z opt_leadinZ entry_idxr` rS ZsubkeyZconfZconfig�ignorerX rY r� r� r Zsubdatar1 r1 r2 rb � sv "" * *$ zDocCLI.add_fieldsc C s" g }d}t jd }tt jt|� d�}|�d|�� |�d�f � |d D �]�}|d | }|�d�r�|�d||�d�f � n|�d | � |�d �r�t|d t�r�d � |d �} n|d } |�d t j t � | �|||d � � |�d��r|�d� t �||�d�||� |�d� |�d��rT|�d� |�t �t �|�d��|�� |�d� dD ]�} | |v�rj�qXt|| t��r�|�d| �� t j t � || �|t| �d |d�f � nZt|| ttf��r�|�d| �� d� || �f � n$|�t �t �| �� || i�d�� |�d� �qXqJ|S )a� Generate 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. � 皙�����?�F � > %s (%s) rH rp rq zENTRY POINT: %s - %s zENTRY POINT: %s r� � �%s rP r� �OPTIONS (= is mandatory): rr � attributes� ATTRIBUTES: )Zauthorr[ � �rR r� )r+ r� r� �intr� ra rN r< r� rI r^ r_ r� r� rb r\ rK r" r rg �tuple) rQ r# r� r8 re �padrd ry rz r� r r1 r1 r2 r� V sL � �"$zDocCLI.get_role_man_textc C sn t | �} tjtjd f t_d}g }tjd }ttjt|� d�}| � tjd | � d��pf| � d�pf|}|rxd||f }|� d|� � | � d �f � t | d t�r�d �| � d ��}n | � d �}|� d tjt�|�|||d � � d| v �r| � d�} | � dd �} |� dt�| | � � | � dd��r�|� d� t | d t ��r�d| d v �rb|� d| � d� � nDd| d v �r�d| d v�r�| d d | d d< |� d| � d� � n|� d| � d� � |� d� | � dd��r�|� d d � | � d d��r|� d � t�|| � d �||� |� d � | � d!d��rZ|� d"� |� t�t�| � d!��|�� |� d � | � d#d��r�|� d$� | d# D ]4} |� tjt�| �|d% |d d&� d' |d �� �qz|� d � |� d � | d#= | � d(d��rb|� d)� | d( D �]Z} d*| v �r�|� tjt�d+| d* �|d% |d d&� d' |d �� | � d �} | d u �r`| d* �d,��r`d-| d* } | d u�r�|� tjt�| �|d% |d. |d. d �� | d* �d,��rDd/| d* �d0d1d2� }|� tjt�t|��|d% |d. |d �� �q�d| v �r�d3| v �r�d | v �r�|� tjt�| d �|d% |d d&� d' |d �� |� tjt�| d �|d% |d. |d. d �� |� tjt�| d3 �|d% |d. |d. d �� n�d4| v �r�d | v �r�|� tjt�d5| d4 �|d% |d d&� d' |d �� |� tjt�| d �|d% |d. |d. d �� |� tjt�td6| d4 ��|d% |d. |d. d �� �q�|� d � |� d � | d(= | � d7d��r�d8�| � d7��}|� d9tjt�|�|d: d;|d � � t| �D ]�}|tjv �s�| | �s̐q�t | | t��r|� d<|� � tjt�| | �|t |�d2 |d=�f � nZt | | tt f��rL|� d<|� � d8�| | �f � n$|� t�t�|� � | | i�d �� | |= |� d � �q�| � d>d��r2|� d?� |� d � t | d> t��r�|� | � d>�� � � nRz |� t | � d>�d2dd@�� W n2 t �y } zt!dA|dB��W Y d }~n d }~0 0 |� d � |� d � | � dCd��rd|� dD� tj|| � dC�||dEdF� d�|�S )GNr� rj rk rl r' r/ r rm r� r� rn ro rP r� r� z ADDED IN: %s r, Fz DEPRECATED: Zremoved_at_datezg Reason: %(why)s Will be removed in a release after %(removed_at_date)s Alternatives: %(alternative)sr* Z removed_inz[ Reason: %(why)s Will be removed in: Ansible %(removed_in)s Alternatives: %(alternative)sz%sr� r5 z * note: %s z.This module has a corresponding action plugin.r� rp rr rq rr ZnoteszNOTES:� ���z* Zseealsoz SEE ALSO:r' z Module %szansible.builtin.z,The official documentation on the %s module.z zcollections/%s_module.htmlre r/ rs �link�refzAnsible documentation [%s]z/#stq=%s&stp=1Z requirementsr� zREQUIREMENTS:%s � z r[ rt r� z EXAMPLES:)rJ rD z Unable to parse examples sectionrF r� zRETURN VALUES:T)rf )"r) r� r` r r� r+ r� r� ru rN r� ra r\ r< r� rI r^ r_ r� rL rb rK r" r� r0 r" r� r rg rv r3 r r� r )rz r& r/ re r8 rw rd r, r� r� r� ZnoterX r� Z relative_urlZreqr r9 r1 r1 r2 r8 � s� & � � � � �� ��� �� � & :"$ " zDocCLI.get_man_text)N)FT)F)N)Frr )rr rr )5r� r� r� r� r' r` �re�compiler� r� r� r� r� r� r� r� r� r� r� r� r� � classmethodr� r� r� r� r� r� r� � staticmethodr� r r� r r r� r r r$ r. r* r r r! r rC r" rK rL rb r� r8 � __classcell__r1 r1 r� r2 r� ] s| 4 -! C + l ' X=r� c C sf g }t �| d �}| �d�}|r>|�d| � |�d| � n |�d| �d| �d�� � d}d �|d �}tj| }t| d �� �D ]�}| d | }t |d t �r�t �|d �} nt �d � |d ��} |�dd�} t | t �s�t d| ��d| }|�r&| �rd| } |�d|tj| ||d�f � q�| �r2d} n |�dd�} |�d|| tj| ||dd�f � q�|S )Nrq r' z - name: %sz %s:z# %s:r� r' � z# rs r� r� rn rM F�7Incorrect value for 'Required', a boolean is needed: %sz%s:z (required) %sz %-20s # %srt z (required)r� �Nonez %s %-9s # %srf )rR Z max_lines)r� r� rN r� �rjustr+ r� r� rs r< r rI r r r^ r_ ) rz r8 Zmdescr' rw Zsubdentrd rg rh r� rM r� r1 r1 r2 r7 s8 $r7 c C s g }d| � d| � d�� }g }t| d �� �D ]�}| d | }|�d||� dd�|� dd �f � |d v rx|d | 7 }q.|� d d �}t|t�s�td| ��|r�d}n |� dd�}|� d�dv r�|d||f 7 }q.|d||f 7 }q.|d7 }|�r|�|� |�d � |�|� |S )Nz lookup('%s', r� r' r� z # %s(%s): %sr� r� r� rr )Z_termsZ_rawZ_listz< %s >rM Fr� z <REQUIRED>r� r� )r� �strz , %s='%s'z, %s=%s�))rN r� rs r� r< r r r� )rz r8 ZsnippetZcommentrg rh rM r� r1 r1 r2 r6 L s0 $ r6 c C s t �| � d S r� )r� Z cli_executor)r� r1 r1 r2 rA r s rA �__main__)N)N)SZ __future__r r r r� Z __metaclass__Z ansible.clir r� rG Zos.pathr} r^ r6 Zansible.plugins.loaderr r r �pathlibr r� r r� r Zansible.cli.argumentsr r� Zansible.collections.listr Zansible.errorsr r r r Zansible.module_utils._textr r Z'ansible.module_utils.common.collectionsr Z ansible.module_utils.common.jsonr Z ansible.module_utils.common.yamlr Zansible.module_utils.compatr Zansible.module_utils.sixr Zansible.parsing.plugin_docsr Zansible.parsing.utils.yamlr Zansible.parsing.yaml.dumperr Zansible.plugins.listr r r Z ansible.utils.collection_loaderr r Z2ansible.utils.collection_loader._collection_finderr Zansible.utils.displayr Zansible.utils.plugin_docsr r! r" r+ r r� r� r� r� r3 r: �objectr; r� r7 r6 rA r� r1 r1 r1 r2 �<module> sj I-&