U
    mª/eÄ<  ã                   @   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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dS )é    N)Ú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kS )NZgenerate_presigned_url)Zs3© )Úmethod_nameÚservice_nameÚkwargsr   r   ú8/tmp/pip-unpacked-wheel-3gylhwtm/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 k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_client0   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(   Zfiltered_methodsr   r+   Úincluder   r   r   r*   ?   s    ý
z'ClientDocumenter._filter_client_methodsc                 K   s*   | j D ]}|f |Ž}|d k	r|  S qdS )NT)Ú_CLIENT_METHODS_FILTERS)r   r   ÚfilterZfilter_includer   r   r   r-   K   s
    


z&ClientDocumenter._filter_client_methodc                 C   s   |j  d¡ d S )NZClient©ÚstyleÚh2©r   r'   r   r   r   r"   U   s    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 )NZintroz A low-level client representing z These are the available methods:z/client/)Úadd_new_sectionr   r   r   r   Úwriter2   Únew_lineÚinclude_doc_stringÚdocumentationÚ_add_client_creation_exampleÚdedentÚnew_paragraphÚwritelnÚtoctreeÚsortedÚtocitemr   )r   r'   r(   Zofficial_service_namer   r   r   r   r%   X   s$    
ÿÿ

ÿ




z"ClientDocumenter._add_client_introc                 C   s   |j j| j› dd d S )Nz.Client©Ú
class_name)r2   Ústart_sphinx_py_classr   r4   r   r   r   r#   q   s    
ÿz%ClientDocumenter._add_class_signaturec                 C   s6   |j  ¡  |j  ¡  | dj| jd¡ |j  ¡  d S )Nz+client = session.create_client('{service}'))Zservice)r2   Ústart_codeblockr7   r6   Úformatr   Úend_codeblockr4   r   r   r   r:   v   s    

ÿÿz-ClientDocumenter._add_client_creation_examplec                 C   sP   t |ƒD ]B}t|dd}|  |||| ¡ tj | j| jd¡}| ||¡ qd S )NÚhtml©Útargetr   )	r?   r   Ú_add_client_methodÚosÚpathÚjoinr   r   Úwrite_to_file)r   r(   r   Zmethod_doc_structureZ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}|  |¡rp|  |||¡ n|  	||¡ d S )NÚ
breadcrumbz../../z / Client / Ú	qualifierz.Client.)Úcontext)
r5   r2   Úrefr   r   r6   Úadd_title_sectionÚ_is_custom_methodÚ_add_custom_methodÚ_add_model_driven_method)r   r'   r   r+   Úbreadcrumb_sectionZmethod_sectionr   r   r   rJ      s$    
 
ÿ
þ
ýz#ClientDocumenter._add_client_methodc                 C   s   || j jjkS r   )r   r   Úmethod_to_api_mapping)r   r   r   r   r   rT   ¤   s    z"ClientDocumenter._is_custom_methodc                 C   s   t |||ƒ d S r   )r   )r   r'   r   r+   r   r   r   rU   §   s    z#ClientDocumenter._add_custom_methodc                 C   s\   |  d¡}|j ¡  |j d¡ |j ¡  |jD ]&}| j› d|j› }|j d| ¡ q0d S )NÚ
exceptionsZ
Exceptionsú.Client.exceptions.z:py:class:`%s`)r5   r2   r7   ÚboldÚerror_shapesr   ÚnameÚli)r   r'   Úoperation_modelZerror_sectionÚerrorrB   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
rn|  ||¡ | j |¡}|rŒt||||ƒ d S )Nzresponse = client.%srP   Ú )Úevent_emitterZmethod_descriptionÚexample_prefix)r   r   r   rX   r_   rQ   Úgetr   Úeventsr9   r\   ra   r   r	   )	r   r'   r   r   Úoperation_namer_   rd   Zfull_method_namer    r   r   r   rV   µ   s0    

ÿú
   ÿz)ClientDocumenter._add_model_driven_method)N)r   Ú
__module__Ú__qualname__r   r/   r!   r)   r$   r*   r-   r"   r%   r#   r:   r&   rJ   rT   rU   ra   rV   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ÚErrorZ	structurez1Normalized access to common exception attributes.ZCodeÚstringz,An identifier specifying the exception type.)r]   Ú	type_namer9   ÚMessagez;A descriptive message explaining why the exception occured.)r]   rm   r9   Ú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_classesr4   r   r   r   Údocument_exceptionsý   s    


z.ClientExceptionsDocumenter.document_exceptionsc                 C   s   |j  d¡ d S )NzClient Exceptionsr1   r4   r   r   r   r"     s    z%ClientExceptionsDocumenter._add_titlec                 C   s>   |j  ¡  | d¡ |j jd| jd | d¡ |j  ¡  d S )NzÂClient 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Ú.)r2   r7   r6   Zexternal_linkÚ_USER_GUIDE_LINKr4   r   r   r   rp     s    
ÿþ
z(ClientExceptionsDocumenter._add_overviewc                 C   s   | j › d|j› S )NrZ   )r   r]   )r   Úshaper   r   r   Ú_exception_class_name  s    z0ClientExceptionsDocumenter._exception_class_namec                 C   sx   | j jjj}|s2|j ¡  | d¡ |j ¡  d S |j ¡  | d¡ |j ¡  |D ]}|j 	| j
› d|j› ¡ qTd S )Nz-This client has no modeled exception classes.z$The available client exceptions are:z/client/exceptions/)r   r   r   r\   r2   r7   r6   r=   r>   r@   r   r]   )r   r'   r\   rx   r   r   r   rq     s    





ÿz/ClientExceptionsDocumenter._add_exceptions_listc                 C   sT   | j jjjD ]B}t|jdd}|  ||¡ tj 	| j
| jdd¡}| ||j¡ qd S )NrG   rH   r   rY   )r   r   r   r\   r   r]   Ú_add_exception_classrK   rL   rM   r   r   rN   )r   rx   Zexception_doc_structureZexception_dir_pathr   r   r   rr   '  s      ÿü ÿz1ClientExceptionsDocumenter._add_exception_classesc                 C   s–   |  d¡}|j | jd| j› ¡ | d|j› ¡ | |j¡ |  |j¡}|  |¡}|jj	|d |  
||¡ |  ||¡ |  ||¡ |j ¡  d S )NrO   z	../../../z / Client / exceptions / rA   )r5   r2   rR   r   r   r6   r]   rS   ry   rC   Ú_add_top_level_documentationÚ_add_exception_catch_exampleÚ_add_response_attrZend_sphinx_py_class)r   r'   rx   rW   Zclass_sectionrB   r   r   r   rz   :  s    
 
ÿ
z/ClientExceptionsDocumenter._add_exception_classc                 C   s*   |j r&|j ¡  | |j ¡ |j ¡  d S r   )r9   r2   r7   r8   ©r   r'   rx   r   r   r   r{   I  s    
z7ClientExceptionsDocumenter._add_top_level_documentationc                 C   s¬   |j  ¡  |j  d¡ |j  ¡  |j  ¡  | d¡ |j  ¡  |j  ¡  | d¡ |j  ¡  |j  ¡  | d|j ¡ |j  ¡  |j  ¡  | d¡ |j  ¡  |j  	¡  d S )NZExampleztry:z...z!except client.exceptions.%s as e:zprint(e.response))
r2   r7   r[   r<   rD   r6   Úindentr;   r]   rF   r~   r   r   r   r|   O  s     












z7ClientExceptionsDocumenter._add_exception_catch_examplec                 C   sF   |  d¡}|j d¡ |  |¡ |  ||¡ |  ||¡ |j ¡  d S )NÚresponse)r5   r2   Zstart_sphinx_py_attrÚ_add_response_attr_descriptionÚ_add_response_exampleÚ_add_response_paramsZend_sphinx_py_attr)r   r'   rx   Zresponse_sectionr   r   r   r}   a  s    

z-ClientExceptionsDocumenter._add_response_attrc                 C   s"   |j  ¡  | d¡ |j  ¡  d S )NzÈThe 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.)r2   r7   r8   r4   r   r   r   r   i  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 )NZsyntaxZSyntax©r   rg   rc   ©r.   )r5   r2   r7   r[   r<   r   r   r   r   rf   Zdocument_exampleÚ_GENERIC_ERROR_SHAPE)r   r'   rx   Zexample_sectionÚ
documenterr   r   r   r‚   s  s    


ýý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…   )r5   r2   r7   r[   r<   r   r   r   r   rf   Zdocument_paramsr†   )r   r'   rx   Zparams_sectionr‡   r   r   r   rƒ   ƒ  s    


ýýz/ClientExceptionsDocumenter._add_response_paramsN)r   rh   ri   rw   r
   r   r†   r!   rs   r"   rp   ry   rq   rr   rz   r{   r|   r}   r   r‚   rƒ   r   r   r   r   rj   Ó   sL   ÿüþüþõÿü
rj   )rK   Zbotocore.compatr   Zbotocore.docs.bcdoc.restdocr   Zbotocore.docs.exampler   Zbotocore.docs.methodr   r   r   Zbotocore.docs.paramsr   Zbotocore.docs.sharedexampler	   Zbotocore.docs.utilsr
   r   r   r   rj   r   r   r   r   Ú<module>   s    2