python-boto3/tests/unit/docs/__init__.py

# 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 json
import os
import shutil
import tempfile

import botocore.session
from botocore.compat import OrderedDict
from botocore.docs.bcdoc.restdoc import DocumentStructure
from botocore.loaders import Loader

from boto3.session import Session
from tests import unittest


class BaseDocsTest(unittest.TestCase):
    def setUp(self):
        self.root_dir = tempfile.mkdtemp()
        self.version_dirs = os.path.join(
            self.root_dir, 'myservice', '2014-01-01'
        )
        os.makedirs(self.version_dirs)

        self.model_file = os.path.join(self.version_dirs, 'service-2.json')
        self.waiter_model_file = os.path.join(
            self.version_dirs, 'waiters-2.json'
        )
        self.paginator_model_file = os.path.join(
            self.version_dirs, 'paginators-1.json'
        )
        self.resource_model_file = os.path.join(
            self.version_dirs, 'resources-1.json'
        )
        self.example_model_file = os.path.join(
            self.version_dirs, 'examples-1.json'
        )

        self.json_model = {}
        self.waiter_json_model = {}
        self.paginator_json_model = {}
        self.resource_json_model = {}
        self._setup_models()

        self.doc_name = 'MyDoc'
        self.doc_structure = DocumentStructure(self.doc_name)

        self.setup_client_and_resource()

    def tearDown(self):
        shutil.rmtree(self.root_dir)

    def setup_client_and_resource(self):
        self._write_models()
        self.loader = Loader(extra_search_paths=[self.root_dir])
        self.botocore_session = botocore.session.get_session()
        self.botocore_session.register_component('data_loader', self.loader)
        self.session = Session(
            botocore_session=self.botocore_session, region_name='us-east-1'
        )
        self.client = self.session.client('myservice', 'us-east-1')
        self.resource = self.session.resource('myservice', 'us-east-1')

    def _setup_models(self):
        self.json_model = {
            'metadata': {
                'apiVersion': '2014-01-01',
                'endpointPrefix': 'myservice',
                'signatureVersion': 'v4',
                'serviceFullName': 'AWS MyService',
                'protocol': 'query',
                'serviceId': 'MyService',
            },
            'operations': {
                'SampleOperation': {
                    'name': 'SampleOperation',
                    'input': {'shape': 'SampleOperationInputOutput'},
                    'output': {'shape': 'SampleOperationInputOutput'},
                }
            },
            'shapes': {
                'SampleOperationInputOutput': {
                    'type': 'structure',
                    'members': OrderedDict(
                        [
                            (
                                'Foo',
                                {
                                    'shape': 'String',
                                    'documentation': 'Documents Foo',
                                },
                            ),
                            (
                                'Bar',
                                {
                                    'shape': 'String',
                                    'documentation': 'Documents Bar',
                                },
                            ),
                        ]
                    ),
                },
                'String': {'type': 'string'},
            },
        }

        self.example_json_model = {
            "version": 1,
            "examples": {
                "SampleOperation": [
                    {
                        "id": "sample-id",
                        "title": "sample-title",
                        "description": "Sample Description.",
                        "input": OrderedDict(
                            [
                                ("Foo", "bar"),
                            ]
                        ),
                        "comments": {
                            "input": {"Foo": "biz"},
                        },
                    }
                ]
            },
        }

        self.waiter_json_model = {
            "version": 2,
            "waiters": {
                "SampleOperationComplete": {
                    "delay": 15,
                    "operation": "SampleOperation",
                    "maxAttempts": 40,
                    "acceptors": [
                        {
                            "expected": "complete",
                            "matcher": "pathAll",
                            "state": "success",
                            "argument": "Biz",
                        },
                        {
                            "expected": "failed",
                            "matcher": "pathAny",
                            "state": "failure",
                            "argument": "Biz",
                        },
                    ],
                }
            },
        }

        self.paginator_json_model = {
            "pagination": {
                "SampleOperation": {
                    "input_token": "NextResult",
                    "output_token": "NextResult",
                    "limit_key": "MaxResults",
                    "result_key": "Biz",
                }
            }
        }

        self.resource_json_model = {
            "service": {
                "actions": OrderedDict(
                    [
                        (
                            "SampleOperation",
                            {"request": {"operation": "SampleOperation"}},
                        ),
                        (
                            "SampleListReturnOperation",
                            {
                                "request": {"operation": "SampleOperation"},
                                "resource": {
                                    "type": "Sample",
                                    "identifiers": [
                                        {
                                            "target": "Name",
                                            "source": "response",
                                            "path": "Samples[].Name",
                                        }
                                    ],
                                    "path": "Samples[]",
                                },
                            },
                        ),
                    ]
                ),
                "has": {
                    "Sample": {
                        "resource": {
                            "type": "Sample",
                            "identifiers": [
                                {"target": "Name", "source": "input"}
                            ],
                        }
                    }
                },
                "hasMany": {
                    "Samples": {
                        "request": {"operation": "SampleOperation"},
                        "resource": {
                            "type": "Sample",
                            "identifiers": [
                                {
                                    "target": "Name",
                                    "source": "response",
                                    "path": "Samples[].Foo",
                                }
                            ],
                        },
                    }
                },
            },
            "resources": {
                "Sample": {
                    "identifiers": [{"name": "Name", "memberName": "Foo"}],
                    "shape": "SampleOperationInputOutput",
                    "load": {
                        "request": {
                            "operation": "SampleOperation",
                            "params": [
                                {
                                    "target": "Foo",
                                    "source": "identifier",
                                    "name": "Name",
                                }
                            ],
                        }
                    },
                    "actions": {
                        "Operate": {
                            "request": {
                                "operation": "SampleOperation",
                                "params": [
                                    {
                                        "target": "Foo",
                                        "source": "identifier",
                                        "name": "Name",
                                    }
                                ],
                            }
                        }
                    },
                    "batchActions": {
                        "Operate": {
                            "request": {
                                "operation": "SampleOperation",
                                "params": [
                                    {
                                        "target": "Samples[].Foo",
                                        "source": "identifier",
                                        "name": "Name",
                                    }
                                ],
                            }
                        }
                    },
                    "has": {
                        "RelatedSample": {
                            "resource": {
                                "type": "Sample",
                                "identifiers": [
                                    {
                                        "target": "Name",
                                        "source": "data",
                                        "path": "Foo",
                                    }
                                ],
                            }
                        }
                    },
                    "waiters": {
                        "Complete": {
                            "waiterName": "SampleOperationComplete",
                            "params": [
                                {
                                    "target": "Foo",
                                    "source": "identifier",
                                    "name": "Name",
                                }
                            ],
                        }
                    },
                }
            },
        }

    def _write_models(self):
        with open(self.resource_model_file, 'w') as f:
            json.dump(self.resource_json_model, f)

        with open(self.waiter_model_file, 'w') as f:
            json.dump(self.waiter_json_model, f)

        with open(self.paginator_model_file, 'w') as f:
            json.dump(self.paginator_json_model, f)

        with open(self.model_file, 'w') as f:
            json.dump(self.json_model, f)

        with open(self.example_model_file, 'w') as f:
            json.dump(self.example_json_model, f)

    def add_shape(self, shape):
        shape_name = list(shape.keys())[0]
        self.json_model['shapes'][shape_name] = shape[shape_name]

    def add_shape_to_params(
        self, param_name, shape_name, documentation=None, is_required=False
    ):
        params_shape = self.json_model['shapes']['SampleOperationInputOutput']
        member = {'shape': shape_name}
        if documentation is not None:
            member['documentation'] = documentation
        params_shape['members'][param_name] = member

        if is_required:
            required_list = params_shape.get('required', [])
            required_list.append(param_name)
            params_shape['required'] = required_list

    def assert_contains_lines_in_order(self, lines, contents=None):
        if contents is None:
            contents = self.doc_structure.flush_structure().decode('utf-8')
        for line in lines:
            assert line in contents
            beginning = contents.find(line)
            contents = contents[(beginning + len(line)) :]

    def assert_not_contains_lines(self, lines):
        contents = self.doc_structure.flush_structure().decode('utf-8')
        for line in lines:
            assert line not in contents