diff options
Diffstat (limited to '.venv/lib/python3.12/site-packages/boto3/docs/service.py')
| -rw-r--r-- | .venv/lib/python3.12/site-packages/boto3/docs/service.py | 202 |
1 files changed, 202 insertions, 0 deletions
diff --git a/.venv/lib/python3.12/site-packages/boto3/docs/service.py b/.venv/lib/python3.12/site-packages/boto3/docs/service.py new file mode 100644 index 00000000..39ed89b8 --- /dev/null +++ b/.venv/lib/python3.12/site-packages/boto3/docs/service.py @@ -0,0 +1,202 @@ +# Copyright 2015 Amazon.com, Inc. or its affiliates. All Rights Reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"). You +# may not use this file except in compliance with the License. A copy of +# the License is located at +# +# https://aws.amazon.com/apache2.0/ +# +# or in the "license" file accompanying this file. This file is +# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF +# ANY KIND, either express or implied. See the License for the specific +# language governing permissions and limitations under the License. +import os + +from botocore.docs.bcdoc.restdoc import DocumentStructure +from botocore.docs.service import ServiceDocumenter as BaseServiceDocumenter +from botocore.exceptions import DataNotFoundError + +import boto3 +from boto3.docs.client import Boto3ClientDocumenter +from boto3.docs.resource import ResourceDocumenter, ServiceResourceDocumenter +from boto3.utils import ServiceContext + + +class ServiceDocumenter(BaseServiceDocumenter): + # The path used to find examples + EXAMPLE_PATH = os.path.join(os.path.dirname(boto3.__file__), 'examples') + + def __init__(self, service_name, session, root_docs_path): + super().__init__( + service_name=service_name, + # I know that this is an internal attribute, but the botocore session + # is needed to load the paginator and waiter models. + session=session._session, + root_docs_path=root_docs_path, + ) + self._boto3_session = session + self._client = self._boto3_session.client(service_name) + self._service_resource = None + if self._service_name in self._boto3_session.get_available_resources(): + self._service_resource = self._boto3_session.resource(service_name) + self.sections = [ + 'title', + 'client', + 'paginators', + 'waiters', + 'resources', + 'examples', + 'context-params', + ] + self._root_docs_path = root_docs_path + self._USER_GUIDE_LINK = ( + 'https://boto3.amazonaws.com/' + 'v1/documentation/api/latest/guide/resources.html' + ) + + def document_service(self): + """Documents an entire service. + + :returns: The reStructured text of the documented service. + """ + doc_structure = DocumentStructure( + self._service_name, section_names=self.sections, target='html' + ) + self.title(doc_structure.get_section('title')) + + self.client_api(doc_structure.get_section('client')) + self.paginator_api(doc_structure.get_section('paginators')) + self.waiter_api(doc_structure.get_section('waiters')) + if self._service_resource: + self.resource_section(doc_structure.get_section('resources')) + self._document_examples(doc_structure.get_section('examples')) + context_params_section = doc_structure.get_section('context-params') + self.client_context_params(context_params_section) + return doc_structure.flush_structure() + + def client_api(self, section): + examples = None + try: + examples = self.get_examples(self._service_name) + except DataNotFoundError: + pass + + Boto3ClientDocumenter( + self._client, self._root_docs_path, examples + ).document_client(section) + + def resource_section(self, section): + section.style.h2('Resources') + section.style.new_line() + section.write( + 'Resources are available in boto3 via the ' + '``resource`` method. For more detailed instructions ' + 'and examples on the usage of resources, see the ' + 'resources ' + ) + section.style.external_link( + title='user guide', + link=self._USER_GUIDE_LINK, + ) + section.write('.') + section.style.new_line() + section.style.new_line() + section.write('The available resources are:') + section.style.new_line() + section.style.toctree() + self._document_service_resource(section) + self._document_resources(section) + + def _document_service_resource(self, section): + # Create a new DocumentStructure for each Service Resource and add contents. + service_resource_doc = DocumentStructure( + 'service-resource', target='html' + ) + breadcrumb_section = service_resource_doc.add_new_section('breadcrumb') + breadcrumb_section.style.ref( + self._client.__class__.__name__, f'../../{self._service_name}' + ) + breadcrumb_section.write(' / Resource / ServiceResource') + ServiceResourceDocumenter( + self._service_resource, self._session, self._root_docs_path + ).document_resource(service_resource_doc) + # Write collections in individual/nested files. + # Path: <root>/reference/services/<service>/<resource_name>/<collection_name>.rst + resource_name = self._service_resource.meta.resource_model.name + if resource_name == self._service_name: + resource_name = 'service-resource' + service_resource_dir_path = os.path.join( + self._root_docs_path, + f'{self._service_name}', + f'{resource_name.lower()}', + ) + service_resource_doc.write_to_file(service_resource_dir_path, 'index') + section.style.tocitem(f'{self._service_name}/{resource_name}/index') + + def _document_resources(self, section): + temp_identifier_value = 'foo' + loader = self._session.get_component('data_loader') + json_resource_model = loader.load_service_model( + self._service_name, 'resources-1' + ) + service_model = self._service_resource.meta.client.meta.service_model + for resource_name in json_resource_model['resources']: + resource_model = json_resource_model['resources'][resource_name] + resource_cls = ( + self._boto3_session.resource_factory.load_from_definition( + resource_name=resource_name, + single_resource_json_definition=resource_model, + service_context=ServiceContext( + service_name=self._service_name, + resource_json_definitions=json_resource_model[ + 'resources' + ], + service_model=service_model, + service_waiter_model=None, + ), + ) + ) + identifiers = resource_cls.meta.resource_model.identifiers + args = [] + for _ in identifiers: + args.append(temp_identifier_value) + resource = resource_cls(*args, client=self._client) + # Create a new DocumentStructure for each Resource and add contents. + resource_name = resource.meta.resource_model.name.lower() + resource_doc = DocumentStructure(resource_name, target='html') + breadcrumb_section = resource_doc.add_new_section('breadcrumb') + breadcrumb_section.style.ref( + self._client.__class__.__name__, f'../../{self._service_name}' + ) + breadcrumb_section.write( + f' / Resource / {resource.meta.resource_model.name}' + ) + ResourceDocumenter( + resource, self._session, self._root_docs_path + ).document_resource( + resource_doc.add_new_section(resource.meta.resource_model.name) + ) + # Write collections in individual/nested files. + # Path: <root>/reference/services/<service>/<resource_name>/<index>.rst + service_resource_dir_path = os.path.join( + self._root_docs_path, + f'{self._service_name}', + f'{resource_name}', + ) + resource_doc.write_to_file(service_resource_dir_path, 'index') + section.style.tocitem( + f'{self._service_name}/{resource_name}/index' + ) + + def _get_example_file(self): + return os.path.realpath( + os.path.join(self.EXAMPLE_PATH, self._service_name + '.rst') + ) + + def _document_examples(self, section): + examples_file = self._get_example_file() + if os.path.isfile(examples_file): + section.style.h2('Examples') + section.style.new_line() + with open(examples_file) as f: + section.write(f.read()) |