o
    VfC                     @   s   d dl Z d dlmZ d dlmZ d dlmZ d dlmZ d dl	m
Z
mZmZ d dlmZ d dlmZ d d	lmZmZ d
d ZG dd dZG dd dZG dd dZdS )    N)
xform_name)OrderedDict)DocumentStructure)ResponseExampleDocumenter)document_custom_methoddocument_model_driven_methodget_instance_public_methods)ResponseParamsDocumenter)document_shared_examples)DocumentedShapeget_official_service_namec                 K   s   | dkrd S |dv S )Ngenerate_presigned_url)s3 )method_nameservice_namekwargsr   r   U/home/ubuntu/oakencloud.com/venv/lib/python3.10/site-packages/botocore/docs/client.py!_allowlist_generate_presigned_url   s   r   c                   @   s   e Zd ZegZd ddZdd Zdd Zdd	 Zd
d Z	dd Z
dd Zdd Zdd Zdd Zdd Zdd Zdd Zdd Zdd ZdS )!ClientDocumenterNc                 C   s@   || _ | j jj| _|| _|| _| jd u ri | _| j jjj| _	d S N)
_client	__class____name___client_class_name_root_docs_path_shared_examplesmetaservice_modelr   _service_name)selfclientroot_docs_pathshared_examplesr   r   r   __init__(   s   
zClientDocumenter.__init__c                 C   s6   |  | | | |  }| || | | dS )z]Documents a client and its methods

        :param section: The section to write to.
        N)
_add_title_add_class_signature_get_client_methods_add_client_intro_add_client_methods)r    sectionclient_methodsr   r   r   document_client1   s
   

z ClientDocumenter.document_clientc                 C   s   t | j}| |S r   )r   r   _filter_client_methods)r    r+   r   r   r   r'   <   s   

z$ClientDocumenter._get_client_methodsc                 C   s8   i }|  D ]\}}| j||| jd}|r|||< q|S )N)methodr   r   )items_filter_client_methodr   )r    r+   filtered_methodsr   r.   includer   r   r   r-   @   s   z'ClientDocumenter._filter_client_methodsc                 K   s.   | j D ]}|di |}|d ur|  S qdS )NTr   )_CLIENT_METHODS_FILTERS)r    r   filterfilter_includer   r   r   r0   L   s   
z&ClientDocumenter._filter_client_methodc                 C      |j d d S )NClientstyleh2r    r*   r   r   r   r%   V      zClientDocumenter._add_titlec                 C   s   | d}t| jjj}|d|  |j  || jjjj	 | 
| |j  |j  |d |j  t|D ]}|j| j d|  q?d S )Nintroz A low-level client representing z These are the available methods:z/client/)add_new_sectionr   r   r   r   writer9   new_lineinclude_doc_stringdocumentation_add_client_creation_examplededentnew_paragraphwritelntoctreesortedtocitemr   )r    r*   r+   official_service_namer   r   r   r   r(   Y   s&   







z"ClientDocumenter._add_client_introc                 C   s   |j j| j dd d S )Nz.Client
class_name)r9   start_sphinx_py_classr   r;   r   r   r   r&   r   s   

z%ClientDocumenter._add_class_signaturec                 C   s6   |j   |j   |d| j d |j   d S )Nz client = session.create_client('z'))r9   start_codeblockr@   r?   r   end_codeblockr;   r   r   r   rC   w   s   

z-ClientDocumenter._add_client_creation_examplec                 C   sP   t |D ]!}t|dd}| ||||  tj| j| jd}||| qd S )Nhtmltargetr!   )	rH   r   _add_client_methodospathjoinr   r   write_to_file)r    r+   r   method_doc_structureclient_dir_pathr   r   r   r)      s   

z$ClientDocumenter._add_client_methodsc                 C   s   | d}|j| jd| j  |d|  || |j |d| j did}| |r9| ||| d S | 	|| d S )N
breadcrumbz../../z / Client / 	qualifierz.Client.)context)
r>   r9   refr   r   r?   add_title_section_is_custom_method_add_custom_method_add_model_driven_method)r    r*   r   r.   breadcrumb_sectionmethod_sectionr   r   r   rS      s"   


z#ClientDocumenter._add_client_methodc                 C   s   || j jjvS r   )r   r   method_to_api_mapping)r    r   r   r   r   r_      s   z"ClientDocumenter._is_custom_methodc                 C   s   t ||| d S r   )r   )r    r*   r   r.   r   r   r   r`      r<   z#ClientDocumenter._add_custom_methodc                 C   s`   | d}|j  |jd |j  |jD ]}| j d|j }|jd| d qd S )N
exceptions
Exceptions.Client.exceptions.z:py:class:``)r>   r9   r@   bolderror_shapesr   nameli)r    r*   operation_modelerror_sectionerrorrL   r   r   r   _add_method_exceptions_list   s   



z,ClientDocumenter._add_method_exceptions_listc           	      C   s   | j jj}| j jj| }||}d| }|jdd | }t|||| j jj|j	|d |j
r8| || | j|}|rIt|||| d S d S )Nzresponse = client.r[    )event_emittermethod_descriptionexample_prefix)r   r   r   rd   rm   r\   getr   eventsrB   rj   rp   r   r
   )	r    r*   r   r   operation_namerm   rt   full_method_namer#   r   r   r   ra      s,   



z)ClientDocumenter._add_model_driven_methodr   )r   
__module____qualname__r   r3   r$   r,   r'   r-   r0   r%   r(   r&   rC   r)   rS   r_   r`   rp   ra   r   r   r   r   r   #   s$    
	
r   c                   @   s   e Zd ZdZedddededdddfd	ed	dd
dfgdZdd Zdd Zdd Z	dd Z
dd Zdd Zdd Zdd Zdd Zdd Zd d! Zd"d# Zd$d% Zd&d' Zd(S ))ClientExceptionsDocumenterzQhttps://boto3.amazonaws.com/v1/documentation/api/latest/guide/error-handling.htmlError	structurez1Normalized access to common exception attributes.Codestringz,An identifier specifying the exception type.)rk   	type_namerB   Messagez;A descriptive message explaining why the exception occured.)rk   r   rB   membersc                 C   s*   || _ | j jj| _| j jjj| _|| _d S r   )	r   r   r   r   r   r   r   r   r   )r    r!   r"   r   r   r   r$      s   
z#ClientExceptionsDocumenter.__init__c                 C   s*   |  | | | | | |   d S r   )r%   _add_overview_add_exceptions_list_add_exception_classesr;   r   r   r   document_exceptions   s   


z.ClientExceptionsDocumenter.document_exceptionsc                 C   r6   )NzClient Exceptionsr8   r;   r   r   r   r%     r<   z%ClientExceptionsDocumenter._add_titlec                 C   >   |j   |d |j jd| jd |d |j   d S )NzClient exceptions are available on a client instance via the ``exceptions`` property. For more detailed instructions and examples on the exact usage of client exceptions, see the error handling z
user guidetitlelink.)r9   r@   r?   external_link_USER_GUIDE_LINKr;   r   r   r   r        

z(ClientExceptionsDocumenter._add_overviewc                 C   s   | j  d|j S )Nrg   )r   rk   )r    shaper   r   r   _exception_class_name  s   z0ClientExceptionsDocumenter._exception_class_namec                 C   sx   | j jjj}|s|j  |d |j  d S |j  |d |j  |D ]}|j	| j
 d|j  q*d S )Nz-This client has no modeled exception classes.z$The available client exceptions are:z/client/exceptions/)r   r   r   rj   r9   r@   r?   rF   rG   rI   r   rk   )r    r*   rj   r   r   r   r   r     s   





z/ClientExceptionsDocumenter._add_exceptions_listc                 C   sT   | j jjjD ]!}t|jdd}| || tj	| j
| jdd}|||j qd S )NrP   rQ   r!   re   )r   r   r   rj   r   rk   _add_exception_classrT   rU   rV   r   r   rW   )r    r   exception_doc_structureexception_dir_pathr   r   r   r   &  s   z1ClientExceptionsDocumenter._add_exception_classesc                 C   s   | d}|j| jd| j  |d|j  ||j | |j}| |}|jj	|d | 
|| | || | || |j  d S )NrZ   z	../../../z / Client / exceptions / rK   )r>   r9   r]   r   r   r?   rk   r^   r   rM   _add_top_level_documentation_add_exception_catch_example_add_response_attrend_sphinx_py_class)r    r*   r   rb   class_sectionrL   r   r   r   r   9  s   

z/ClientExceptionsDocumenter._add_exception_classc                 C   s.   |j r|j  ||j  |j  d S d S r   )rB   r9   r@   rA   r    r*   r   r   r   r   r   H  s
   
z7ClientExceptionsDocumenter._add_top_level_documentationc                 C   s   |j   |j d |j   |j   |d |j   |j   |d |j   |j   |d|j d |j   |j   |d |j   |j 	  d S )NExampleztry:z...zexcept client.exceptions.z as e:zprint(e.response))
r9   r@   ri   rE   rN   r?   indentrD   rk   rO   r   r   r   r   r   N  s    












z7ClientExceptionsDocumenter._add_exception_catch_examplec                 C   sF   | d}|jd | | | || | || |j  d S )Nresponse)r>   r9   start_sphinx_py_attr_add_response_attr_description_add_response_example_add_response_paramsend_sphinx_py_attr)r    r*   r   response_sectionr   r   r   r   `  s   

z-ClientExceptionsDocumenter._add_response_attrc                 C   s"   |j   |d |j   d S )NzThe parsed error response. All exceptions have a top level ``Error`` key that provides normalized access to common exception atrributes. All other keys are specific to this service or exception class.)r9   r@   rA   r;   r   r   r   r   h  s
   
z9ClientExceptionsDocumenter._add_response_attr_descriptionc                 C   sX   | d}|j  |jd |j  t| jd | jjj	d}|j
||| jgd d S )NsyntaxSyntaxr   rw   rr   r2   )r>   r9   r@   ri   rE   r   r   r   r   rv   document_example_GENERIC_ERROR_SHAPE)r    r*   r   example_section
documenterr   r   r   r   r     



z0ClientExceptionsDocumenter._add_response_examplec                 C   sX   | d}|j  |jd |j  t| jd | jjj	d}|j
||| jgd d S )N	Structurer   r   )r>   r9   r@   ri   rE   r	   r   r   r   rv   document_paramsr   )r    r*   r   params_sectionr   r   r   r   r     r   z/ClientExceptionsDocumenter._add_response_paramsN)r   ry   rz   r   r   r   r   r$   r   r%   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r{      sN    
r{   c                   @   sB   e Zd ZdZdddZdd Zdd Zd	d
 Zdd Zdd Z	dS )ClientContextParamsDocumenterzPhttps://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html)
AccelerateDisableMultiRegionAccessPointsForcePathStyleUseArnRegion)r   )r   	s3controlc                 C   s   || _ || _d S r   )r   _context_params)r    r   context_paramsr   r   r   r$     s   
z&ClientContextParamsDocumenter.__init__c                 C   s"   |  | | | | | d S r   )r%   r   _add_context_params_listr;   r   r   r   document_context_params  s   

z5ClientContextParamsDocumenter.document_context_paramsc                 C   r6   )NzClient Context Parametersr8   r;   r   r   r   r%     r<   z(ClientContextParamsDocumenter._add_titlec                 C   r   )NzClient context parameters are configurable on a client instance via the ``client_context_params`` parameter in the ``Config`` object. For more detailed instructions and examples on the exact usage of context params see the zconfiguration guider   r   )r9   r@   r?   r   _CONFIG_GUIDE_LINKr;   r   r   r   r     r   z+ClientContextParamsDocumenter._add_overviewc              	   C   sv   |j   d| j d}|d| d | jD ] }|j   dt|j d}|d| d|j d|j	  qd S )Nz``zThe available z client context params are:z* z (z) - )
r9   r@   r   rF   r   r   rk   r?   typerB   )r    r*   snparamrk   r   r   r   r     s   


"z6ClientContextParamsDocumenter._add_context_params_listN)
r   ry   rz   r   OMITTED_CONTEXT_PARAMSr$   r   r%   r   r   r   r   r   r   r     s    
r   )rT   botocorer   botocore.compatr   botocore.docs.bcdoc.restdocr   botocore.docs.exampler   botocore.docs.methodr   r   r   botocore.docs.paramsr	   botocore.docs.sharedexampler
   botocore.docs.utilsr   r   r   r   r{   r   r   r   r   r   <module>   s    0 B