aboutsummaryrefslogtreecommitdiff
path: root/.venv/lib/python3.12/site-packages/boto3/docs/service.py
diff options
context:
space:
mode:
authorS. Solomon Darnell2025-03-28 21:52:21 -0500
committerS. Solomon Darnell2025-03-28 21:52:21 -0500
commit4a52a71956a8d46fcb7294ac71734504bb09bcc2 (patch)
treeee3dc5af3b6313e921cd920906356f5d4febc4ed /.venv/lib/python3.12/site-packages/boto3/docs/service.py
parentcc961e04ba734dd72309fb548a2f97d67d578813 (diff)
downloadgn-ai-master.tar.gz
two version of R2R are hereHEADmaster
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.py202
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())