# boto3-stubs

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

- [boto3-stubs](#boto3-stubs)
  - [How to use](#how-to-use)
  - [How it works](#how-it-works)
  - [Submodules](#submodules)

## How to use

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

Install `boto3-stubs`, it will add type annotations for `boto3` package, no services included.

```bash
# install type annotations just for boto3
python -m pip install boto3-stubs

# install `boto3` type annotations
# for ec2, s3, rds, lambda, sqs, dynamo and cloudformation
# Consumes ~10 MB of space
python -m pip install boto3-stubs[essential]

# or install annotations for services you use
python -m pip install boto3-stubs[acm,apigateway]

# build service index. You should execute this command everytime
# you update boto3-stubs or install/remove services
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 dynamodb

# Enjoy auto-complete for now
client: dynamodb.Client = boto3.client("dynamodb")

# argument hints and correct return type is provided by boto3-stubs
client.query("my_table")
```

## 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 with no services.
{% if package.essential_service_names -%}
    {{ "- `essential` - Type annotations for " -}}
    {% for service_name in package.essential_service_names -%}
        {% if not loop.first -%}
            {{ " and " if loop.last else ", " -}}
        {% endif -%}
        {{ "`" -}}
        {{ service_name.boto3_name -}}
        {{ "`" -}}
    {% endfor -%}
    {{ " services" if package.essential_service_names|length > 1 else " service" -}}
    {{ ".\n" -}}
{% endif -%}
{% for service_name in package.service_names -%}
    {{ "- `" -}}
    {{ service_name.boto3_name -}}
    {{ "` - Type annotations for `" -}}
    {{ service_name.boto3_name -}}
    {{ "` service." -}}
    {{ "" if loop.last else "\n" -}}
{% endfor -%}
{{ '\n' -}}
