File: //usr/lib/python3.9/site-packages/ansible/cli/__pycache__/doc.cpython-39.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-&