# {{ service_name.pypi_name }}

Mypy-friendly auto-generated type annotations for `boto3 {{ service_name.boto3_name }} {{ boto3_version }}` service.
More information can be found [here](https://github.com/vemel/mypy_boto3).

- [{{ service_name.pypi_name }}](#{{ service_name.pypi_name }})
  - [How to use](#how-to-use)
    - [Type checking](#type-checking)
    - [Code auto-complete](#code-auto-complete)
  - [How it works](#how-it-works)

## How to use

### Type checking

Make sure you have [mypy](https://github.com/python/mypy) installed and activated in your IDE.

Install `boto3-stubs` for `{{ service_name.boto3_name }}` service.

```bash
python -m pip install boto3-stubs[{{service_name.pypi_name}}]

# build service index. You should execute this command everytime
# you update boto3-stubs or install/remove services
python -m python -m mypy_boto3
```

Use `boto3` with `{{ master_module_name }}` in your project and enjoy type checking.

```python
import boto3

from {{ master_module_name }} import {{ service_name.import_name }}
# alternative import if you do not want to install {{ master_module_name }} package
# import {{ service_name.module_name }} as {{ service_name.import_name }}

# Use this client as usual, now mypy can check if your code is valid.
# Check if your IDE supports function overloads,
# you probably do not need explicit type annotations
# client = boto3.client("{{ service_name.boto3_name }}")
client: {{ service_name.import_name }}.Client = boto3.client("{{ service_name.boto3_name }}")

# works for session as well
session = boto3.session.Session(region="us-west-1")
session_client: {{ service_name.import_name }}.Client = session.client("{{ service_name.boto3_name }}")

{% if package.service_resource -%}
# Do you prefer resource approach? We've got you covered!
resource: {{ service_name.import_name }}.ServiceResource = boto3.resource("{{ service_name.boto3_name }}")
{% endif -%}

{% if package.waiters -%}
{{ '\n' -}}
# Waiters need type annotation on creation
{% for waiter in package.waiters -%}
{{ waiter.waiter_name }}_waiter: {{ service_name.import_name }}.{{ waiter.name }} = client.get_waiter("{{ waiter.waiter_name }}")
{% endfor -%}
{% endif -%}

{% if package.paginators -%}
{{ '\n' -}}
# Paginators need type annotation on creation
{% for paginator in package.paginators -%}
{{ paginator.operation_name }}_paginator: {{ service_name.import_name }}.{{ paginator.name }} = client.get_paginator("{{ paginator.operation_name }}")
{% endfor -%}
{% endif -%}
```

## How it works

Fully automated [builder](https://github.com/vemel/mypy_boto3) carefully generates
type annotations for each service, patiently waiting for `boto3` updates. It delivers
a drop-in type annotations for you and makes sure that:

- Latest version of `boto3` is used.
- Each public class and method of every `boto3` service gets valid type annotations
  extracted from latest documentation (blame `botocore` docs if types are incorrect).
- Type annotations include up-to-date documentation.
- Code is processed by [black](https://github.com/psf/black) for readability.

## Submodules

- `master` - Install `mypy-boto3` package.
