two version of R2R are here HEAD master

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())