Google
Edit File: plugin_docs.cpython-39.pyc
a �)g�: � @ s d dl mZmZmZ eZd dlmZmZm Z d dl m Z d dl m Z d dlmZ d dlmZmZmZ d dlmZ d dlmZ d d lmZ d d l m Z d d l m Z e � Z d d � Z!dd� Z"d"dd�Z#d#dd�Z$d$dd�Z%d%dd�Z&dd� Z'd d � Z(d d � Z)d d!� Z*dS )&� )�absolute_import�division�print_function)�MutableMapping� MutableSet�MutableSequence)�Path)� constants)� __version__)� AnsibleError�AnsibleParserError�AnsiblePluginNotFound)� string_types)� to_native)�read_docstring)� AnsibleLoader)�Displayc C s� |� � D ]�\}}|| v r�t| | t�r6|�| | � nNt| | t�rT|�| | � n0t| | t�rxtt|| | ��}n t d| ��|| |< qd S )Nz?Attempt to extend a documentation fragment, invalid type for %s) �items� isinstancer �updater �addr �sorted� frozenset� Exception)�target�source�key�value� r �=/usr/lib/python3.9/site-packages/ansible/utils/plugin_docs.py�merge_fragment s r c s� d� �fdd� �� �fdd��� ����fdd��� �fdd ��� fd d �}| sTd S |rd�| � d S d | v rx� | d d � t | �d�t�r��| d dd� t | �d�t�r��| d � t | �d�t�r�|| d � d S )NFc sj |rdnd}t | t�sd S �s"|r6d| v r6� | d|� d| v rJ� | d|� �sf|sfd| v rf� | d|� d S )NZremoved_from_collection�collection_nameZ removed_inZremoved_at_date�version)r r )Z deprecation� top_levelr! )�callback� is_moduler r �process_deprecation' s z8_process_versions_and_dates.<locals>.process_deprecationc sJ | D ]@}t |t�sqd|v r(� |dd� t |�d�t�r�|d � qd S )N� version_added�version_added_collection� deprecated)r r �get)Z specifiersZ specifier)r$ r& r r �process_option_specifiers2 s z>_process_versions_and_dates.<locals>.process_option_specifiersc s� | � � D ]�}t|t�sqd|v r,� |dd� �s�t|�d�t�rL�|d � t|�d�t�rh�|d � t|�d�t�r��|d � t|�d�t�r��|d � t|�d�t�r�|d � qd S )Nr' r( �envZini�varsr) Z suboptions)�valuesr r r* �list)�options�option)r$ r% r& r+ �process_optionsr r r2 ; s z4_process_versions_and_dates.<locals>.process_optionsc sN | � � D ]@}t|t�sqd|v r,� |dd� t|�d�t�r�|d � qd S )Nr' r( �contains)r. r r r* )Z return_valuesZ return_value)r$ �process_return_valuesr r r4 M s z:_process_versions_and_dates.<locals>.process_return_valuesc s2 | � � D ]$}t|t�sqd|v r� |dd� qd S )Nr' r( )r. r r )� attributesZ attribute)r$ r r �process_attributesV s z7_process_versions_and_dates.<locals>.process_attributesr' r( r) T)r# r0 r5 )F)r r* r )�fragmentr% � return_docsr$ r6 r )r$ r% r& r+ r2 r4 r �_process_versions_and_dates& s$ r9 Fc s � fdd�}t | |||� d S )Nc s || vr� | |< d S �Nr �r0 r1 Zcollection_name_field�r! r r r o s z1add_collection_to_versions_and_dates.<locals>.add�r9 )r7 r! r% r8 r r r< r �$add_collection_to_versions_and_datesn s r> c s � fdd�}t | |||� d S )Nc s | � |�� kr| |= d S r: )r* r; r< r r �removew s zAremove_current_collection_from_versions_and_dates.<locals>.remover= )r7 r! r% r8 r? r r< r �1remove_current_collection_from_versions_and_datesv s r@ c C s� | � dg �}t|t�r |g}g }|D �]J}|}d}|�|�} | d u rvd|v rv|�dd�} | d }| d �� }|�|�} | d u r�|�|� q$t| |d �} | d u r�|dkr�|�|� q$nd} t| |d�� � } t| d�} d| v r�d� | � d�dd � �nd }t | ||d � d | v �r>| � d �}|�r>d | v�r0g | d < | d � |� d | v �rx| � d �}|�rxd | v�rjg | d < | d � |� d| v�r�d| v�r�td||f ��dD ]�}|| v �r�|| v �rzt| | | � |�� W n> t�y } z$tdt|�|||f ��W Y d }~n d }~0 0 n| � |�| |< �q�zt| | � W q$ t�yn } z"tdt|�||f ��W Y d }~q$d }~0 0 q$|�r�td�|td� |�����d S )NZ extends_documentation_fragmentZ DOCUMENTATION�.� r z{})� file_nameZ ansible_name� � �r% �notes�seealsor0 r5 zJmissing options or attributes in fragment (%s), possibly misformatted?: %s)r0 r5 z %s %s (%s) of unknown type: %sz%s (%s) of unknown type: %sz(unknown doc_fragment(s) in file {0}: {1}z, )�popr r r* �rsplit�upper�append�getattrr Zget_single_data�join�splitr> �extendr r r r �format)�doc�filename�fragment_loaderr% Z fragmentsZunknown_fragmentsZ fragment_slugZ fragment_nameZ fragment_varZfragment_classZ splitnameZ fragment_yamlr7 Zreal_fragment_nameZreal_collection_namerG rH Zdoc_key�er r r � add_fragments~ sl $ 0.rV Nc C s� |du r |du rd}q |dk}n t | ||d�}|�dd�rh|durTt|d ||d� t|d | ||d� |�dd�r�|dur�t|d ||d d � |d |d |d |d fS ) z� DOCUMENTATION can be extended using documentation fragments loaded by the PluginLoader from the doc_fragments plugins. NF�module)�verbose� ignore_errorsrR rF )rT r% Z returndocsT)r% r8 Z plainexamples�metadata)r r* r> rV )rS rT rX rY r! r% � plugin_type�datar r r � get_docstring� s r] c s t | �} z�tj�d�}|�d�s(|d7 }| �d�r>| dd� } t�d�� t� �dk rbt d� t���d� � d � d �}� d �d �r�t � fd d �dD ��s�t� �dkr�d� d v r�d}d� ||| �W S t � y� } z d� | t |��W Y d}~S d}~0 0 dS )a� returns a versioned documentation link for the current Ansible major.minor version; used to generate in-product warning/error links to the configured DOCSITE_ROOT_URL (eg, https://docs.ansible.com/ansible/2.8/somepath/doc.html) :param path: relative path to a document under docs/docsite/rst; :return: absolute URL to the specified doc for the current version of Ansible ZDOCSITE_ROOT_URL�/rB NrA � zinvalid version ({0})z{0}.{1}r rD �0c 3 s | ]}|� d v V qdS )rD Nr )�.0Zpre�Z split_verr r � <genexpr> � z(get_versioned_doclink.<locals>.<genexpr>)�a�b�devZdevelz {0}{1}/{2}z7(unable to create versioned doc link for path {0}: {1})) r �CZconfigZget_config_value�endswith� startswith�ansible_versionrO �len� RuntimeErrorrQ �anyr )�pathZbase_urlZ doc_version�exr rb r �get_versioned_doclink� s" .rq c C sf t | �}|�d�d }|j|kr*|�|�}g }|D ].}|�|�}||krJq2|�� r2|�t|�� q2|S )NrA ���)r rO �stem� with_name� with_suffix�existsrL r )ro �plugin� extensionsZadjacentZplugin_base_name�paths�ext� candidater r r �_find_adjacent s r| c C s� |j | ddd�}|r|js0|dv r0|�| �\}}|r:|jsJtd| |d��t|j�}|jtjvr�t || tj�}|rz|d nd}nt |�}|du r�t d | ��||j fS ) zn if the plugin lives in a non-python file (eg, win_X.ps1), require the corresponding 'sidecar' file for docs FT)Zignore_deprecatedZ check_aliases)�filter�testz%s was not found)Zplugin_load_contextr NzO%s cannot contain DOCUMENTATION nor does it have a companion documentation file) Zfind_plugin_with_contextZresolvedZget_with_contextr r Zplugin_resolved_path�suffixrh �DOC_EXTENSIONSr| r r Zplugin_resolved_collection)rw r[ �loader�contextZ plugin_objZdocfile� filenamesrS r r r �find_plugin_docfile' s r� c C s" g }t | ||�\}}zt|||||d�}W n8 tyb } z td| |f |d��W Y d }~n d }~0 0 |d s�t|| tj�D ]j} z,t| ||||d�}| }|d d ur�W q�W qz ty� } z td| |f |d��W Y d }~qzd }~0 0 qz|d d u �rtd| |f ��n||d d< ||d d< |S ) N)rX r! r[ z1%s did not contain a DOCUMENTATION attribute (%s))Zorig_excr z?Adjacent file %s did not contain a DOCUMENTATION attribute (%s)z&No documentation available for %s (%s)rS Z collection)r� r] r r r| rh r� ) rw r[ r� rT rX ZdocsrS r! rU Znewfiler r r �get_plugin_docs@ s( * , r� )F)F)F)FFNNN)+Z __future__r r r �typeZ __metaclass__�collections.abcr r r �pathlibr Zansibler rh Zansible.releaser rk Zansible.errorsr r r Zansible.module_utils.sixr Zansible.module_utils._textr Zansible.parsing.plugin_docsr Zansible.parsing.yaml.loaderr Zansible.utils.displayr Zdisplayr r9 r> r@ rV r] rq r| r� r� r r r r �<module> s, H R "