aioboto3-hints-docs 0.4.0
Type annotations for aioboto3. Adds code completion in IDEs such as PyCharm.
License: MIT License

# aioboto3 Type Hints

[![PyPi Version](https://img.shields.io/pypi/v/aioboto3-hints.svg)](https://pypi.python.org/pypi/aioboto3-hints)
[![Build Status](https://travis-ci.com/terrycain/aioboto3-hints.svg?branch=master)](https://travis-ci.com/terrycain/aioboto3-hints)
[![PyUp Updates](https://pyup.io/repos/github/terrycain/aioboto3-hints/shield.svg)](https://pyup.io/repos/github/terrycain/aioboto3-hints/)


All of the credit goes to Allie Fitter who did all of the hard work, I've just repurposed his repo to generate async type hints

Upstream repo - https://github.com/alliefitter/boto3_type_annotations

## With or Without Docstrings

This package is available both with docstrings, named `aioboto3-hints-docs` on PyPi (which contains the 
same documentation you'll find online), and without, named `aioboto3-hints` on PyPi. The reason for this is 
that, for a python package, `aioboto3-hints-docs` is HUGE. `aioboto3-hints` is pretty large itself 
at 2.2 MB, but `aioboto3-hints-with-docs` dwarfs it at 41 MB. Both of the packages contain a module `aioboto3_hints` 
so you can swap out the libraries between local testing and going to production with ease.

## TODO

Am planning to add in work to reflect some work done by vemel here - https://github.com/vemel/mypy_boto3

## Installation

Without docs:
```
pip install aioboto3-hints
```

With docs:
```
pip install aioboto3-hints-docs
```

## Usage

Regardless of which deployment package you install, you'll still import the same package, `aioboto3_hints`.
Its constituent packages and modules can be used to declare the type of `aioboto3` objects. For instance, everybody's 
favorite, S3:

```python
import asyncio
import boto3
from aioboto3_hints.s3 import Client, ServiceResource
from aioboto3_hints.s3.waiter import BucketExists
from aioboto3_hints.s3.paginator import ListObjectsV2

# With type annotations
async def main():
    client: Client = boto3.client('s3')
    await client.create_bucket(Bucket='foo')  # Not only does your IDE knows the name of this method, 
                                              # it knows the type of the `Bucket` argument too!
                                              # It also, knows that `Bucket` is required, but `ACL` isn't!

    # Waiters and paginators and defined also...
    waiter: BucketExists = client.get_waiter('bucket_exists')
    await waiter.wait('foo')

    paginator: ListObjectsV2 = client.get_paginator('list_objects_v2')
    async for response in paginator.paginate(Bucket='foo'):
        print(response)

    await client.close()

    # Along with service resources.
    resource: ServiceResource = boto3.resource('s3')
    bucket = resource.Bucket('bar')
    await bucket.create()

    await resource.close()

    # With type comments
    async with boto3.client('s3') as client:  # type: Client
        response = await client.get_object(Bucket='foo', Key='bar')

    # This should also work
    client: Client
    async with boto3.client('s3') as client:
        response = await client.get_object(Bucket='foo', Key='bar')


asyncio.run(main())    

# In docstrings
class Foo:
    def __init__(self, client):
        """
        :param client: It's an S3 Client and the IDE is gonna know what it is!
        :type client: Client
        """
        self.client = client

    async def bar(self):
        """
        :rtype: Client
        """
        await self.client.delete_object(Bucket='foo', Key='bar')
        return self.client
```