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 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 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 handle_shapes(service_model: ServiceModel, class_name, shapes_path):
top_level_shapes = [(service_model.shape_for(name), class_name)
for name in service_model.shape_names]
if not top_level_shapes:
return
docs_shapes_path = f'docs/{shapes_path}'
create_new_file(docs_shapes_path)
service_name = get_service_name(service_model)
all_shapes = find_all_shapes(top_level_shapes)
shape_docs = [get_shape_doc(shapes_path, shape) for shape in all_shapes]
write_lines(docs_shapes_path,
[f'# {service_name} data types'] + shape_docs)
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 create_resource_index(path, resource_name, service_name, class_name):
create_new_file(path)
return [
f'# {service_name} resource',
f'A resource representing {service_name}:\n',
'You create such a resource as follows:',
f"""```python
import boto3
resource = boto3.resource('{resource_name}') # type: botostubs.{class_name}.{class_name}Resource
```
""",
get_botostubs_message(),
]
def create_waiter_index(path, client_name, service_name, waiter_name):
create_new_file(path)
return [
f'# {service_name} waiters',
f"""You get a waiter by calling `get_waiter` on a certain client:
```python
import boto3
client = boto3.client('{client_name}')
waiter = client.get_waiter('{pythonic.xform_name(waiter_name)}') # type: botostubs.{service_name}.{waiter_name}Waiter
```
""",
get_botostubs_message(),
'The available client waiters are:',
]
def handle_resource_actions(client_name, class_name, list_items, resource_path, service_model, shapes_path, actions):
if actions:
list_items.extend(['# Actions', 'These are the available actions:'])
for action in actions:
fn_name = action.name
method_path = f'{resource_path}/operations/{fn_name}.md'
list_item, signature, documentation, headline = handle_resource_action(
client_name, class_name, action, method_path, fn_name, service_model, shapes_path, resource_path
)
docs_method_path = f'docs/{method_path}'
create_new_file(docs_method_path)
write_lines(docs_method_path, [headline, documentation, signature])
list_items.append(list_item)
if actions:
list_items.append('') # newline
def create_paginator_index(path, client_name, service_name,
example_paginator_name):
create_new_file(path)
return [
f'# {service_name} paginators',
f"""You get a paginator by calling `get_paginator` on a certain client:
```python
import boto3
client = boto3.client('{client_name}')
paginator = client.get_paginator('{pythonic.xform_name(example_paginator_name)}') # type: botostubs.{service_name}.{example_paginator_name}Paginator
```
""",
get_botostubs_message(),
'The available client paginators are:',
]
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 create_client_index(path, client_name, service_name, class_name):
create_new_file(path)
return [
f'# {service_name} client',
f'A low-level client representing {service_name}.',
'There are 2 main ways of creating clients; with a default `boto3.Session` or with one that you define:',
f"""```python
import boto3
client = boto3.client('{client_name}') # type: botostubs.{class_name}
```
""",
'or ...',
f"""```python
from boto3 import Session
session = Session(profile_name='your-aws-cli-profile')
client = session.client('{client_name}') # type: botostubs.{class_name}
```""",
get_botostubs_message(),
'# Operations',
'These are the available operations:',
]