1# Copyright 2015 Amazon.com, Inc. or its affiliates. All Rights Reserved.
2#
3# Licensed under the Apache License, Version 2.0 (the "License"). You
4# may not use this file except in compliance with the License. A copy of
5# the License is located at
6#
7# https://aws.amazon.com/apache2.0/
8#
9# or in the "license" file accompanying this file. This file is
10# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
11# ANY KIND, either express or implied. See the License for the specific
12# language governing permissions and limitations under the License.
13from botocore import xform_name
14from botocore.model import OperationModel
15from botocore.utils import get_service_module_name
16from botocore.docs.method import document_model_driven_method
17from botocore.docs.method import document_custom_method
18
19from boto3.docs.base import BaseDocumenter
20from boto3.docs.method import document_model_driven_resource_method
21from boto3.docs.utils import get_resource_ignore_params
22from boto3.docs.utils import get_resource_public_actions
23from boto3.docs.utils import add_resource_type_overview
24
25
26class ActionDocumenter(BaseDocumenter):
27    def document_actions(self, section):
28        modeled_actions_list = self._resource_model.actions
29        modeled_actions = {}
30        for modeled_action in modeled_actions_list:
31            modeled_actions[modeled_action.name] = modeled_action
32        resource_actions = get_resource_public_actions(
33            self._resource.__class__)
34        self.member_map['actions'] = sorted(resource_actions)
35        add_resource_type_overview(
36            section=section,
37            resource_type='Actions',
38            description=(
39                'Actions call operations on resources.  They may '
40                'automatically handle the passing in of arguments set '
41                'from identifiers and some attributes.'),
42            intro_link='actions_intro')
43
44        for action_name in sorted(resource_actions):
45            action_section = section.add_new_section(action_name)
46            if action_name in ['load', 'reload'] and self._resource_model.load:
47                document_load_reload_action(
48                    section=action_section,
49                    action_name=action_name,
50                    resource_name=self._resource_name,
51                    event_emitter=self._resource.meta.client.meta.events,
52                    load_model=self._resource_model.load,
53                    service_model=self._service_model
54                )
55            elif action_name in modeled_actions:
56                document_action(
57                    section=action_section,
58                    resource_name=self._resource_name,
59                    event_emitter=self._resource.meta.client.meta.events,
60                    action_model=modeled_actions[action_name],
61                    service_model=self._service_model,
62                )
63            else:
64                document_custom_method(
65                    action_section, action_name, resource_actions[action_name])
66
67
68def document_action(section, resource_name, event_emitter, action_model,
69                    service_model, include_signature=True):
70    """Documents a resource action
71
72    :param section: The section to write to
73
74    :param resource_name: The name of the resource
75
76    :param event_emitter: The event emitter to use to emit events
77
78    :param action_model: The model of the action
79
80    :param service_model: The model of the service
81
82    :param include_signature: Whether or not to include the signature.
83        It is useful for generating docstrings.
84    """
85    operation_model = service_model.operation_model(
86        action_model.request.operation)
87    ignore_params = get_resource_ignore_params(action_model.request.params)
88
89    example_return_value = 'response'
90    if action_model.resource:
91        example_return_value = xform_name(action_model.resource.type)
92    example_resource_name = xform_name(resource_name)
93    if service_model.service_name == resource_name:
94        example_resource_name = resource_name
95    example_prefix = '%s = %s.%s' % (
96        example_return_value, example_resource_name, action_model.name)
97    document_model_driven_resource_method(
98        section=section, method_name=action_model.name,
99        operation_model=operation_model,
100        event_emitter=event_emitter,
101        method_description=operation_model.documentation,
102        example_prefix=example_prefix,
103        exclude_input=ignore_params,
104        resource_action_model=action_model,
105        include_signature=include_signature
106    )
107
108
109def document_load_reload_action(section, action_name, resource_name,
110                                event_emitter, load_model, service_model,
111                                include_signature=True):
112    """Documents the resource load action
113
114    :param section: The section to write to
115
116    :param action_name: The name of the loading action should be load or reload
117
118    :param resource_name: The name of the resource
119
120    :param event_emitter: The event emitter to use to emit events
121
122    :param load_model: The model of the load action
123
124    :param service_model: The model of the service
125
126    :param include_signature: Whether or not to include the signature.
127        It is useful for generating docstrings.
128    """
129    description = (
130        'Calls  :py:meth:`%s.Client.%s` to update the attributes of the'
131        ' %s resource. Note that the load and reload methods are '
132        'the same method and can be used interchangeably.' % (
133            get_service_module_name(service_model),
134            xform_name(load_model.request.operation),
135            resource_name)
136    )
137    example_resource_name = xform_name(resource_name)
138    if service_model.service_name == resource_name:
139        example_resource_name = resource_name
140    example_prefix = '%s.%s' % (example_resource_name, action_name)
141    document_model_driven_method(
142        section=section, method_name=action_name,
143        operation_model=OperationModel({}, service_model),
144        event_emitter=event_emitter,
145        method_description=description,
146        example_prefix=example_prefix,
147        include_signature=include_signature
148    )
149