def handle_paginators(client_name, class_name, service_name, service_path,
sidebar_lines):
try:
model = botocore.session.get_session().get_paginator_model(client_name)
except botocore.exceptions.UnknownServiceError:
return
paginator_config = model._paginator_config
if not paginator_config:
return
paginator_names = list(paginator_config.keys())
if not paginator_names:
return
paginators_path = f'{service_path}/paginators'
sidebar_lines.append(f' - [Paginators]({paginators_path})')
docs_paginators_path = f'docs/{paginators_path}.md'
example_paginator_name = paginator_names[0]
paginator_list_items = create_paginator_index(docs_paginators_path,
client_name, service_name,
example_paginator_name)
for name, paginator in sorted(paginator_config.items()):
pythonic_name = pythonic.xform_name(name)
paginator_path = f'{paginators_path}/{pythonic_name}'
docs_pagination_path = f'docs/{paginator_path}.md'
create_new_file(docs_pagination_path)
list_item, signature, documentation, headline = get_paginator_page(
name, pythonic_name, client_name, class_name, paginator,
paginator_path, service_path)
create_new_file(docs_pagination_path)
write_lines(docs_pagination_path, [headline, documentation, signature])
paginator_list_items.append(list_item)
write_lines(docs_paginators_path, paginator_list_items)
def create_sub_resource_index(path, resource_name, class_name,
sub_resource_name, param_str,
sub_resource_shape_name, shapes_path):
create_new_file(path)
sub_resource_variable = pythonic.xform_name(sub_resource_name)
if '_' in sub_resource_variable:
sub_resource_variable = sub_resource_variable[sub_resource_variable.
rindex('_') + 1:]
resource_hint = f"botostubs.{class_name}.{class_name}Resource"
sub_resource_title = f'{class_name}.{sub_resource_name}'
return [
f'# {sub_resource_title} sub-resource',
f'A sub-resource representing `{sub_resource_title}`:\n',
'You create such a resource as follows:',
f"""```python
import boto3
resource = boto3.resource('{resource_name}') # type: {resource_hint}
{sub_resource_variable} = resource.{sub_resource_name}({param_str}) # type: {resource_hint}.{sub_resource_name}
```
""",
get_resource_equivalence_message(sub_resource_name,
sub_resource_shape_name, shapes_path),
get_botostubs_message(),
]
def create_collection_page(path, collection_name, resource_name, class_name,
parameter_str, client_name, service_path, op_name,
resource_path):
create_new_file(path)
def all():
return f'Creates an iterable of all {resource_name} resources in the collection', ''
def filter():
return f'{all()[0]} filtered by kwargs passed to the method', parameter_str
def limit():
return (
f'Creates an iterable up to a specified number of {resource_name} resources in the collection',
'count=123',
)
def page_size():
return (
f'Creates an iterable of all {resource_name} resources in the collection, but limits the number of items returned by each service call by the specified number',
'count=123',
)
new_resource_path = get_resource_path_for(resource_name, resource_path)
result = [
f'# {collection_name} collection',
f'A collection of [{resource_name}]({new_resource_path}) resources:\n',
'# Actions',
]
for fn in [all, filter, limit, page_size]:
result.append(f'## {fn.__name__}')
doc, param_str = fn()
result.append(doc)
item_name = pythonic.xform_name(resource_name)
result.append(f"""```python
{item_name}: botostubs.{class_name}.{class_name}Resource.{resource_name}
for {item_name} in resource.{collection_name}.{fn.__name__}({param_str}):
pass # TODO: add your code here
```
""")
if fn == filter:
pythonic_op_name = pythonic.xform_name(op_name)
result.append(f"""#### Accepts
{get_accepts_redirect_link(client_name, pythonic_op_name, service_path)}
""")
result.append(get_botostubs_message())
return result
def handle_client_operation(class_name, client_list_items, client_name,
client_path, name, service_model, shapes_path):
fn_name = pythonic.xform_name(name)
method_path = f'{client_path}/operations/{fn_name}.md'
list_item, signature, documentation, headline = get_method_page(
client_name, class_name, service_model, name, method_path, shapes_path)
docs_method_path = f'docs/{method_path}'
create_new_file(docs_method_path)
write_lines(docs_method_path, [headline, documentation, signature])
client_list_items.append(list_item)
def get_waiter_page(name, fn_name, client_name, class_name, waiter_path,
service_path):
pythonic_name = pythonic.xform_name(name)
headline = f'# {pythonic_name} waiter'
signature = f"""
{get_example_waiter_snippet(name, pythonic_name, client_name, class_name, fn_name, service_path)}
"""
documentation = f'Polls {client_name}_client.{get_link_to_client_function(fn_name, service_path)} every 15 seconds until a successful state is reached. An error is returned after 40 failed checks.'
list_item = f'- [{pythonic_name}]({waiter_path})'
return list_item, signature, documentation, headline
def handle_waiter(class_name, client_name, name, service_path,
waiter_list_items, waiter_model, waiters_path):
waiter = waiter_model.get_waiter(name)
pythonic_name = pythonic.xform_name(waiter.operation)
waiter_path = f'{waiters_path}/{pythonic.xform_name(name)}'
docs_waiter_path = f'docs/{waiter_path}.md'
create_new_file(docs_waiter_path)
list_item, signature, documentation, headline = get_waiter_page(
name, pythonic_name, client_name, class_name, waiter_path,
service_path)
create_new_file(docs_waiter_path)
write_lines(docs_waiter_path, [headline, documentation, signature])
waiter_list_items.append(list_item)
def get_method_page(client_name, class_name, service_model, operation_name,
method_path, shapes_path):
pythonic_op_name = pythonic.xform_name(operation_name)
operation_model: OperationModel = service_model.operation_model(
operation_name)
input_shape: shape_union = operation_model.input_shape
output_shape: shape_union = operation_model.output_shape
param_str = get_param_str(input_shape, shapes_path)
append_return_type = ' -> ' + get_shape_string_link(
output_shape, shapes_path) if output_shape else ''
signature = get_signature_string(client_name, class_name, input_shape,
output_shape, pythonic_op_name, param_str,
shapes_path, append_return_type)
headline = f'# {pythonic_op_name} operation'
documentation = get_operation_documentation(operation_model, service_model)
list_item = f'- **[{pythonic_op_name}]({method_path})**({param_str}){append_return_type}'
return list_item, signature, documentation, headline
def handle_sub_resource_waiters(resource: Action, resource_list_items,
service_path):
waiters = resource.resource.model.waiters
if waiters:
resource_list_items.extend(
['# Waiters', 'The following waiters are available:'])
waiters_path = f'{service_path}/waiters'
waiter: Waiter
for waiter in waiters:
name = pythonic.xform_name(waiter.waiter_name)
variable_name = get_variable_name_for(resource.name)
resource_list_items.append(f'## {waiter.name}')
resource_list_items.append(f"""```python
{variable_name}.{waiter.name}(...)
```
""")
resource_list_items.append(
f'> Note that this waiter delegates to the client [{name}]({waiters_path}/{name}) waiter'
)
def print_sub_resource(resource_name, resource, sub_resource):
def get_shape_str(name, shapes_in_classes):
shape_str = []
for shape_class in shapes_in_classes:
if shape_class[1] != name:
continue
base_type = 'Mapping' if shape_class[
0].type_name == 'structure' else 'object'
shape_str.append(
f""" class {shape_class[0].name}({base_type}):
pass
""")
return '\n'.join(set(shape_str))
service_model = resource.meta.client.meta.service_model # sub_resource.resource.meta.client.meta.service_model
attr = getattr(resource, sub_resource.name)
params = []
shape_classes = []
for identifier in sub_resource.resource.identifiers:
params.append(pythonic.xform_name(identifier.target))
model_shape = sub_resource.resource.model.shape
attributes_doc = '\n '
if model_shape:
shape = service_model.shape_for(model_shape)
attributes = resource.meta.resource_model.get_attributes(shape)
for key, value in attributes.items():
type_shape = value[1]
attributes_doc += get_param_name(type_shape, key, type_shape,
shape_classes,
resource_name) + f"""
"""
resource_doc = f'r"""{inspect.getdoc(attr)}"""'
params_str = ''
if len(params):
params_str = ', ' + ', '.join(params)
return f"""
def get_method_signature(service_model, operation_name, shapes, class_name):
pythonic_op_name = pythonic.xform_name(operation_name)
operation_model = service_model.operation_model(operation_name)
input_shape = operation_model.input_shape
output_shape = operation_model.output_shape
parameters = input_shape.members if input_shape else {}
if input_shape:
append_to_shapes(input_shape, class_name, shapes)
if output_shape:
append_to_shapes(output_shape, class_name, shapes)
param_list = get_param_list(input_shape, parameters, shapes, class_name)
param_str = ', '.join(param_list)
operation_doc = operation_model.documentation.replace('<p>', '').replace(
'</p>', '')
docstr = f'r"""{operation_doc}\n'
append_return_type = ' -> ' + output_shape.name if output_shape else ''
rest_params = f":param {get_doc_str(input_shape)}"
return f""" def {pythonic_op_name}({param_str}){append_return_type}:
def get_variable_name_for(name):
variable_name = pythonic.xform_name(name)
if '_' in variable_name:
variable_name = variable_name[variable_name.rindex('_') + 1 :]
return variable_name
def get_sub_resource_param_str(sub_resource):
params = []
for identifier in sub_resource.resource.identifiers:
params.append(pythonic.xform_name(identifier.target) + "='...'")
param_str = ', '.join(params)
return param_str