U
    N8Úc«3  ã                   @   s|   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 )é    )ÚOrderedDict)Ú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-ozje0y8b/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d kri | _| j jjj| _d S ©N)Ú_clientÚ_shared_examplesÚmetaÚservice_modelr   Ú_service_name)ÚselfÚclientÚshared_examplesr   r   r   Ú__init__$   s
    
zClientDocumenter.__init__c                 C   s8   |   |¡ |  |¡ |  ¡ }|  ||¡ |  ||¡ 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_client+   s
    

z ClientDocumenter.document_clientc                 C   s   t | jƒ}|  |¡S r   )r   r   Ú_filter_client_methods)r   r"   r   r   r   r   6   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'   F   s
    


z&ClientDocumenter._filter_client_methodc                 C   s   |j  d¡ d S )NZClient©ÚstyleÚh2©r   r!   r   r   r   r   P   s    zClientDocumenter._add_titlec                 C   s¢   |  d¡}t| jjjƒ}| d|› ¡ |j ¡  | | jjjj	¡ |  
|¡ |j ¡  | d¡ |j ¡  | jjj}t|ƒD ]}|j d|› d|› d¡ q~d S )NZintroz A low-level client representing z These are the available methods:z:py:meth:`~z.Client.ú`)Úadd_new_sectionr
   r   r   r   Úwriter,   Únew_lineÚinclude_doc_stringÚdocumentationÚ_add_client_creation_exampleÚ	__class__Ú__name__ÚsortedÚli)r   r!   r"   Zofficial_service_nameÚ
class_namer   r   r   r   r   S   s$    
ÿÿ

ÿ




z"ClientDocumenter._add_client_introc                 C   s   |j j| jjj› dd d S )Nz.Client©r:   )r,   Ústart_sphinx_py_classr   r6   r7   r.   r   r   r   r   l   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)r,   Ústart_codeblockr2   r1   Úformatr   Úend_codeblockr.   r   r   r   r5   q   s    

ÿÿz-ClientDocumenter._add_client_creation_examplec                 C   s.   |  d¡}t|ƒD ]}|  |||| ¡ qd S )NÚmethods)r0   r8   Ú_add_client_method)r   r!   r"   r   r   r   r   r    {   s    
  ÿz$ClientDocumenter._add_client_methodsc                 C   s4   |  |¡}|  |¡r$|  |||¡ n|  ||¡ d S r   )r0   Ú_is_custom_methodÚ_add_custom_methodÚ_add_model_driven_method©r   r!   r   r%   r   r   r   rA   ‚   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   rB   ‰   s    z"ClientDocumenter._is_custom_methodc                 C   s   t |||ƒ d S r   )r   rE   r   r   r   rC   Œ   s    z#ClientDocumenter._add_custom_methodc                 C   sd   |  d¡}|j ¡  |j d¡ |j ¡  | jjj}|jD ]$}|› d|j› }|j 	d| ¡ q:d S )NÚ
exceptionsZ
Exceptionsú.Client.exceptions.ú:py:class:`%s`)
r0   r,   r2   Úboldr   r6   r7   Úerror_shapesÚnamer9   )r   r!   Úoperation_modelZerror_sectionZclient_nameÚerrorr:   r   r   r   Ú_add_method_exceptions_list   s    




z,ClientDocumenter._add_method_exceptions_listc                 C   sz   | j jj}| j jj| }| |¡}d| }t|||| j jj|j|d |jrX|  	||¡ | j
 |¡}|rvt||||ƒ d S )Nzresponse = client.%s)Úevent_emitterZmethod_descriptionÚexample_prefix)r   r   r   rF   rM   r   Úeventsr4   rK   rO   r   Úgetr   )r   r!   r   r   Úoperation_namerM   rQ   r   r   r   r   rD   ™   s,    

ú
   ÿz)ClientDocumenter._add_model_driven_method)N)r7   Ú
__module__Ú__qualname__r   r)   r   r#   r   r$   r'   r   r   r   r5   r    rA   rB   rC   rO   rD   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.)rL   Ú	type_namer4   ÚMessagez;A descriptive message explaining why the exception occured.)rL   rZ   r4   Úmembersc                 C   s   || _ | j jjj| _d S 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   s   |j  d¡ d S )NzClient Exceptionsr+   r.   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Ú.)r,   r2   r1   Zexternal_linkÚ_USER_GUIDE_LINKr.   r   r   r   r]   å   s    
ÿþ
z(ClientExceptionsDocumenter._add_overviewc                 C   s   | j jj}|› d|j› S )NrH   )r   r6   r7   rL   )r   ÚshapeZcls_namer   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 d| ¡ qTd S )Nz-This client has no modeled exception classes.z$The available client exceptions are:rI   )	r   r   r   rK   r,   r2   r1   rf   r9   )r   r!   rK   re   r:   r   r   r   r^   ø   s    






z/ClientExceptionsDocumenter._add_exceptions_listc                 C   s"   | j jjjD ]}|  ||¡ qd S r   )r   r   r   rK   Ú_add_exception_class©r   r!   re   r   r   r   r_     s    z1ClientExceptionsDocumenter._add_exception_classesc                 C   sV   |  |j¡}|  |¡}|jj|d |  ||¡ |  ||¡ |  ||¡ |j ¡  d S )Nr;   )	r0   rL   rf   r,   r<   Ú_add_top_level_documentationÚ_add_exception_catch_exampleÚ_add_response_attrZend_sphinx_py_class)r   r!   re   Zclass_sectionr:   r   r   r   rg   
  s    
z/ClientExceptionsDocumenter._add_exception_classc                 C   s*   |j r&|j ¡  | |j ¡ |j ¡  d S r   )r4   r,   r2   r3   rh   r   r   r   ri     s    
z7ClientExceptionsDocumenter._add_top_level_documentationc                 C   s¢   |j  ¡  |j  d¡ |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))	r,   r2   rJ   r=   r1   ÚindentÚdedentrL   r?   rh   r   r   r   rj     s    











z7ClientExceptionsDocumenter._add_exception_catch_examplec                 C   sF   |  d¡}|j d¡ |  |¡ |  ||¡ |  ||¡ |j ¡  d S )NÚresponse)r0   r,   Zstart_sphinx_py_attrÚ_add_response_attr_descriptionÚ_add_response_exampleÚ_add_response_paramsZend_sphinx_py_attr)r   r!   re   Zresponse_sectionr   r   r   rk   *  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.)r,   r2   r3   r.   r   r   r   ro   2  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   rT   rP   ©r(   )r0   r,   r2   rJ   Únew_paragraphr   r   r   r   rR   Zdocument_exampleÚ_GENERIC_ERROR_SHAPE)r   r!   re   Zexample_sectionÚ
documenterr   r   r   rp   <  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Ú	Structurerr   rs   )r0   r,   r2   rJ   rt   r   r   r   r   rR   Zdocument_paramsru   )r   r!   re   Zparams_sectionrv   r   r   r   rq   L  s    


ýýz/ClientExceptionsDocumenter._add_response_paramsN)r7   rU   rV   rd   r	   r   ru   r   r`   r   r]   rf   r^   r_   rg   ri   rj   rk   ro   rp   rq   r   r   r   r   rW   ´   sL   ÿüþüþõÿü	
rW   N)Zbotocore.compatr   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   rW   r   r   r   r   Ú<module>   s    