/usr/lib/python3/dist-packages/boto3/docs/resource.py is in python3-boto3 1.4.2-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 | # 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
#
# http://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.
from botocore import xform_name
from botocore.docs.utils import get_official_service_name
from boto3.docs.base import BaseDocumenter
from boto3.docs.action import ActionDocumenter
from boto3.docs.waiter import WaiterResourceDocumenter
from boto3.docs.collection import CollectionDocumenter
from boto3.docs.subresource import SubResourceDocumenter
from boto3.docs.attr import document_attribute
from boto3.docs.attr import document_identifier
from boto3.docs.attr import document_reference
from boto3.docs.utils import get_identifier_args_for_signature
from boto3.docs.utils import get_identifier_values_for_example
from boto3.docs.utils import get_identifier_description
from boto3.docs.utils import add_resource_type_overview
class ResourceDocumenter(BaseDocumenter):
def __init__(self, resource, botocore_session):
super(ResourceDocumenter, self).__init__(resource)
self._botocore_session = botocore_session
def document_resource(self, section):
self._add_title(section)
self._add_intro(section)
overview_section = section.add_new_section('member-overview')
self._add_identifiers(section)
self._add_attributes(section)
self._add_references(section)
self._add_actions(section)
self._add_sub_resources(section)
self._add_collections(section)
self._add_waiters(section)
self._add_overview_of_members(overview_section)
def _add_title(self, section):
section.style.h2(self._resource_name)
def _add_intro(self, section):
identifier_names = []
if self._resource_model.identifiers:
for identifier in self._resource_model.identifiers:
identifier_names.append(identifier.name)
# Write out the class signature.
class_args = get_identifier_args_for_signature(identifier_names)
section.style.start_sphinx_py_class(
class_name='%s(%s)' % (self.class_name, class_args))
# Add as short description about the resource
description_section = section.add_new_section('description')
self._add_description(description_section)
# Add an example of how to instantiate the resource
example_section = section.add_new_section('example')
self._add_example(example_section, identifier_names)
# Add the description for the parameters to instantiate the
# resource.
param_section = section.add_new_section('params')
self._add_params_description(param_section, identifier_names)
def _add_description(self, section):
official_service_name = get_official_service_name(
self._service_model)
section.write(
'A resource representing an %s %s' % (
official_service_name, self._resource_name))
def _add_example(self, section, identifier_names):
section.style.start_codeblock()
section.style.new_line()
section.write('import boto3')
section.style.new_line()
section.style.new_line()
section.write(
'%s = boto3.resource(\'%s\')' % (
self._service_name, self._service_name)
)
section.style.new_line()
example_values = get_identifier_values_for_example(identifier_names)
section.write(
'%s = %s.%s(%s)' % (
xform_name(self._resource_name), self._service_name,
self._resource_name, example_values))
section.style.end_codeblock()
def _add_params_description(self, section, identifier_names):
for identifier_name in identifier_names:
description = get_identifier_description(
self._resource_name, identifier_name)
section.write(':type %s: string' % identifier_name)
section.style.new_line()
section.write(':param %s: %s' % (
identifier_name, description))
section.style.new_line()
def _add_overview_of_members(self, section):
for resource_member_type in self.member_map:
section.style.new_line()
section.write('These are the resource\'s available %s:' % (
resource_member_type))
section.style.new_line()
for member in self.member_map[resource_member_type]:
if resource_member_type in ['identifiers', 'attributes',
'references', 'collections']:
section.style.li(':py:attr:`%s`' % member)
else:
section.style.li(':py:meth:`%s()`' % member)
def _add_identifiers(self, section):
identifiers = self._resource.meta.resource_model.identifiers
section = section.add_new_section('identifiers')
member_list = []
if identifiers:
self.member_map['identifiers'] = member_list
add_resource_type_overview(
section=section,
resource_type='Identifiers',
description=(
'Identifiers are properties of a resource that are '
'set upon instantation of the resource.'),
intro_link='identifiers_attributes_intro')
for identifier in identifiers:
identifier_section = section.add_new_section(identifier.name)
member_list.append(identifier.name)
document_identifier(
section=identifier_section,
resource_name=self._resource_name,
identifier_model=identifier
)
def _add_attributes(self, section):
service_model = self._resource.meta.client.meta.service_model
attributes = {}
if self._resource.meta.resource_model.shape:
shape = service_model.shape_for(
self._resource.meta.resource_model.shape)
attributes = self._resource.meta.resource_model.get_attributes(
shape)
section = section.add_new_section('attributes')
attribute_list = []
if attributes:
add_resource_type_overview(
section=section,
resource_type='Attributes',
description=(
'Attributes provide access'
' to the properties of a resource. Attributes are lazy-'
'loaded the first time one is accessed via the'
' :py:meth:`load` method.'),
intro_link='identifiers_attributes_intro')
self.member_map['attributes'] = attribute_list
for attr_name in sorted(attributes):
_, attr_shape = attributes[attr_name]
attribute_section = section.add_new_section(attr_name)
attribute_list.append(attr_name)
document_attribute(
section=attribute_section,
service_name=self._service_name,
resource_name=self._resource_name,
attr_name=attr_name,
event_emitter=self._resource.meta.client.meta.events,
attr_model=attr_shape
)
def _add_references(self, section):
section = section.add_new_section('references')
references = self._resource.meta.resource_model.references
reference_list = []
if references:
add_resource_type_overview(
section=section,
resource_type='References',
description=(
'References are related resource instances that have '
'a belongs-to relationship.'),
intro_link='references_intro')
self.member_map['references'] = reference_list
for reference in references:
reference_section = section.add_new_section(reference.name)
reference_list.append(reference.name)
document_reference(
section=reference_section,
reference_model=reference
)
def _add_actions(self, section):
section = section.add_new_section('actions')
actions = self._resource.meta.resource_model.actions
if actions:
documenter = ActionDocumenter(self._resource)
documenter.member_map = self.member_map
documenter.document_actions(section)
def _add_sub_resources(self, section):
section = section.add_new_section('sub-resources')
sub_resources = self._resource.meta.resource_model.subresources
if sub_resources:
documenter = SubResourceDocumenter(self._resource)
documenter.member_map = self.member_map
documenter.document_sub_resources(section)
def _add_collections(self, section):
section = section.add_new_section('collections')
collections = self._resource.meta.resource_model.collections
if collections:
documenter = CollectionDocumenter(self._resource)
documenter.member_map = self.member_map
documenter.document_collections(section)
def _add_waiters(self, section):
section = section.add_new_section('waiters')
waiters = self._resource.meta.resource_model.waiters
if waiters:
service_waiter_model = self._botocore_session.get_waiter_model(
self._service_name)
documenter = WaiterResourceDocumenter(
self._resource, service_waiter_model)
documenter.member_map = self.member_map
documenter.document_resource_waiters(section)
class ServiceResourceDocumenter(ResourceDocumenter):
@property
def class_name(self):
return '%s.ServiceResource' % self._service_docs_name
def _add_title(self, section):
section.style.h2('Service Resource')
def _add_description(self, section):
official_service_name = get_official_service_name(
self._service_model)
section.write(
'A resource representing %s' % official_service_name)
def _add_example(self, section, identifier_names):
section.style.start_codeblock()
section.style.new_line()
section.write('import boto3')
section.style.new_line()
section.style.new_line()
section.write(
'%s = boto3.resource(\'%s\')' % (
self._service_name, self._service_name))
section.style.end_codeblock()
|