Dashboard
PHP:
8.2.30
OS:
Linux
User:
dh_nv8b2m
/
/
usr
/
local
/
lib
/
python3.10
/
dist-packages
/
ansible
/
cli
/
__pycache__
📤 Upload
📝 New File
📁 New Folder
Close
Editing: doc.cpython-310.pyc
o O�h � @ sB d dl mZ d dlmZ d dlZd dlZd dlZd dlZd dlZd dl Z d dl Z d dl m m Z d dlmZ d dlmZ d dlmZ d dlmZ d dlmZ d d lmZm 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,m-Z- d dl.m/Z/ d dl0m1Z1 d dl m2Z2m3Z3 d dl4m5Z5m6Z6 d dl7m8Z8 d dl9m:Z: d dl;m<Z< d dl=m>Z>m?Z?m@Z@ e<� ZAejBd ZCg d�ZDi ZEg d�ZFd d d d d d!d"d#�ZGd$d%d&d&d'�ZHd(d)d*d)d+d(d,�ZId-d.� ZJG d/d0� d0eK�ZLd1d2� ZMd3d4� ZNG d5d6� d6eeL�ZOd7d8� ZPd9d:� ZQd>d;d<�ZReSd=k�r eR� dS dS )?� )� annotations)�CLIN)�Path)� constants)�context)�option_helpers)�list_collection_dirs)� AnsibleError�AnsibleOptionsError�AnsibleParserError�AnsiblePluginNotFound)� to_native�to_text)� is_sequence)� json_dump)� yaml_dump)� string_types)� read_docstub)� from_yaml)� AnsibleDumper)� list_plugins)� action_loader�fragment_loader)�AnsibleCollectionConfig�AnsibleCollectionRef)� _get_collection_name_from_path)�stringc)�Display)�get_plugin_docs� get_docstring�get_versioned_doclink)�role�keyword)�Play�Role�Block�Task�Handler)� inventory�lookup�modulez[5mz[1mz[8mz[0mz[0;0mz[7mz[4m)�BLINK�BOLD�HIDE�NORMAL�RESET�REVERSE� UNDERLINEz*%s*z`%s`z[%s])r, r1 �MODULE�PLUGIN�yellow�magenta�cyanz dark gray)r2 �REF�LINK�DEP�CONSTANTr3 c C sL z t � t| �� W d S ty% } zt �t�� � tdt|� ��d }~ww )NzXWe could not convert all the documentation into JSON as there was a conversion issue: %s)�displayr � TypeError�vvv� traceback� format_excr r )�text�e� rB �:/usr/local/lib/python3.10/dist-packages/ansible/cli/doc.py�jdumpN s ��rD c @ s� e Zd ZdZdd� ejD �Zdd� ejD �e Zdd� Zdd� Z d d � Z dd d �Z ddd�Z dd� Z dd� Zddd�Zd dd�Zd S ) � 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 � g | ]}d | �qS )�mainrB ��.0rA rB rB rC � <listcomp>^ � zRoleMixin.<listcomp>c C rF )�argument_specsrB rH rB rB rC rJ _ rK c C s� |r t j�|d|d�}nt j�|d�}|D ]}t j�||�}t j�|�r(|} nq|du r/i S z1t|d��!} t| �� |d�} | du rMi } W d � W | S W d � W | S 1 sYw Y W | S ttfyx } z t d||f | d��d} ~ 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 �roles�metaN�r)� file_namez$Could not read the role '%s' (at %s)��orig_exc) �os�path�join�exists�openr �read�IOError�OSErrorr ) �self�root�files� role_name� collection� meta_path�specfile� full_pathrT �f�datarA rB rB rC �_load_role_dataa s6 � �� �����zRoleMixin._load_role_datac C s | � || 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 )re �ROLE_METADATA_FILES)r[ r^ � role_pathr_ rd rB rB rC �_load_metadata� s zRoleMixin._load_metadatac C sb z| � || j||�}|�di �}W |S ty0 } zd|t|�f |d�}W Y d}~|S d}~ww )a� 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 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. rL z Failed to process role (%s): %s)�error� exceptionN)re �ROLE_ARGSPEC_FILES�get� Exceptionr )r[ r^ rg r_ rd rA rB rB rC � _load_argspec� s � ��zRoleMixin._load_argspecNc C s� t � }t � }|D ]G}tj�|�sqt�|�D ]8}tj�||�}| jD ]+}tj�|d|�} tj�| �rM|du s:||v rK||vrK|�|� |�|d|f� nq"qq|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 rN N) �setrS rT �isdir�listdirrU rk rV �add) r[ � role_paths� name_filters�found� found_namesrT �entryrg ra rb rB rB rC �_find_all_normal_roles� s& ���z RoleMixin._find_all_normal_rolesc C s t � }t|d�}|D ]}}t|dd�}t|�}tj�|d�}tj�|�r�t�|�D ]^} | j D ]X} tj�|| d| �} tj�| �r�|du rK|� | ||f� n8|D ]5} t | � d��dkrv| � d�\} }}d�| |g�|kru| |kru|� | ||f� qM| | kr�|� | ||f� qM nq-q(q |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 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_filter�surrogate_or_strict��errorsrM rN N�.� ) ro r r r rS rT rU rV rq rk rr �len�split)r[ rt �collection_filterru � b_colldirs�b_pathrT �collname� roles_dirrw ra rb �fqcn�ns�colr! rB rB rC �_find_all_collection_roles� s4 ���� z$RoleMixin._find_all_collection_rolesc C s~ |r |� d�r |d }nddi}i |d< |r"d�||g�}||d< n|}|�� D ]}|| p/i }|� dd�|d |< q(||fS ) a3 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 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� )rl rU �keys) r[ r! r_ rN �argspec�summaryr� �ep� entry_specrB rB rC �_build_summary� s zRoleMixin._build_summaryc C s� |r d� ||g�}n|}i }||d< ||d< d|v r#|�|� ||fS i |d< |�� D ]}|d u s5||krA|| p:i } | |d |< q+t|d �� �dkrNd }||fS )Nr} rT r_ ri r� r )rU �updater� r ) r[ r! rT r_ r� � entry_pointr� �docr� r� rB rB rC � _build_doc s$ � �zRoleMixin._build_docTc C s� | � � }| �� }|s| �|�}nt� }| j|d�}i }||B D ][\}}} z | �|| |�} W n tyM } zt�d|t | �f d� i } W Y d} ~ nd} ~ ww | � || |�} d| v rl|r_| d �t� d|| d f d� q | � ||| | �\} }||| < 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', } }, } )r� z$No metadata for role (%s) due to: %sTNri rj z Skipping role (%s) due to: %s) �_get_roles_path�_get_collection_filterrx ro r� rh rm r; r= r rn �warningr� )r[ �fail_on_errors� roles_pathr� rM � collroles�resultr! r_ rg rN rA r� r� r� rB rB rC �_create_role_list2 s0 �� zRoleMixin._create_role_listc C sn | � � }| j||d�}| j|d�}i }||B D ] \}} } | �|| | �} | �|| | | |�\} } | 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 )r� rx r� rn r� )r[ � role_namesr� r� r� rM r� r� r! r_ rg r� r� r� rB rB rC �_create_role_doco s �zRoleMixin._create_role_doc�N)NN)T)NT)�__name__� __module__� __qualname__�__doc__�C�YAML_FILENAME_EXTENSIONSrf rk re rh rn rx r� r� r� r� r� rB rB rB rC rE V s $ %* =rE c C s | � d�s t| �} | S )N)�httpz..)� startswithr )�urlrB rB rC �_doclink� s r� c G s� |D ]I}|t vr|�� tvr|tjvrtd| ��tjr'|tv r&t| | } q|tjv r2t| |�} q|t v r>t| t | �} qdt|�� | td f } q| S )z$ add ascii formatting or delimiters z!Invalid format value supplied: %sz%s%s%sr. ) � ref_style�upper�STYLEr� � COLOR_CODES�KeyError�ANSIBLE_NOCOLOR�NOCOLORr )�string�args�stylerB rB rC �_format� s � r� c sZ e Zd ZdZdZdZe�d�Ze�d�Z e�d�Z e�d�Z e�d�Z e�d �Z e�d �Ze�d �Zd Ze�d e �Ze�de �Ze�de �Ze�de �Ze�d�Ze�d�Ze�d�ZdZe�d�Ze�d�Ze�d�Ze�d�Z � fdd�Z e dd � �Z e d d � �Z e!d d � �Z"� fd!d"�Z#� fd#d$�Z$d%d&� Z%d'd(� Z&d)d*� Z'e d+d,� �Z(e d-d.� �Z)d/d0� Z*d1d2� Z+d]d5d6�Z,d7d8� Z-e d9d:� �Z.� fd;d<�Z/e d=d>� �Z0e d?d@� �Z1e dAdB� �Z2e dCdD� �Z3e dEdF� �Z4e dGdH� �Z5dIdJ� Z6e dKdL� �Z7e d^dMdN��Z8e dOdP� �Z9e d_dRdS��Z:e d`dUdV��Z;e dadWdX��Z<dYdZ� Z=e d`d[d\��Z>� Z?S )b�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* �docuri� version_added�version_added_collectionr� �now_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+?::c s t t| ��|� t� | _d S r� )�superr� �__init__ro � plugin_list)r[ r� �� __class__rB rC r� � s zDocCLI.__init__c C s t j�d| �d��}d|� d�S )N�\1� �`�')r� � _UNESCAPE�sub�group)�matcherr@ rB rB rC �_tty_ify_sem_simle� s zDocCLI._tty_ify_sem_simlec C s* t j�d| �d��}d }d|v r|�dd�\}}t j�|�}|r0|�d�}|�d�}|�d�}n|�t j�rD|t t j�d � }d }}nd }}d }d|v rV|�dd�\}}|d ura|� d|� �}|r�|r�|dv rkdnd }|� |� d |� �}|d kr�|d ur�|� d |� d �}d|� d|� d�S d|� d�S )Nr� r� �=� r~ r� �:)r! r* �playbook� plugin� r! �, z entrypointr� z' (of �)r� ) r� r� r� r� r� �_FQCN_TYPE_PREFIX_RE�matchr� �_IGNORE_MARKERr ) r� r@ �value�m� plugin_fqcn� plugin_type� entrypoint� plugin_suffix�pluginrB rB rC �_tty_ify_sem_complex� s2 zDocCLI._tty_ify_sem_complexc C sR | j �tdd�|�}| j�tdd�|�}| j�tdd�|�}| j�d|�}| j�d|�}| j�tdd�|�}| j�tdd�|�}| j �td d �|�}| j �| j |�}| j �| j |�}| j�| j |�}| j�| j |�}| j�d �d �|�}| j�d |�}| j�tdd�|�}| j�d|�}| j�d|�}t�| jdd� |�}t�| jdd� |�}|S )Nr� r1 r, r2 z\1 <\2>z[\1]r3 r7 z`\1'r: z {0} z -------------z See also:zNote:�boldr� r� c S s t dt| �d�� d�S )N�%sr� r8 )r� r� r� �r� rB rB rC �<lambda> s z DocCLI.tty_ify.<locals>.<lambda>c S s" d| � d�tt| � d��d�f S )Nz%s <%s>r� r� r8 )r� r� r� r� rB rB rC r� s " )�_ITALICr� r� �_BOLD�_MODULE�_URL�_LINK�_PLUGIN�_REF�_CONST�_SEM_OPTION_NAMEr� �_SEM_OPTION_VALUEr� �_SEM_ENV_VARIABLE�_SEM_RET_VALUE�_RULER�format� _RST_SEEALSO� _RST_NOTE� _RST_ROLES�_RST_DIRECTIVES�re)�clsr@ �trB rB rC �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� �*�Pluginr� )�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-pointr� z#Select the entry point for role(s).)r r z-sz --snippet� show_snippetz0Show playbook snippet for these plugin types: %sr� 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_help�add_module_options�parser�add_basedir_options� add_argumentr� �TARGET_OPTIONSr� �DEFAULT_ROLES_PATH� unfrack_path�PrependListAction� add_mutually_exclusive_grouprU �SNIPPETS)r[ ry � exclusiver� rB rC r sP � �� � � ��� � �zDocCLI.init_parserc s t t| ��|�}|jt_|S r� )r� r� �post_process_args� verbosityr; )r[ �optionsr� rB rC r N s zDocCLI.post_process_argsc C s� t dd� |�� D ��}tj| d }g }g }tjd rot|�� �D ]L}t|| �}|�d�}|d � d�r_|d d kr_|d d v r_|d d d � |d< d� |�}|� d |||t |�|f � q!|� d |||t |�|f � q!n[t|�� �D ]T}t �|| �} t | �|kr�| d |� d } |�d�}|d � d�r�|� d�r�|d d d � |d< d� |�}|� d |||t | �| f � qu|� d |||t | �| f � qut |�dkr�|� d� |�|� t �d� |�� d S )Nc s � � | ]}t |�V qd S r� �r �rI �xrB rB rC � <genexpr>X � � z-DocCLI.display_plugin_list.<locals>.<genexpr>� r r} ����_r �ansibler� )�builtin�legacyz %-*s %-*.*s�...)�ansible.builtin.zansible.legacy.z DEPRECATED:� )�maxr� r; �columnsr �CLIARGS�sortedr r� r� rU �appendr r� r� �extend�pager) r[ �results�displace� linelimitr@ � deprecatedr� �filename�pbreakr� rB rB rC �display_plugin_listU s8 & � zDocCLI.display_plugin_listc C s t |�� �}t� }|D ]}|| d �� D ]}|�|� qq d}d}|r-tdd� |D ��}tj| | d }g } t|�D ]A}|| d rv| �d| � | �d� || d � � D ] \}} t | �|krj| d|� d } | �d ||| f � qXq<| �d | � 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 r� r c s r" r� r# r$ rB rB rC r& � r' z2DocCLI._display_available_roles.<locals>.<genexpr>r( �%s:z specs:Nr. z %-*s: %sr� r0 )�listr� ro rr r1 r; r2 r4 r5 �itemsr r� r7 rU ) r[ � list_jsonrM �entry_point_namesr! r� � max_role_len� max_ep_lenr: r@ r� rB rB rC �_display_available_roles� s. � �z DocCLI._display_available_rolesc C s� t |�� �}g }|D ]8}z"d|| v r#t�d||| d f d� W q || �||| �7 }W q tyB } ztd| |d��d }~ww t�d�|�� d S )Nri z Skipping role '%s' due to: %sTzRole '%srQ r0 ) r@ r� r; r� �get_role_man_textr r� r7 rU )r[ � role_jsonrM r@ r! rA rB rB rC �_display_role_doc� s ��zDocCLI._display_role_docc C s t t�dd��S )Nr+ zkeyword_desc.yml)r �pkgutil�get_datarB rB rB rC �_list_keywords� s zDocCLI._list_keywordsc C s� i }t �� }| D ]�}|�d�rd}n |dkrd}n|}z�d|| i}g |d< tD ]l}|tvrAd|�� }t�|�}t||d �t|< |t| j v r�|d � |� d|vr�t| j � |�} t| d �rdi }t �t| d d �|d< |� d �su|d v rzd|d< nt| d�r�d|d< nd|d< dD ] } t| | �|| < q�q(t|�� �D ] } || d u r�|| = q�|||< W q tt fy� } z t�d|t| �f � tjdkr�t�t�� � W Y d } ~ qd } ~ ww |S )N�with_�loop�async� async_valr� � applies_tozansible.playbook.%sr �private�isar� �when)�until�implicit�template�static�explicit)�alias�priorityz+Skipping Invalid keyword '%s' specified: %sr~ )r� rL r� � PB_OBJECTS� PB_LOADED�lower� importlib� import_module�getattr� fattributesr5 rl r� �endswithr@ r� �AttributeErrorr; r� r r �verboser> r? ) r� rd �descs�keyr" �kdata�pobj� obj_class� loaded_class�fa�visible�krA rB rB rC �_get_keywords_docs� sX � � ��zDocCLI._get_keywords_docsc C sF d }t tjd �dkr!tjd }|D ]}t�|�s td�|���q|S )Nr� r� zGInvalid collection name (must be of the form namespace.collection): {0})r r r3 r �is_valid_collection_namer r� )r[ ry � coll_namerB rB rC r� � s �z DocCLI._get_collection_filterc s� i }i � _ t�|�}� �� }� j �t||�� |dkr"� �|�}|S |dkr4� fdd�� j �� D �}|S dd� � j �� D �}t� � _ |S )N�dirr] c s i | ] }|� j | d �qS )r )�plugins�rI rn �r[ rB rC � <dictcomp> s z(DocCLI._list_plugins.<locals>.<dictcomp>c S s i | ]}|i �qS rB rB rt rB rB rC rv s ) rs r� � _prep_loaderr� r� r � _get_plugin_list_descriptionsr� ro r� )r[ r� �contentr8 �loaderry rB ru rC � _list_plugins s ��zDocCLI._list_pluginsFTc C st t �|�}i }|D ]�}i }zt|||ttjd dk�\}} } } W nX ty9 } z t�t | �� W Y d } ~ q d } ~ w t yx } z4|sRddt | � i||< W Y d } ~ q t� t � � � d||t | �f } |rjt�| � nt| ��W Y d } ~ nd } ~ ww |s�|s�ddi||< q t �|||| | | �}|s�zt|� W n t y� } zddt | � i||< W Y d } ~ q d } ~ ww |||< q |S )Nr r ri 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� rw r r r r3 r r; r� r rm r= r> r? r �_combine_plugin_docr )r[ r� �names�fail_okr� rz � plugin_docsr� r� r� r� �metadatarA �msg�docsrB rB rC �_get_plugins_docs sJ & � ��� �� zDocCLI._get_plugins_docsc C sV t jd }t jd dur)tj�t jd d�}tj�|�r!|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� �basedirNrM )r r3 rS rT rU rp )r[ r� �subdirrB rB rC r� H s zDocCLI._get_roles_pathc C sb t td| �}tjd dur|jtjd dd� tjd r,tjd D ] }|r+|�|� q"d|_|S )z' return a plugint type specific loader � %s_loaderr� NT)� with_subdir� module_path)ra � plugin_loaderr r3 � add_directory�_paths)r� rz rT rB rB rC rw Y s �zDocCLI._prep_loaderc s� t t| ��� tjd }tjd �� }tjd p tjd }tjd p&tjd }tjd r/d}n tjd r7d}nd }i }|r@|t_|tvrJt d | ��tjd r�t}i |d < |D ]O}t tjd �} |d kr}| j | d �} | j | � � tjd | d �|d |< qW|dkr�t�� } t�| � � �|d |< qW| �|d �} | j|| |dv | d�|d |< qWnQ|r�|dkr�t�� }nF|d kr�| j dd �}n;| �||�}n4ttjd �dkr�t d��|dkr�t�tjd �}n|d kr�| � tjd tjd �}n | �|tjd �}|�rt|� dS g } |tjv �r�|�r|�r| �|� n�tjd �re|tv�r*tdd�t� ��|�� D ]5\}}z t�|||d �}W n t �y\ } zt � d� |t |��� W Y d }~�q.d }~ww | �!|� �q.nV|�� D ](\}}t�"|||d |d |d |d �}|�r�| �!|� �qit � d | � �qin(|d k�r�tjd �r�|�r�| �#|� n|�r�| �$|� n |�r�t�%t�&|��} | �r�t�'d �| �� dS ) Nr� r r r r r r] rr z)Unknown or undocumentable plugin type: %s�allr r! )r� r� r" )�test�filter)r~ r� Fr� r zEMissing name(s), incorrect options passed for detailed documentation.r z>Snippets are only available for the following plugin types: %sr� r� z,Unable to construct a snippet for '{0}': {1}�examples�returnr� z.No valid documentation was retrieved from '%s'r� )(r� r� �runr r3 r^ r �playbook_pathsr r �boolr� r� r� rL ro r{ r� r rD r� �DOCUMENTABLE_PLUGINSr> r r rU rA �format_snippet� ValueErrorr; r� r� r r5 �format_plugin_docrF rI r� � _dump_yamlr7 )r[ r� r� �do_json�listingry r� �ptypes�ptype�no_failrM r} � plugin_namesr@ r� �doc_data�textretrA r� rB rC r� l s� $ � +� � ���� �� �z DocCLI.runc C s> t td| �}|�� }i }|D ] }|�t| �� qt|�� �S )Nr� )ra r� �_get_paths_with_contextr� r r4 r� )r� rz �pathsrs � path_contextrB rB rC �get_all_plugins_of_type� s z DocCLI.get_all_plugins_of_typec C s� t td| �}|j|dddd�}|jstd�| |���|j}|j}zt|t t j d dk|| d�\}}}}W n t yL t �t�� � td | ||f ��w |d u rSd S t|t�|||j�|�d d �|�d d �d �S )Nr� z.pyT)�mod_type�ignore_deprecated� check_aliasesz$unable to load {0} plugin named {1} r r )re �collection_namer� zM%s %s at %s has a documentation formatting error or is missing documentation.r� �UNKNOWNr� )�name� namespacer� r� )ra r� �find_plugin_with_context�resolvedr r� �plugin_resolved_path�plugin_resolved_collectionr r r r3 rm r; r= r> r? �dictr� � namespace_from_plugin_filepath� package_pathrl )r� r� rz r� r< r� r� �__rB rB rC �get_plugin_metadata� s, � � �zDocCLI.get_plugin_metadatac C s` |� d�s |d7 }| �|d�}tj�|�d }|�|d�d �d�}|�dd�}|dkr.d }|S )N�/r� r r� z/_r} )rc �replacerS rT �splitext�rsplit�strip)�filepathr� r� �rel_path�extension_free�namespace_only�clean_nsrB rB rC r� � s z%DocCLI.namespace_from_plugin_filepathc C s0 |dkr| t v r d|d< nd|d< ||||d�S )Nr* T� has_actionF)r� r� r� r� )r )r� r� r� r� r� r� rB rB rC r| s zDocCLI._combine_plugin_docc C sb |dkr|� di �� d�rtd�| ���g }|dkr t|�}nd|v r't|�}|�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) r� r0 )rl r� r� �_do_lookup_snippet�_do_yaml_snippetr5 rU )r� r� r� r@ rB rB rC r� s � zDocCLI.format_snippetc C st |d }||d< ||d< ||d< z t �|||�}W |S ty9 } zt�t�� � td| t|�f |d��d }~ww )Nr_ r� r� r� z5Unable to retrieve documentation from '%s' due to: %srQ ) r� � get_man_textrm r; r= r> r? r r ) r� r� r� r� r� r� r� r@ rA rB rB rC r� + s ���zDocCLI.format_plugin_docc C s( i }| j �� D ]�}d }tt| j | d ��}d }zt|�}W n ty2 } z|}W Y d }~nd }~ww |d u ro|�d�d }|�||j �} t j D ]%} | � | �} z | � � rYt| �}W qI tyn } z|}W Y d }~qId }~ww |r{t �d||f � q|r�t|t�s�d} n|�dd��� } | ||< q|S )Nr r} r) z+%s has a documentation formatting error: %sr� r� zINVALID SHORT DESCRIPTION)rs r� r r r rm r� � with_name�suffixr� �DOC_EXTENSIONS� with_suffixrV r; r� � isinstancer� rl r� ) r[ rz rf r� r� r< �docerrorrA �base�basefile� extension�docfiler� rB rB rC rx B s@ �� ��� 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)�subdirsrz r{ )� _get_pathsr r5 rS r rU )�finder�ret�irB rB rC � print_pathsi s � zDocCLI.print_pathsc C s t | |dtd��d�S )Nz'')�default_flow_style� default_style�Dumperr0 )r r �rstrip)�struct� flow_stylerB rB rC r� u s zDocCLI._dump_yamlc s$ t �d�� fdd�| �d�D ���S )Nr0 c s g | ]}� | �qS rB rB )rI �line��indentrB rC rJ { rK z(DocCLI._indent_lines.<locals>.<listcomp>)r� r� rU r� )r@ r� rB r� rC � _indent_linesy s $zDocCLI._indent_linesNc C s2 |dkr d}| dkr dS |rd| |f } d| f S )N�ansible.builtin� ansible-core� historicalz%s of %sz version %srB )r� r� rB rB rC �_format_version_added} s z DocCLI._format_version_addedr� c K sH g }| � d�D ]}|�tj||f||dddd�|��� |}qd�|�S )Nz FT)�initial_indent�subsequent_indent�break_on_hyphens�break_long_words�drop_whitespacer0 )r� r5 �textwrap�fillrU )r@ �limitr� r� �kwargsr� � paragraphrB rB rC � warp_fill� s �� zDocCLI.warp_fillc C s2 t |�D �]}t|| �}|�dd�} t| t�s td| ��d} d} | r5tjr)d} d|| t|dd �f } ntjr:d } d|| t|d �f } d |vrLtd ��| � d� |dt t |�t |� t |� d� } | dt |�d } t |d �r�t |d d�D ]9\}}t|t�s�td||t|�f ��|dkr�| � | tjt�|�|| | d� � q{| � tjt�|�|| | d�� q{n&t|d t�s�td|t|d �f ��| � | tjt�|d �|| | d� � |d = g }dD ]}||v r�|� ||�|�f� q�| �s|�sd|v�rd |d< i }dD ]I}||v �rO|| �rOdd� |�|�D �||< tjD ],}|| D ]$}tjdk�rCd|v �rCt�|d |�d d ��|d < ||v �rK||= �q(�q"�qd |v �r�|d �r�g |d < |d D ]%}d |v�r�|d � |d! d"|d! �d#d � d$�� �qc|d � |� �qc|d = |�r�| � t�t�d%|i�|�� |�dd �}|�d&d �}t |�D ]8}|�d#��r��q�t || ��r�| � t�d'|tj|| d(d)�f |�� �q�| � t�t�||| i�|�� �q�|�r�|�s�| � d*|t�||�f � |D ]\}}| � d+||f � t� | |||d ||� �q�qd S ),N�requiredFz8Incorrect value for 'Required', a boolean is needed.: %s� r� r� �%s%s %sr� �red�-r4 r� zCAll (sub-)options and return values must have a 'description' fieldr� r� r~ r� z8Expected string in description of %s at index %s, got %s�r� r� z,Expected string in description of %s, got %s)r! � suboptions�contains�specr )�env�ini�yaml�varsr" c S s g | ]}t |��qS rB )r� )rI �itemrB rB rC rJ � rK z%DocCLI.add_fields.<locals>.<listcomp>r r� �version_added_collecitonr� �added_in�cli�optionr� z--%sr* )r� r� �set_viar� �%s: %sT)r� z%sadded in: %sz%s%s:) r4 r� �popr� r� r r� r� r� r5 r1 r r � enumerater r r� r� r� �IGNOREr; r r� rl r� r� r� r� � add_fields)r@ �fieldsr� � opt_indent� return_values� base_indent�man�o�optr� � opt_leadinrg � inline_indent� sub_indent� entry_idxrw r� �subkey�conf�config�ignorer� r� r� r� rn �subdatarB rB rC r � s� & $ �&� ��� , ,$ ��zDocCLI.add_fieldsc C s� g }d}t jd }tt jt|� d�}|�dt|d�|�d�f � |d D �]=}|d | }d} |�d �r=d |�d � } |�d� |�d t|d�| f � |�d� |�d �r�t|d t�rd|d } n|d g} | D ]} |�d t j t � | �|||d� � qk|�d� |�d�r�|�tdd�dt j r�dnd � t �||�d�||� |�dd�r�t jd|� d|� d�ddd � |�d� |�td d�� |d �� D ]-} |�d� |�t j t � td | d ��|d ||d�� |�t �t �|d | �|�� q�|d= d!D ]c} | |v�r �q |�d� t|| t��r4|�d"| �� t j t � || �|t| �d# |d$�f � �q t|| ttf��rP|�d"| �� d%�|| �f � �q |�t �t �| �� || i�d�� �q q&|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. z 皙�����?�F z> ROLE: %s (%s)r, rT r� r� r� z- %szENTRY POINT: %s %sr� r� r� r! �Optionsr� � (%s indicates it is required):r� r� � 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 � )�authorr� r� �r� r� )r; r2 r1 �intr5 r� rl r� r@ r� r� r� r� r� r r r; r� r� r� r r� r �tuplerU ) r[ r! rH r@ r �padr� r� r� r� rf rn rB rB rC rG � sf $ " � "�" �$(� zDocCLI.get_role_man_textc C s& t | �} tjtjd f t_d}d}g }tjd }ttjt|� d�}|� d|� � t | � d�d�| � d �f � t | d t�rE| � d �}n| � d �g}|� d � |D ]} |� tjt�| �|||d �� qRtjd kryt�| � dd�| � dd��| d< | �dd�r�|� t ddd�� t | d t �r�d| d v r�|� d| � d� � n+d| d v r�d| d vr�| d d | d d< |� d| � d� � n |� d | � d� � | � d d�r�|� d � |� t d d�d � | �d d��r |� d � |� t d!d�d"tjr�d#nd$ � tj|| � d �||tjd kd%� | �d&d��rY|� d � |� t d'd�� | d& �� D ].} |� d � |� tjt�t d(| d)��|d* ||d �� |� t�t�| d& | �|�� �q'| d&= | �d+d��r�|� d � |� t d,d�� | d+ D ]} |� tjt�| �|d* |d d-� d. |d �� �qq| d+= | �d/d��rv|� d � |� t d0d�� | d/ D �]�} d1| v �r&|� tjt�d2| d1 �|d* |d d-� d. |d �� | �d �} | d u �r�| d1 �d3��r�d4| d1 } | d u�r�|� tjt�| �|d* |d5 |d5 d �� | d1 �d3��r$d6| d1 �d7d8d9� }|� tjt�t |��|d* |d5 |d �� �q�d:| v �r�d;| v �r�| d; d<v�r9d=nd }|� tjt�d>| d; � � || d: f �|d* |d d-� d. |d �� | �d �} | d u �rz| d: �d3��rzd?| d: | d; |f } | d u�r�|� tjt�| �|d* |d5 |d5 d �� | d: �d3��r�d@| d: �d7d8d9�| d; f }|� tjt�t |��|d* |d5 |d �� �q�dA| v �rdB| v �rd | v �r|� tjt�| dA �|d* |d d-� d. |d �� |� tjt�| d �|d* |d5 |d5 d �� |� tjt�| dB �|d* |d5 |d5 d �� �q�dC| v �rqd | v �rq|� tjt�dD| dC �|d* |d d-� d. |d �� |� tjt�| d �|d* |d5 |d5 d �� |� tjt�t dE| dC ��|d* |d5 |d5 d �� �q�| d/= | �dFd��r�|� d � dG� | � dF��}|� t dHd�dItjt�|�|dJ d|d � � t | �D ]s} | | �r�| tjv �r��q�|� d � t | � � d�}t | | t ��r�|� dK|tjt�| | �|t!| �d9 |dL�f � n1t | | tt"f��r�|� dK|dG� | | �f � n|� dM| t�t�| | �dNt!| �d9 � � | | = �q�| �dOd��rd|� d � |� t dPd�� t | dO t ��rA|� | � dO��#� � n#z|� t$| � dO�d9ddQ�� W n t%�yc } zt&dR|dS��d }~ww | �dTd��r�|� d � |� t dUd�� tj|| � dT�||dVtjd kdW� |� dX� dX� |�S )YNr z r� r r z > %s %s (%s)r� r� r< r� r� r� r r� r� r� r� r� r; Fz DEPRECATED: r9 �removed_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)sr� r� z * note:z/ This module has a corresponding action plugin.r! �OPTIONSr r� r� )r r r r? r1 r �noteszNOTES:���z* �seealsoz SEE ALSO:r* z Module %sr/ z,The official documentation on the %s module.z zcollections/%s_module.htmlr} r� r� r� r� )r* r! r� r� z*The official documentation on the %s %s%s.zcollections/%s_%s.htmlr� �link�refzAnsible documentation [%s]z/#stq=%s&stp=1� requirementsr� z REQUIREMENTS:z%s � r� r z%s: r� r� z EXAMPLES:)r� r� z Unable to parse examples sectionrQ r� zRETURN VALUES:T)r r r0 )'r� r� r r r3 r; r2 r1 r r5 r� r� r r� r@ r� r� r r� rl r� r� r r� r� r� r� r� r �titlerU r4 r r r r� r rm r )r� r� r� r r r@ r r� rf r� rn �noter� r� � relative_urlr� �req�headerrA rB rB rC r� @ s& * � " "�$ � � ���&� � �� �� ��� �� " � 6 0 �� " zDocCLI.get_man_text)FT)Fr� )r� r� )Fr� F)@r� r� r� r� r� r r� �compiler� r� r� r� r� r� r� r� �_SEM_PARAMETER_STRINGr� r� r� r� r� r� r� r� r� r� r� r� r� � staticmethodr� r� � classmethodr� r r r> rF rI rL ro r� r{ r� r� rw r� r� r� r� r| r� r� rx r� r� r� r� r� r rG r� � __classcell__rB rB r� rC r� � s� ! 6/" C + l ' dJr� c C s` g }t �| d �}| �d�}|r |�d| � |�d| � n|�d| �d| �d�� � d}d �|d �}tj| }t| d �� �D ]j}| d | }t |d t �rZt �|d �} n t �d � |d ��} |�dd�} t | t �sut d| ��d| }|r�| r�d| } |�d|t j| ||d�f � qC| r�d} n|�dd�} |�d|| t j| ||dd�f � qC|S )Nr� r* z - name: %sz %s:z# %s:r� r� � z# r� r! r� r� r� F�7Incorrect value for 'Required', a boolean is needed: %sr? z (required) %sz %-20s # %sr z (required)r �Nonez %s %-9s # %sr~ )r� � max_lines)r� r� rl r5 �rjustr; r2 r4 r� r� r rU r� r� r� ) r� r@ �mdescr* r �subdentr� r r r� r� r rB rB rC r� � s8 $r� c C s g }d| � d| � d�� }g }t| d �� �D ]Y}| d | }|�d||� dd�|� dd �f � |d v r<|d | 7 }q|� d d �}t|t�sMtd| ��|rRd}n|� dd�}|� d�dv rh|d||f 7 }q|d||f 7 }q|d7 }|r�|�|� |�d � |�|� |S )Nz lookup('%s', r� r� r! z # %s(%s): %sr r� r� r� )�_terms�_raw�_listz< %s >r� Fr6 z <REQUIRED>r r7 )r� �strz , %s='%s'z, %s=%sr� )rl r4 r� r5 r� r� r� r6 )r� r@ �snippet�commentr r r� r rB rB rC r� s0 $ r� c C s t �| � d S r� )r� � cli_executor)r� rB rB rC rG / s rG �__main__r� )T� __future__r � ansible.clir r_ rJ rS �os.pathr� r� r> �ansible.plugins.loaderrs rz r� �pathlibr r+ r r� r �ansible.cli.argumentsr r �ansible.collections.listr �ansible.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.yamlr �ansible.module_utils.sixr �ansible.parsing.plugin_docsr �ansible.parsing.utils.yamlr �ansible.parsing.yaml.dumperr �ansible.plugins.listr r r � ansible.utils.collection_loaderr r �2ansible.utils.collection_loader._collection_finderr �ansible.utils.colorr �ansible.utils.displayr �ansible.utils.plugin_docsr r r r; r� r r\ r] r r� r� r� rD �objectrE r� r� r� r� r� rG r� rB rB rB rC �<module> s� �� 3 =- & �
Save
Cancel