Type annotations builder for boto3-stubs project. Compatible with mypy, pyright, VSCode, PyCharm and other tools.

See how it helps to find and fix potential bugs:

• mypy_boto3_builder
  • Using boto3-stubs
  • How to build type annotations
    • Locally
    • With Docker image
  • Known issues
    • PyCharm consumes too much CPU
  • Versioning
  • Latest changes
  • Thank you

Check boto3-stubs project for installation and usage instructions.

If you use up-to-date boto3 version, just install corresponding boto3-stubs and start using code auto-complete and mypy validation. You can find instructions on boto3-stubs page.

This page is only for building type annotations manually. For example, if you want to use the latest features for an older boto3 version.

# Install preferred version of `boto3`
python -m pip install boto3==1.16.25 botocore==1.19.25

# Install `mypy-boto3-builder`
python -m pip install mypy-boto3-builder

# Build all packages in mypy_boto3_output directory
python -m mypy_boto3_builder mypy_boto3_output

# Or specify required services explicitly
python -m mypy_boto3_builder mypy_boto3_output -s ec2 s3

# Install custom `boto3-stubs` packages
cd mypy_boto3_output
pip install mypy_boto3_ec2_package
pip install mypy_boto3_s3_package
pip install boto3_stubs_package

• Install Docker
• Pull latest mypy_boto3_builder version and tag it

docker pull docker.pkg.github.com/vemel/mypy_boto3_builder/mypy_boto3_builder_stable:latest
docker tag docker.pkg.github.com/vemel/mypy_boto3_builder/mypy_boto3_builder_stable:latest mypy_boto3_builder

• Generate stubs in output directory

mkdir output

# generate stubs for all services
docker run -v `pwd`/output:/output -ti mypy_boto3_builder

# generate stubs for s3 service
docker run -v `pwd`/output:/output -ti mypy_boto3_builder -s s3

# generate stubs for a specific boto3 version
docker run -e BOTO3_VERSION=1.16.25 BOTOCORE_VERSION=1.19.25 -v `pwd`/output:/output -ti mypy_boto3_builder

• Install packages from output directory as described above

PyCharm does not handle Literal overloads properly, so the only way to reduce CPU usage is to generate overloads only for services you use

# got to your project folder, activate venv

# install boto3-stubs as usual with services you need
pip install 'boto3-stubs[s3,ec2]'

# install mypy_boto3_builder
pip install mypy_boto3_builder

# generate boto3 stubs only with services in use, s3 and ec2 in this case
# stubs should be generated in <project_root>/typings/boto3
python -m mypy_boto3_builder --installed --skip-services typings -d -s s3 ec2

Add <project_root>/typings folder to your Interpreter Paths

Autocomplete should work now and do not stress your CPU. Still, try to avoid generation for 6 or more services, as it is still stressful for PyCharm. In this case, generate boto3-stubs for a couple of services and use explicit type annotations for the rest.

Since stubs are stored in your project root, you do not need to re-generate them after update.

mypy_boto3_builder version is not related to boto3 version and follows PEP 440.

Full changelog can be found in Releases.

• @alliefitter for boto3-type-annotations, this package is based on top of his work
• black developers for an awesome formatting tool
• @timothycrosley for isort and how flexible it is
• mypy for doing all dirty work for us
• pyright team for the new era of typed Python