# {{ service_name.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](https://github.com/vemel/mypy_boto3_builder/raw/master/logo.png)

Type annotations for
[boto3.{{ service_name.class_name }} {{ boto3_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 }}](https://github.com/vemel/mypy_boto3_builder).

More information can be found on [boto3-stubs](https://pypi.org/project/boto3-stubs/) page and in
[{{ package.pypi_name }} docs]({{ service_name.local_doc_link }})

See how it helps to find and fix potential bugs:

![boto3-stubs demo](https://github.com/vemel/mypy_boto3_builder/raw/master/demo.gif)

## How to install

### VSCode extension

Add [AWS Boto3](https://marketplace.visualstudio.com/items?itemName=Boto3typed.boto3-ide)
extension to your VSCode and run `AWS boto3: Quick Start` command.

Click `Modify` and select `boto3 common` and `{{ service_name.class_name }}`.

### From PyPI with pip

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

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

## Usage

### VSCode

- Install [Python extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
- Install [Pylance extension](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance)
- Set `Pylance` as your Python Language Server
- Install `boto3-stubs[{{service_name.extras_name}}]` in your environment: `python -m pip install 'boto3-stubs[{{service_name.extras_name}}]'`

Both type checking and auto-complete should work for `{{ service_name.class_name }}` service.
No explicit type annotations required, write your `boto3` code as usual.

### PyCharm

- Install `boto3-stubs[{{service_name.extras_name}}]` in your environment: `python -m pip install 'boto3-stubs[{{service_name.extras_name}}]'`

Both type checking and auto-complete should work for `{{ service_name.class_name }}` service.
No explicit type annotations required, write your `boto3` code as usual.
Auto-complete can be slow on big projects or if you have a lot of installed `boto3-stubs` submodules.

### Other IDEs

Not tested, but as long as your IDE supports `mypy` or `pyright`, everything should work.

### mypy

- Install `mypy`: `python -m pip install mypy`
- Install `boto3-stubs[{{service_name.extras_name}}]` in your environment: `python -m pip install 'boto3-stubs[{{service_name.extras_name}}]'`
- Run `mypy` as usual

Type checking should work for `{{ service_name.class_name }}` service.
No explicit type annotations required, write your `boto3` code as usual.

### pyright

- Install `pyright`: `yarn global add pyright`
- Install `boto3-stubs[{{service_name.extras_name}}]` in your environment: `python -m pip install 'boto3-stubs[{{service_name.extras_name}}]'`
- Optionally, you can install `boto3-stubs` to `typings` folder.

Type checking should work for `{{ service_name.class_name }}` service.
No explicit type annotations required, write your `boto3` code as usual.

## Explicit type annotations

### Client annotations

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

```python
import boto3

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

client: {{ package.client.name }} = boto3.client("{{ service_name.boto3_name }}")

# now client usage is checked by mypy and IDE should provide code auto-complete

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

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

`{{ service_name.module_name }}.paginator` module contains type annotations for all paginators.

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

client: {{ package.client.name }} = boto3.client("{{ service_name.boto3_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

`{{ service_name.module_name }}.waiter` module contains type annotations for all waiters.

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

client: {{ package.client.name }} = boto3.client("{{ service_name.boto3_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 `boto3.resource("{{ service_name.boto3_name }}")`.

```python
from {{ service_name.module_name }} import {{ package.service_resource.name }}

resource: {{ package.service_resource.name }} = boto3.resource("{{ service_name.boto3_name }}")

# now resource usage is checked by mypy and IDE should provide code auto-complete

# works for session as well
session = boto3.session.Session(region="us-west-1")
session_resource: {{ package.service_resource.name }} = session.resource("{{ service_name.boto3_name }}")
```

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

`{{ service_name.module_name }}.service_resource` module contains type annotations for all resources.

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

resource: {{ package.service_resource.name }} = boto3.resource("{{ service_name.boto3_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

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

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

resource: {{ package.service_resource.name }} = boto3.resource("{{ service_name.boto3_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

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

```python
from {{ service_name.module_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

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

```python
from {{ service_name.module_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 %}


## Versioning

`{{ package.pypi_name }}` version is the same as related `boto3` version and follows
[PEP 440](https://www.python.org/dev/peps/pep-0440/) format.

## Documentation

All type annotations can be found in [{{ package.pypi_name }} docs]({{ service_name.local_doc_link }})

## Support and contributing

This package is auto-generated. Please reports any bugs or request new features in
[mypy-boto3-builder](https://github.com/vemel/mypy_boto3_builder/issues/) repository.
