CloudWatchLogs Type Annotations for Boto3

1.42.83 · active · verified Fri Apr 10

mypy-boto3-logs provides static type annotations for the `boto3` CloudWatchLogs service, enhancing code quality and developer experience. It is generated by the `mypy-boto3-builder` project and is compatible with various type checkers like mypy and pyright, as well as IDEs like VSCode and PyCharm. The current version is 1.42.83, with frequent updates aligning with `boto3` releases and builder improvements.

Warnings

breaking Python 3.8 support has been removed as of `mypy-boto3-builder` version 8.12.0. All `mypy-boto3-*` packages now require Python 3.9 or newer.
Fix: Upgrade your Python environment to 3.9 or a newer version.
breaking TypeDef naming conventions changed in `mypy-boto3-builder` 8.9.0. Method argument TypeDefs may use shorter names, and conflicting `Extra` postfixes were moved to the end. This may require updating import paths or references to specific TypedDicts.
Fix: Refer to the specific service's documentation or use IDE auto-completion to find the updated TypeDef names for requests and responses.
gotcha `mypy-boto3-*` packages migrated to PEP 561. While beneficial, this might impact older `mypy` configurations. Stub-only packages, per PEP 561, cannot be found via `MYPYPATH` and must be installed directly in the environment `mypy` inspects.
Fix: Ensure `mypy-boto3-logs` is installed in the same Python environment used for `mypy` execution. Avoid relying on `MYPYPATH` for these stub packages.
gotcha PyCharm users may experience slow performance or high CPU usage due to Literal overloads. The `boto3-stubs-lite` packages are recommended as a workaround, or disable PyCharm's internal type checker and use `mypy` or `pyright` instead.
Fix: Install `boto3-stubs-lite[logs]` (`pip install 'boto3-stubs-lite[logs]'`) or disable PyCharm's type checking.
gotcha When using `TYPE_CHECKING` for conditional imports, Pylint may incorrectly report undefined variables. A workaround is to assign `object` to the type hints in the non-`TYPE_CHECKING` branch.
Fix: Implement the following pattern: `if TYPE_CHECKING: from mypy_boto3_logs.client import CloudWatchLogsClient else: CloudWatchLogsClient = object`

Install

pip install mypy-boto3-logs boto3 mypy Install with boto3 and mypy
pip install 'boto3-stubs[logs]' mypy Install via boto3-stubs extra (recommended)

Imports

CloudWatchLogsClient
```
from mypy_boto3_logs.client import CloudWatchLogsClient
```
Directly importing from boto3 does not provide type hints; the stub package provides the specific client type.
CloudWatchLogsServiceResource
```
from mypy_boto3_logs.service_resource import CloudWatchLogsServiceResource
```
Use this for service resources, if available for CloudWatchLogs (less common for logs).
PutLogEventsRequestRequestTypeDef
```
from mypy_boto3_logs.type_defs import PutLogEventsRequestRequestTypeDef
```
TypedDicts for request/response bodies are found in type_defs.

Quickstart

This quickstart demonstrates how to obtain a type-hinted CloudWatchLogs client and use it with type-safe operations. The `TYPE_CHECKING` block ensures that `mypy-boto3-logs` is only a development dependency. Replace placeholder credentials with actual AWS configuration for real-world usage.

from typing import TYPE_CHECKING
import boto3

if TYPE_CHECKING:
    from mypy_boto3_logs.client import CloudWatchLogsClient
    from mypy_boto3_logs.type_defs import PutLogEventsResponseTypeDef


def get_logs_client() -> 'CloudWatchLogsClient':
    """Returns a type-hinted CloudWatchLogs client."""
    session = boto3.Session(
        aws_access_key_id=os.environ.get('AWS_ACCESS_KEY_ID', ''),
        aws_secret_access_key=os.environ.get('AWS_SECRET_ACCESS_KEY', ''),
        region_name=os.environ.get('AWS_REGION', 'us-east-1')
    )
    return session.client('logs')


def put_log_events_example():
    """Example of using the type-hinted CloudWatchLogs client."""
    client = get_logs_client()
    response: PutLogEventsResponseTypeDef = client.put_log_events(
        logGroupName='my-log-group',
        logStreamName='my-log-stream',
        logEvents=[
            {'timestamp': 1678886400000, 'message': 'Hello from mypy-boto3-logs!'}
        ]
    )
    print(f"Sequence Token: {response.get('nextSequenceToken')}")

if __name__ == '__main__':
    import os
    # Set dummy AWS credentials for local testing or ensure they are in env vars
    # For actual use, configure boto3 credentials securely
    if not os.environ.get('AWS_ACCESS_KEY_ID'):
        os.environ['AWS_ACCESS_KEY_ID'] = 'TEST_ACCESS_KEY'
        os.environ['AWS_SECRET_ACCESS_KEY'] = 'TEST_SECRET_KEY'
        os.environ['AWS_REGION'] = 'us-east-1'

    put_log_events_example()

view raw JSON →