# {{ package.pypi_name }}

[![PyPI - {{ package.pypi_name }}](https://img.shields.io/pypi/v/{{ package.pypi_name }}.svg?color=blue)](https://pypi.org/project/{{ package.pypi_name }})
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/{{ package.pypi_name }}.svg?color=blue)](https://pypi.org/project/{{ package.pypi_name }})
[![Docs](https://img.shields.io/readthedocs/mypy-boto3-builder.svg?color=blue)](https://mypy-boto3-builder.readthedocs.io/)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/{{ package.pypi_name }}?color=blue)](https://pypistats.org/packages/{{ package.pypi_name }})

![boto3.typed]({{ builder_repo_url }}/raw/main/logo.png)

Type annotations for
[{{ package.library_name }}.{{ service_name.class_name }} {{ package.library_version }}]({{ service_name.boto3_doc_link }}) service
compatible with
[VSCode](https://code.visualstudio.com/),
[PyCharm](https://www.jetbrains.com/pycharm/),
[Emacs](https://www.gnu.org/software/emacs/),
[Sublime Text](https://www.sublimetext.com/),
[mypy](https://github.com/python/mypy),
[pyright](https://github.com/microsoft/pyright)
and other tools.

Generated by [mypy-boto3-builder {{ builder_version }}]({{ builder_repo_url }}).

More information can be found on
[{{ package.data.PYPI_NAME }}](https://pypi.org/project/{{ package.data.PYPI_NAME }}/) page
and in [{{ package.pypi_name }} docs]({{ package.get_local_doc_link() }}).

See how it helps to find and fix potential bugs:

![boto3-stubs demo]({{ builder_repo_url }}/raw/main/demo.gif)

{% include "common/how_to_install_service.md.jinja2" with context %}

{% with extras_name=package.service_name.extras_name %}
{% include "common/usage.md.jinja2" with context %}
{% endwith %}

## Explicit type annotations

### Client annotations

`{{ package.client.name }}` provides annotations for `session.create_client("{{ service_name.boto3_name }}")`.

```python
from {{ package.library_name }}.session import get_session

from {{ package.name }} import {{ package.client.name }}

session = get_session()
async with session.create_client("{{ service_name.boto3_name }}") as client:
    client: {{ package.client.name }}
    # now client usage is checked by mypy and IDE should provide code completion
```

{% if package.paginators -%}
### Paginators annotations

`{{ package.name }}.paginator` module contains type annotations for all paginators.

```python
from {{ package.library_name }}.session import get_session

from {{ package.name }} import {{ package.client.name }}
from {{ package.name }}.paginator import (
{% for paginator in package.paginators %}    {{ paginator.name }},{{ '' if loop.last else '\n' }}{% endfor %}
)

session = get_session()
async with session.create_client("{{ service_name.boto3_name }}") as client:
    client: {{ package.client.name }}

    # Explicit type annotations are optional here
    # Type should be correctly discovered by mypy and IDEs
    # VSCode requires explicit type annotations
    {% for paginator in package.paginators -%}
    {{ '    ' -}}{{ paginator.operation_name }}_paginator: {{ paginator.name }} = client.get_paginator("{{ paginator.operation_name }}")
    {% endfor -%}
```
{% endif %}

{% if package.waiters -%}
### Waiters annotations

`{{ package.name }}.waiter` module contains type annotations for all waiters.

```python
from {{ package.library_name }}.session import get_session

from {{ package.name }}.client import {{ package.client.name }}
from {{ package.name }}.waiter import (
{% for waiter in package.waiters %}    {{ waiter.name }},{{ '' if loop.last else '\n' }}{% endfor %}
)

session = get_session()
async with session.create_client("{{ service_name.boto3_name }}") as client:
    client: {{ package.client.name }}

    # Explicit type annotations are optional here
    # Type should be correctly discovered by mypy and IDEs
    # VSCode requires explicit type annotations
    {% for waiter in package.waiters -%}
    {{ '    ' -}}{{ waiter.waiter_name }}_waiter: {{ waiter.name }} = client.get_waiter("{{ waiter.waiter_name }}")
    {% endfor -%}
```
{% endif %}

{% if package.service_resource -%}
### Service Resource annotations

`{{ package.service_resource.name }}` provides annotations for `{{ package.library_name }}.resource("{{ service_name.boto3_name }}")`.

```python
from {{ package.library_name }}.session import get_session

from {{ package.name }} import {{ package.service_resource.name }}

session = get_session()
async with session.resource("{{ service_name.boto3_name }}") as resource:
    resource: {{ package.service_resource.name }}
    # now resource usage is checked by mypy and IDE should provide code completion
```

{% if package.service_resource.sub_resources %}
### Other resources annotations

`{{ package.name }}.service_resource` module contains type annotations for all resources.

```python
from {{ package.library_name }}.session import get_session

from {{ package.name }} import {{ package.service_resource.name }}
from {{ package.name }}.service_resource import (
{% for sub_resource in package.service_resource.sub_resources %}    {{ sub_resource.name }},{{ '' if loop.last else '\n' }}{% endfor %}
)

session = get_session()
async with session.resource("{{ service_name.boto3_name }}") as resource:
    resource: {{ package.service_resource.name }}

# Explicit type annotations are optional here
# Type should be correctly discovered by mypy and IDEs
{% for sub_resource in package.service_resource.sub_resources -%}
{{ '    ' -}}my_{{ sub_resource.variable_name }}: {{ sub_resource.name }} = resource.{{ sub_resource.name }}(...)
{% endfor -%}
```
{% endif %}

{% if package.service_resource.collections %}
### Collections annotations

`{{ package.name }}.service_resource` module contains type annotations
for all `{{ package.service_resource.name }}` collections.

```python
from {{ package.library_name }}.session import get_session

from {{ package.name }} import {{ package.service_resource.name }}
from {{ package.name }}.service_resource import (
{% for collection in package.service_resource.collections %}    {{ collection.name }},{{ '' if loop.last else '\n' }}{% endfor %}
)

session = get_session()
async with session.resource("{{ service_name.boto3_name }}") as resource:
    resource: {{ package.service_resource.name }}

# Explicit type annotations are optional here
# Type should be correctly discovered by mypy and IDEs
{% for collection in package.service_resource.collections -%}
{{ '    ' -}}{{ collection.attribute_name }}: {{ service_name.underscore_name }}_resources.{{ collection.name }} = resource.{{ collection.attribute_name }}
{% endfor -%}
```
{% endif %}
{% endif %}

{% if package.literals %}
### Literals

`{{ package.name }}.literals` module contains literals extracted from shapes
that can be used in user code for type checking.

```python
from {{ package.name }}.literals import (
{% for literal in package.literals %}    {{ literal.name }},{{ '' if loop.last else '\n' }}{% endfor %}
)

def check_value(value: {{ package.literals[0].name }}) -> bool:
    ...
```
{% endif %}

{% if package.typed_dicts %}
### Typed dictionaries

`{{ package.name }}.type_defs` module contains structures and shapes assembled
to typed dictionaries for additional type checking.

```python
from {{ package.name }}.type_defs import (
{% for typed_dict in package.typed_dicts %}    {{ typed_dict.name }},{{ '' if loop.last else '\n' }}{% endfor %}
)

def get_structure() -> {{ package.typed_dicts[0].name }}:
    return {
      ...
    }
```
{% endif %}

{% include "common/footer.md.jinja2" with context %}
