
    ge<                         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	 Z G d
 d          Z G 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                     | dk    rd S |dv S )Ngenerate_presigned_url)s3 )method_nameservice_namekwargss      4lib/python3.11/site-packages/botocore/docs/client.py!_allowlist_generate_presigned_urlr      s    ...t6!!    c                   p    e Zd ZegZddZd Zd Zd Zd Z	d Z
d Zd	 Zd
 Zd Zd Zd Zd Zd Zd ZdS )ClientDocumenterNc                     || _         | j         j        j        | _        || _        || _        | j        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_exampless       r   __init__zClientDocumenter.__init__'   sS    "&,"8"A- / ($&D!!\.<Ir   c                     |                      |           |                     |           |                                 }|                     ||           |                     |           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_methodss      r   document_clientz ClientDocumenter.document_client0   sk    
 	   !!'***1133w777  00000r   c                 T    t          | j                  }|                     |          S r   )r   r   _filter_client_methods)r$   r0   s     r   r,   z$ClientDocumenter._get_client_methods;   s%    4T\BB**>:::r   c                     i }|                                 D ])\  }}|                     ||| j                  }|r|||<   *|S )N)methodr   r   )items_filter_client_methodr#   )r$   r0   filtered_methodsr   r5   includes         r   r3   z'ClientDocumenter._filter_client_methods?   sj    #1#7#7#9#9 	7 	7K00'!/ 1  G
  706 -r   c                 6    | j         D ]} |di |}||c S dS )NTr   )_CLIENT_METHODS_FILTERS)r$   r   filterfilter_includes       r   r7   z&ClientDocumenter._filter_client_methodK   sG    2 	& 	&F#V--f--N)%%%% * tr   c                 :    |j                             d           d S )NClientstyleh2r$   r/   s     r   r*   zClientDocumenter._add_titleU   s    """""r   c                 v   |                     d          }t          | j        j        j                  }|                    d|            |j                                         |                    | j        j        j        j	                   | 
                    |           |j                                         |j                                         |                    d           |j                                         t          |          D ]&}|j                            | j         d|            'd S )Nintroz A low-level client representing z These are the available methods:z/client/)add_new_sectionr   r   r!   r"   writerA   new_lineinclude_doc_stringdocumentation_add_client_creation_examplededentnew_paragraphwritelntoctreesortedtocitemr#   )r$   r/   r0   official_service_namer   s        r   r-   z"ClientDocumenter._add_client_introX   sF   ))'22 9L+!
 !
 	F/DFF	
 	
 	
 	   ""L+9	
 	
 	

 	))'222 	##%%%:;;;!.11 	P 	PKM!!T%7"N"N"N"NOOOO	P 	Pr   c                 L    |j                             | j         d           d S )Nz.Client
class_name)rA   start_sphinx_py_classr   rC   s     r   r+   z%ClientDocumenter._add_class_signatureq   s:    ++1::: 	, 	
 	
 	
 	
 	
r   c                     |j                                          |j                                          |                    d                    | j                             |j                                          d S )Nz+client = session.create_client('{service}'))service)rA   start_codeblockrH   rG   formatr#   end_codeblockrC   s     r   rK   z-ClientDocumenter._add_client_creation_examplev   s{    %%'''   ;BB* C  	
 	
 	

 	##%%%%%r   c                    t          |          D ]q}t          |d          }|                     ||||                    t          j                            | j        | j        d          }|                    ||           rd S )Nhtmltargetr%   )	rP   r   _add_client_methodospathjoinr   r#   write_to_file)r$   r0   r   method_doc_structureclient_dir_paths        r   r.   z$ClientDocumenter._add_client_methods   s    !.11 	M 	MK#4F$ $ $  ##$k>+3N  
 !gll$d&8( O !..LLLL	M 	Mr   c                    |                     d          }|j                            | j        d| j                    |                    d|            |                    |           |                     |d| j         di          }|                     |          r|                     |||           d S | 	                    ||           d S )N
breadcrumbz../../z / Client / 	qualifierz.Client.)context)
rF   rA   refr   r#   rG   add_title_section_is_custom_method_add_custom_method_add_model_driven_method)r$   r/   r   r5   breadcrumb_sectionmethod_sections         r   r`   z#ClientDocumenter._add_client_method   s   $44\BB $$#%Bd.@%B%B	
 	
 	
 	  !=!=!=>>>!!+... 00 T%<"F"F"FG 1 
 
 !!+.. 	G##     )).+FFFFFr   c                 (    || j         j        j        vS r   )r   r!   method_to_api_mapping)r$   r   s     r   rm   z"ClientDocumenter._is_custom_method   s    $,"3"IIIr   c                 (    t          |||           d S r   )r   )r$   r/   r   r5   s       r   rn   z#ClientDocumenter._add_custom_method   s    wV<<<<<r   c                 8   |                     d          }|j                                         |j                            d           |j                                         |j        D ]0}| j         d|j         }|j                            d|z             1d S )N
exceptions
Exceptions.Client.exceptions.z:py:class:`%s`)rF   rA   rH   bolderror_shapesr   nameli)r$   r/   operation_modelerror_sectionerrorrU   s         r   _add_method_exceptions_listz,ClientDocumenter._add_method_exceptions_list   s    //==$$&&&  ...$$&&&$1 	B 	BE*KKuzKK  ""#3j#@AAAA		B 	Br   c                    | j         j        j        }| j         j        j        |         }|                    |          }d|z  }|j                            dd           | }t          |||| j         j        j        |j	        |           |j
        r|                     ||           | j                            |          }|rt          ||||           d S d S )Nzresponse = client.%sri    )event_emittermethod_descriptionexample_prefix)r   r!   r"   rs   r}   rj   getr   eventsrJ   rz   r   r    r
   )	r$   r/   r   r"   operation_namer}   r   full_method_namer'   s	            r   ro   z)ClientDocumenter._add_model_driven_method   s   )7*@M'77GG/+="";33B[BB 	 	%,+2.<)	
 	
 	
 	
 ' 	G,,WoFFF /33NCC 	$./    	 	r   r   )r   
__module____qualname__r   r;   r(   r1   r,   r3   r7   r*   r-   r+   rK   r.   r`   rm   rn   r   ro   r   r   r   r   r   "   s       )J J J J	1 	1 	1; ; ;
  
  
   # # #P P P2
 
 

& & &M M M G G G(J J J= = =	B 	B 	B    r   r   c                       e Zd ZdZ eddd ed eddd          fd	 ed	dd
          fg                    Zd Zd Zd Z	d Z
d Zd Zd Zd Zd Zd Zd Zd Zd Z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.)r{   	type_namerJ   Messagez;A descriptive message explaining why the exception occured.)r{   r   rJ   membersc                     || _         | j         j        j        | _        | j         j        j        j        | _        || _        d S r   )	r   r   r   r   r!   r"   r   r#   r   )r$   r%   r&   s      r   r(   z#ClientExceptionsDocumenter.__init__   s:    "&,"8"A!\.<I-r   c                     |                      |           |                     |           |                     |           |                                  d S r   )r*   _add_overview_add_exceptions_list_add_exception_classesrC   s     r   document_exceptionsz.ClientExceptionsDocumenter.document_exceptions   sT       7###!!'***##%%%%%r   c                 :    |j                             d           d S )NzClient Exceptionsr@   rC   s     r   r*   z%ClientExceptionsDocumenter._add_title  s    ,-----r   c                     |j                                          |                    d           |j                             d| j                   |                    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.)rA   rH   rG   external_link_USER_GUIDE_LINKrC   s     r   r   z(ClientExceptionsDocumenter._add_overview  s       	
 	
 	
 	##& 	$ 	
 	
 	
 	c     r   c                 $    | j          d|j         S )Nrx   )r   r{   )r$   shapes     r   _exception_class_namez0ClientExceptionsDocumenter._exception_class_name  s    )JJejJJJr   c                    | j         j        j        j        }|sI|j                                         |                    d           |j                                         d S |j                                         |                    d           |j                                         |D ]+}|j        	                    | j
         d|j                    ,d S )Nz-This client has no modeled exception classes.z$The available client exceptions are:z/client/exceptions/)r   r!   r"   rz   rA   rH   rG   rN   rO   rQ   r#   r{   )r$   r/   rz   r   s       r   r   z/ClientExceptionsDocumenter._add_exceptions_list  s    |(6C 	M""$$$MMIJJJM""$$$F   >???! 	 	EM!!%FF%*FF   	 	r   c                    | j         j        j        j        D ]u}t	          |j        d          }|                     ||           t          j        	                    | j
        | j        dd          }|                    ||j                   vd S )Nr]   r^   r%   rv   )r   r!   r"   rz   r   r{   _add_exception_classra   rb   rc   r   r#   rd   )r$   r   exception_doc_structureexception_dir_paths       r   r   z1ClientExceptionsDocumenter._add_exception_classes'  s    \&4A 	 	E&7
6' ' '# %%&=uEEE "$$"	" " $11"EJ   	 	r   c                 8   |                     d          }|j                            | j        d| j                    |                    d|j                    |                    |j                   |                     |j                  }|                     |          }|j        	                    |           | 
                    ||           |                     ||           |                     ||           |j                                         d S )Nrh   z	../../../z / Client / exceptions / rT   )rF   rA   rk   r   r#   rG   r{   rl   r   rV   _add_top_level_documentation_add_exception_catch_example_add_response_attrend_sphinx_py_class)r$   r/   r   rp   class_sectionrU   s         r   r   z/ClientExceptionsDocumenter._add_exception_class:  s   $44\BB $$#%E1C%E%E	
 	
 	
 	  !IUZ!I!IJJJ!!%*---//
;;//66
11Z1HHH))-???))-???u555//11111r   c                     |j         rN|j                                         |                    |j                    |j                                         d S d S r   )rJ   rA   rH   rI   r$   r/   r   s      r   r   z7ClientExceptionsDocumenter._add_top_level_documentationI  s\     	%M""$$$&&u':;;;M""$$$$$	% 	%r   c                    |j                                          |j                             d           |j                                          |j                                          |                    d           |j                                          |j                                          |                    d           |j                                          |j                                          |                    d|j        z             |j                                          |j                                          |                    d           |j                                          |j         	                                 d S )NExampleztry:z...z!except client.exceptions.%s as e:zprint(e.response))
rA   rH   ry   rM   rY   rG   indentrL   r{   r[   r   s      r   r   z7ClientExceptionsDocumenter._add_exception_catch_exampleO  sK      9%%%##%%%%%'''f   e   9EJFGGG   )***##%%%%%r   c                    |                     d          }|j                            d           |                     |           |                     ||           |                     ||           |j                                         d S )Nresponse)rF   rA   start_sphinx_py_attr_add_response_attr_description_add_response_example_add_response_paramsend_sphinx_py_attr)r$   r/   r   response_sections       r   r   z-ClientExceptionsDocumenter._add_response_attra  s    "22:>>33J???++,<===""#3U;;;!!"2E:::1133333r   c                     |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.)rA   rH   rI   rC   s     r   r   z9ClientExceptionsDocumenter._add_response_attr_descriptioni  sO       ""*	
 	
 	
 	     r   c                 P   |                     d          }|j                                         |j                            d           |j                                         t          | j        d | j        j        j	                  }|
                    ||| j        g           d S )NsyntaxSyntaxr   r   r   r9   )rF   rA   rH   ry   rM   r   r#   r   r!   r   document_example_GENERIC_ERROR_SHAPE)r$   r/   r   example_section
documenters        r   r   z0ClientExceptionsDocumenter._add_response_examples  s    !11(;;&&(((""8,,,++---.+,+2
 
 


 	##./ 	$ 	
 	
 	
 	
 	
r   c                 P   |                     d          }|j                                         |j                            d           |j                                         t          | j        d | j        j        j	                  }|
                    ||| j        g           d S )N	Structurer   r   )rF   rA   rH   ry   rM   r	   r#   r   r!   r   document_paramsr   )r$   r/   r   params_sectionr   s        r   r   z/ClientExceptionsDocumenter._add_response_params  s     00==%%'''!!+...**,,,-+,+2
 
 


 	""./ 	# 	
 	
 	
 	
 	
r   N)r   r   r   r   r   r   r   r(   r   r*   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r      sz       	@  +?J #O#"*J	  	 #O&"*'	  

 
	  >. . .& & &. . .! ! !K K K    &2 2 2% % %& & &$4 4 4! ! !
 
 
 
 
 
 
 
r   r   )ra   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   <module>r      s2   
			 ' ' ' ' ' ' 9 9 9 9 9 9 ; ; ; ; ; ;         
 : 9 9 9 9 9 @ @ @ @ @ @ J J J J J J J J" " "n n n n n n n nb~
 ~
 ~
 ~
 ~
 ~
 ~
 ~
 ~
 ~
r   