types-boto3

types-boto3 ships fully typed stubs for boto3’s Session, client, and resource APIs, covering every AWS service that botocore exposes. The stubs are generated automatically by the mypy_boto3_builder project directly from botocore’s own service schemas, so method signatures, parameter shapes, and response TypedDicts stay in sync with each botocore release rather than being hand-maintained.

Because boto3 builds its clients dynamically at runtime, editors and type checkers have no way to know what methods a boto3.client('s3') object exposes without help. types-boto3 solves this by providing service-specific overloads for Session.client() and Session.resource(), so a call like boto3.client('s3') resolves to a fully typed S3 client with autocomplete for every API call, typed keyword arguments, and typed paginators and waiters.

What You Get

• Per-service client typing - boto3.client('s3') and hundreds of other service clients resolve to their exact method signatures instead of Any.
• Typed resources and collections - high-level boto3.resource() objects (e.g. a DynamoDB Table) get typed attributes and typed collection iterators.
• Typed paginators and waiters - get_paginator()/get_waiter() calls resolve to the specific paginator or waiter class for that operation, with typed paginate() keyword arguments.
• Response TypedDicts - every API response is a TypedDict with the exact keys AWS returns, so accessing a response field autocompletes instead of returning Any.
• Essential and lite install variants - types-boto3[essential] installs stubs only for commonly used services to keep install size small; types-boto3-lite drops the session overloads for a smaller, faster-to-typecheck footprint.

Common Use Cases

• Catching typos in AWS calls before deploy - a data engineer running boto3.client('s3').get_object(Bukcet=...) gets a mypy error instead of a runtime error after deploying to Lambda.
• IDE-driven AWS SDK exploration - a developer new to a service such as DynamoDB uses autocomplete to discover available operations and required parameters instead of switching to AWS docs.
• CI type-checking of infrastructure automation scripts - a platform team runs mypy in CI over deployment and ops scripts calling multiple AWS services and catches missing or renamed parameters after a botocore upgrade.
• Typed response parsing - a backend service parsing S3 or DynamoDB responses gets typed dict access instead of manually asserting types on Any.

Under The Hood

Architecture mypy_boto3_builder is organized around a family of Generator classes (a shared BaseGenerator subclassed by Boto3Generator, TypesBoto3Generator, MypyBoto3Generator, AioBotocoreGenerator, AioBoto3Generator, and Boto34Generator) that each drive stub emission for one published package family. parsers/ extract botocore’s service JSON schemas into typed internal structures (structures/packages/service_package.py), postprocessors/ refine and normalize the parsed signatures, jinja_manager.py plus templates/ render those structures into .pyi stub files, and writers/ persist per-service packages alongside a meta types-boto3 package that re-exports session, client, and resource overloads. cli_parser.py and main.py orchestrate the flow: parse args, resolve the requested service names (supporting all/updated/essential selectors), instantiate the matching generator, and run it. The stubs_static/types-boto3/ directory holds hand-authored static stubs (session, exceptions, compat) that are shipped verbatim alongside the generated per-service files. This is a clean generator/pipeline architecture where the core parsing abstraction is shared by every output family, so a change there ripples through all five published stub packages at once.

Tech Stack The builder targets Python 3.12+, is uv-managed (a checked-in uv.lock, tool.uv package = true), and depends on jinja2 for templating, boto3/botocore as the source of truth for service schemas, packaging for version comparisons, loguru for logging, and ruff invoked programmatically to format every generated stub file. Interactive quickstart (uvx mypy_boto3_builder) is built on prompt-toolkit and questionary. Dev tooling separates concerns into uv dependency groups: typecheck (pyright, mypy), test (pytest, pytest-cov, pytest-mock, requests-mock), and scripts (istub, twine, wheel) for publishing. The builder itself ships as mypy-boto3-builder with a console-script entry point, while its output — types-boto3, boto3-stubs, types-aiobotocore, types-aioboto3, plus lite/full/custom variants of each — is published to PyPI through dedicated per-package GitHub Actions workflows.

Code Quality The tests/ tree mirrors the source layout module-for-module (parsers/, structures/, postprocessors/, writers/, enums/, utils/, type_annotations/, type_maps/, import_helpers/), indicating deliberate per-module coverage, with pytest-cov and a checked-in codecov.yml wiring coverage into CI. A large set of GitHub Actions workflows runs unit tests, the mypy/pyright typecheck groups, and post-generation sanity checks against the live botocore API surface before each stub package is published. Type safety is central to the project’s own purpose: the source is fully typed with a py.typed marker, and pyright/mypy are configured to exclude only the generated stubs_static directory. Module boundaries are consistent — one file per concern under generators/, parsers/, and postprocessors/.

API Design The published types-boto3 package’s developer experience centers on drop-in installation: pip install 'types-boto3[essential]' adds typed overloads for Session.client()/Session.resource() with zero code changes required, since the stub package only affects static analysis. A lite variant trades away session-level overloads for a smaller, faster-to-typecheck footprint, and full/custom variants let large codebases pin every service’s types at once. Generated stubs embed a documentation link on each method, and the companion VSCode extension automates picking the right install variant — together these lower the friction of adopting strict typing on top of a dynamically-generated SDK like boto3.