Type Annotations for awscrt

Warnings

• breaking In `awscrt` versions 0.28.2 and later, `awscrt.io.init_logging()` can only be called once per process. Subsequent calls will raise an `AWS_ERROR_INVALID_STATE` exception. This can impact test suites or applications that attempt to re-initialize logging. [14]
  Fix: Ensure `awscrt.io.init_logging()` is called only once in the application's lifecycle. Adjust tests to avoid re-initialization or reset logging state carefully if absolutely necessary.
• gotcha `awscrt` uses background threads, which makes `os.fork()` unsafe on POSIX systems (excluding macOS) for Python versions 3.13 and earlier. Using `os.fork()` or the default `multiprocessing` start method ('fork') can lead to hangs or crashes in child processes. [8, 12]
  Fix: When using `multiprocessing`, explicitly set the start method to 'spawn' or 'forkserver' (e.g., `multiprocessing.set_start_method('spawn')`). If using `os.fork()` directly, ensure all CRT resources are released and all CRT threads are joined before forking. [8]
• gotcha On macOS, once a private key is used with a certificate in `awscrt`, that certificate-key pair is imported into the Mac Keychain. All subsequent uses of that certificate will use the stored private key from the Keychain and will ignore any private key passed in programmatically. [1, 8, 12]
  Fix: Be aware of this platform-specific behavior on macOS. If dynamic private key handling is critical, consider alternative approaches or ensure certificate-key pairs are managed appropriately within the Keychain.
• gotcha `types-awscrt` aims to have its version mirror the `awscrt` version it provides type stubs for. Significant discrepancies between `types-awscrt` and `awscrt` versions can lead to incorrect type hints, missing definitions, or type-checking errors if the underlying `awscrt` API has changed without a corresponding `types-awscrt` update. [4, 7]
  Fix: Keep `types-awscrt` and `awscrt` versions synchronized as closely as possible to ensure accurate type checking. Refer to the `types-awscrt` changelog or GitHub releases for specific `awscrt` versions supported.

Install

• pip install types-awscrt Install types-awscrt

Imports

• ClientBootstrap

  from awscrt.io import ClientBootstrap

• AwsCredentials

  from awscrt.auth import AwsCredentials

• S3Client

  from awscrt.s3 import S3Client

• EventLoopGroup

  from awscrt.io import EventLoopGroup

Quickstart

This quickstart demonstrates basic initialization of `awscrt` components. `types-awscrt` enhances this experience by providing static type checking and IDE auto-completion for `awscrt` objects and methods.

import os
import awscrt.io as io
import awscrt.auth as auth
import awscrt.s3 as s3 # Example usage

# Initialize the AWS Common Runtime's I/O and event loop
# types-awscrt provides type hints for these objects
event_loop_group: io.EventLoopGroup = io.EventLoopGroup()
host_resolver: io.DefaultHostResolver = io.DefaultHostResolver(event_loop_group)
bootstrap: io.ClientBootstrap = io.ClientBootstrap(event_loop_group, host_resolver)

# Example for AWS credentials (replace with actual logic, e.g., environment variables or assumed roles)
access_key_id = os.environ.get('AWS_ACCESS_KEY_ID', 'DUMMY_ACCESS_KEY')
secret_access_key = os.environ.get('AWS_SECRET_ACCESS_KEY', 'DUMMY_SECRET_KEY')
session_token = os.environ.get('AWS_SESSION_TOKEN', None) # Optional

credentials: auth.AwsCredentials = auth.AwsCredentials(
    access_key_id=access_key_id,
    secret_access_key=secret_access_key,
    session_token=session_token
)

print(f"AWS CRT initialized. Credentials loaded (Access Key ID: {credentials.access_key_id}).")
# With types-awscrt installed, a type checker (like MyPy or Pyright) would validate the types above.