---
name: mypy-boto3-mwaa
description: "mypy-boto3-mwaa package guide for typed boto3 Amazon MWAA clients, paginators, literals, and TypedDict request shapes"
metadata:
  languages: "python"
  versions: "1.42.3"
  revision: 1
  updated-on: "2026-03-12"
  source: maintainer
  tags: "aws,mwaa,airflow,boto3,python,typing,type-stubs,mypy,pyright"
---

# `mypy-boto3-mwaa` Python Package Guide

## Golden Rule

`mypy-boto3-mwaa` is a typing package, not a runtime AWS SDK. Use `boto3` for real Amazon MWAA calls, and add this package only so `mypy`, `pyright`, and editors understand the MWAA client, paginator, literals, and generated request/response shapes.

If you want `Session.client("mwaa")` to infer automatically, install `boto3-stubs[mwaa]`. If you install only `mypy-boto3-mwaa` or `boto3-stubs-lite[mwaa]`, annotate `MWAAClient` explicitly.

## Version-Sensitive Notes

- The version used here `1.42.3` matched the live PyPI package and maintainer docs checked on `2026-03-12`.
- PyPI marks this package as `Typing :: Stubs Only`, uploaded on `2025-12-04`, and notes it was generated by `mypy-boto3-builder 8.12.0`.
- The maintainer versioning guide states that `boto3-stubs` and `mypy-boto3-*` versions track the related `boto3` release line. Keep `mypy-boto3-mwaa` close to the installed `boto3` version so signatures do not drift.
- The maintainer docs URL is stable but not release-pinned. The AWS runtime docs I used are the latest boto3 service reference, not a frozen `1.42.3` snapshot, so prefer local stub generation when exact patch parity matters.
- For MWAA specifically, the official materials I checked exposed a typed client, one paginator (`ListEnvironmentsPaginator`), literals, and `type_defs`. I did not find a published MWAA service-resource or waiter page in the maintainer docs search results used for this session.

## Install

Choose the install mode that matches how much boto3 type inference you want.

### Best inference: full boto3 stubs

Use this when you want `Session.client("mwaa")` and `client.get_paginator(...)` to infer automatically:

```bash
python -m pip install "boto3==1.42.3" "boto3-stubs[mwaa]==1.42.3"
```

### Service-specific package only

Use this when you only want the MWAA typing package and are comfortable adding explicit annotations:

```bash
python -m pip install "boto3==1.42.3" "mypy-boto3-mwaa==1.42.3"
```

### Lower-memory aggregate package

Use this when the full stubs package is too heavy for the IDE or type-checking environment:

```bash
python -m pip install "boto3==1.42.3" "boto3-stubs-lite[mwaa]==1.42.3"
```

Notes:

- `boto3-stubs[mwaa]` gives the best overload-based inference.
- `boto3-stubs-lite[mwaa]` is lighter, but the maintainer docs note that lite mode omits overloaded `session.client/resource` inference.
- `mypy-boto3-mwaa` is useful when you want only MWAA typing support instead of the broader `boto3-stubs` extras package.

## Initialize And Authenticate

This package does not change AWS authentication, retries, endpoints, or permissions. All runtime behavior still comes from normal `boto3` and `botocore` configuration.

Typical local setup:

```bash
export AWS_PROFILE=dev
export AWS_DEFAULT_REGION=us-east-1
```

```python
from typing import TYPE_CHECKING

import boto3
from botocore.config import Config

if TYPE_CHECKING:
    from mypy_boto3_mwaa.client import MWAAClient

session = boto3.Session(profile_name="dev", region_name="us-east-1")
config = Config(
    retries={
        "mode": "standard",
        "max_attempts": 10,
    }
)

mwaa: "MWAAClient" = session.client("mwaa", config=config)
```

Use the same credential sources you would use for any other boto3 client:

- environment variables
- shared AWS config and credentials files
- IAM Identity Center or assume-role configuration
- task, container, Lambda, or EC2 IAM roles

MWAA is regional. Keep the session region aligned with the environment you are targeting.

## Core Usage

### Typed MWAA client

```python
from typing import TYPE_CHECKING

import boto3

if TYPE_CHECKING:
    from mypy_boto3_mwaa.client import MWAAClient

mwaa: "MWAAClient" = boto3.Session(region_name="us-east-1").client("mwaa")

response = mwaa.get_environment(Name="my-airflow-env")
environment = response["Environment"]

print(environment["Status"])
print(environment.get("AirflowVersion"))
print(environment.get("WebserverUrl"))
```

Use `get_environment` before destructive or follow-up operations when you need to confirm the environment state and webserver endpoint.

### Typed paginator

The docs site uses a `/paginators/` URL, but the Python import module is singular: `mypy_boto3_mwaa.paginator`.

```python
from typing import TYPE_CHECKING

import boto3

if TYPE_CHECKING:
    from mypy_boto3_mwaa.client import MWAAClient
    from mypy_boto3_mwaa.paginator import ListEnvironmentsPaginator

mwaa: "MWAAClient" = boto3.Session(region_name="us-east-1").client("mwaa")
paginator: "ListEnvironmentsPaginator" = mwaa.get_paginator("list_environments")

for page in paginator.paginate(PaginationConfig={"PageSize": 25}):
    for env_name in page.get("Environments", []):
        print(env_name)
```

`list_environments` returns environment names, so call `get_environment` for each name when you also need status, Airflow version, or webserver details.

### Generate a CLI token for the Airflow CLI

`create_cli_token` is the normal path for authenticated CLI access to an MWAA environment:

```python
from typing import TYPE_CHECKING

import boto3

if TYPE_CHECKING:
    from mypy_boto3_mwaa.client import MWAAClient

mwaa: "MWAAClient" = boto3.Session(region_name="us-east-1").client("mwaa")
response = mwaa.create_cli_token(Name="my-airflow-env")

print(response["WebServerHostname"])
print(response["CliToken"])
```

Treat the returned CLI token as short-lived secret material. Do not log or persist it.

### Call the Airflow REST API through MWAA

`invoke_rest_api` is useful when you want to reach the managed Airflow API without hand-assembling the environment endpoint yourself:

```python
from typing import TYPE_CHECKING

import boto3

if TYPE_CHECKING:
    from mypy_boto3_mwaa.client import MWAAClient

mwaa: "MWAAClient" = boto3.Session(region_name="us-east-1").client("mwaa")

response = mwaa.invoke_rest_api(
    Name="my-airflow-env",
    Path="/dags",
    Method="GET",
)

for dag in response.get("RestApiResponse", {}).get("dags", []):
    print(dag["dag_id"])
```

Pass only the Airflow path such as `/dags` or `/dags/<dag_id>/dagRuns`. Do not pass the full webserver URL.

### Typed request dictionaries and literals

Use generated `TypedDict` request shapes and literal aliases when helper functions construct MWAA parameters outside the immediate client call:

```python
from mypy_boto3_mwaa.type_defs import CreateCliTokenRequestTypeDef

request: CreateCliTokenRequestTypeDef = {
    "Name": "my-airflow-env",
}
```

The upstream docs also publish service-specific literals and request/response shapes under `mypy_boto3_mwaa.literals` and `mypy_boto3_mwaa.type_defs` for methods such as `get_environment`, `list_environments`, and `invoke_rest_api`.

## Runtime-Safe Typing Pattern

If stub packages are dev-only dependencies, keep the imports behind `TYPE_CHECKING` so runtime environments do not need them installed:

```python
from __future__ import annotations

from typing import TYPE_CHECKING

import boto3

if TYPE_CHECKING:
    from mypy_boto3_mwaa.client import MWAAClient
else:
    MWAAClient = object

client = boto3.Session(region_name="us-east-1").client("mwaa")
typed_client: "MWAAClient" = client
```

This also helps with `pylint` in environments where stub-only imports would otherwise trigger undefined-name warnings.

## Configuration Notes

- Use the boto3 credential provider chain rather than hard-coding AWS keys in source.
- `AWS_PROFILE` and `AWS_DEFAULT_REGION` are the most useful environment variables for local development.
- Use `botocore.config.Config` for retries, timeouts, proxies, and adaptive behavior; the stubs only type-check those calls.
- The boto3 service name is `"mwaa"`, not `"airflow"` and not the PyPI package name.
- Keep the region explicit in automation. MWAA environment names are unique only within the account and region context you are querying.
- If exact stubs for a locally pinned boto3 build matter more than the published package, the maintainer project recommends generating them locally with `mypy-boto3-builder`.

## Common Pitfalls

- The PyPI package name uses hyphens, but Python imports use underscores: `mypy_boto3_mwaa`.
- `mypy-boto3-mwaa` does not replace `boto3`. Install `boto3` for runtime AWS calls.
- If `Session().client("mwaa")` is inferred as `BaseClient`, you probably installed the standalone or lite package and need an explicit `MWAAClient` annotation.
- `boto3-stubs-lite[mwaa]` trades inference for lower memory use. That is expected behavior, not a broken installation.
- Do not pass a full URL to `invoke_rest_api`; pass the Airflow API path.
- `create_cli_token` returns a short-lived token for the Airflow CLI flow, not long-term AWS credentials.
- Keep the stubs close to the boto3 runtime version. Drift can leave editors showing stale parameters or missing newly added shapes.
- Do not assume every AWS service has a boto3 resource interface or waiter set. For MWAA, the official material used here is client-oriented.

## Official Sources

- PyPI package page: `https://pypi.org/project/mypy-boto3-mwaa/`
- Maintainer docs root: `https://youtype.github.io/boto3_stubs_docs/mypy_boto3_mwaa/`
- Maintainer versioning guide: `https://youtype.github.io/boto3_stubs_docs/#versioning`
- Boto3 MWAA service reference: `https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/mwaa.html`
- Boto3 `create_cli_token`: `https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/mwaa/client/create_cli_token.html`
- Boto3 `invoke_rest_api`: `https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/mwaa/client/invoke_rest_api.html`
- Boto3 credential guide: `https://docs.aws.amazon.com/boto3/latest/guide/credentials.html`
- Boto3 configuration guide: `https://docs.aws.amazon.com/boto3/latest/guide/configuration.html`
