Type Annotations for boto3 SecretsManager

Common errors

• ModuleNotFoundError: No module named 'mypy_boto3_secretsmanager'

  cause The `types-boto3-secretsmanager` package is not installed in your environment.
  fix Run `pip install types-boto3-secretsmanager` or `pip install 'boto3-stubs[secretsmanager]'`.

• error: Missing type stub for 'boto3.client' (reportMissingStubs)

  cause Your type checker (e.g., mypy, pyright) cannot find type information for boto3 when using the Secrets Manager client.
  fix Ensure `types-boto3-secretsmanager` or `boto3-stubs[secretsmanager]` is installed and your type checker is correctly configured to discover PEP 561-compliant stub packages. Updating your type checker might also help.

• error: 'SecretsManagerClient' is not a known type (reportUnknownMemberAccess)

  cause The `SecretsManagerClient` type was either not imported correctly, or your type checker is not resolving it properly.
  fix Verify your import statement: `from mypy_boto3_secretsmanager import SecretsManagerClient`. Also, check if your type checker is up-to-date and configured for PEP 561 packages.

Warnings

• breaking Starting with `mypy-boto3-builder` version 8.12.0 (which generated this package), Python 3.8 is no longer supported for generated stub packages. This applies to `types-boto3-secretsmanager` versions built with builder 8.12.0 or newer.
  Fix: Upgrade your Python environment to 3.9 or newer.
• breaking Following the migration to PEP 561 packages in `mypy-boto3-builder` 8.12.0, ensure your `mypy` or other type checker is up-to-date. Older versions might not correctly discover or utilize the stubs, leading to `Missing type stub` errors or incorrect type inference.
  Fix: Update your type checker (e.g., `pip install --upgrade mypy`) and ensure it's configured to recognize PEP 561-compliant stub packages.
• breaking In `mypy-boto3-builder` version 8.9.0, type definition (TypeDef) naming conventions changed. This includes shorter names for packed method arguments and revised postfix handling for conflicting `TypeDef` names (e.g., `CreateDistributionExtraRequestTypeDef` became `CreateDistributionRequestExtraTypeDef`).
  Fix: Update your code to use the new `TypeDef` names as per the latest stub documentation. Your IDE or type checker should highlight these if you are using explicit type hints.
• gotcha These packages provide only type stubs and are not intended for runtime use. To avoid adding `types-boto3-secretsmanager` as a production dependency and ensure it's only used by static analysis tools, wrap your type imports within an `if TYPE_CHECKING:` block.
  Fix: Use `from typing import TYPE_CHECKING; if TYPE_CHECKING: from mypy_boto3_secretsmanager import SecretsManagerClient` (and similar for other types), with fallback assignments to `object` in the `else` block if `pylint` complains.

Install

• pip install types-boto3-secretsmanager Install standalone package
• pip install 'boto3-stubs[secretsmanager]' Install as part of boto3-stubs (recommended)

Imports

• SecretsManagerClient
  wrong:

  from boto3.client import SecretsManagerClient

  correct:

  from mypy_boto3_secretsmanager import SecretsManagerClient

  The client type hint is imported directly from the stub package, not boto3 itself.
• ListSecretsPaginator

  from mypy_boto3_secretsmanager.paginator import ListSecretsPaginator

  Paginator type hints are located in the .paginator submodule.
• FilterNameStringTypeType

  from mypy_boto3_secretsmanager.literals import FilterNameStringTypeType

  Literal types are available from the .literals submodule for stricter type checking.
• APIErrorTypeTypeDef

  from mypy_boto3_secretsmanager.type_defs import APIErrorTypeTypeDef

  Type definitions (TypedDicts, Unions) for service responses and parameters are in .type_defs.
• TYPE_CHECKING for stubs

  from typing import TYPE_CHECKING
  if TYPE_CHECKING:
      from mypy_boto3_secretsmanager import SecretsManagerClient
  else:
      SecretsManagerClient = object

  For production deployments, wrap stub imports in `if TYPE_CHECKING:` to prevent adding a runtime dependency.

Quickstart

This quickstart demonstrates how to initialize a `boto3` Secrets Manager client and retrieve a secret value with the benefit of static type checking provided by `types-boto3-secretsmanager`. The `if TYPE_CHECKING:` block ensures that `mypy_boto3_secretsmanager` is only used for type analysis and not as a runtime dependency.

import boto3
from typing import TYPE_CHECKING
import os

# Ensure AWS credentials are configured (e.g., via environment variables or ~/.aws/credentials)
# os.environ['AWS_ACCESS_KEY_ID'] = 'YOUR_ACCESS_KEY'
# os.environ['AWS_SECRET_ACCESS_KEY'] = 'YOUR_SECRET_KEY'
# os.environ['AWS_REGION'] = 'us-east-1'

if TYPE_CHECKING:
    from mypy_boto3_secretsmanager import SecretsManagerClient

def get_secret_value_typed(secret_name: str, region_name: str) -> str:
    session = boto3.session.Session()
    client: SecretsManagerClient = session.client(
        service_name='secretsmanager',
        region_name=region_name,
    )

    try:
        response = client.get_secret_value(
            SecretId=secret_name
        )
        if 'SecretString' in response:
            return response['SecretString']
        elif 'SecretBinary' in response:
            return response['SecretBinary'].decode('utf-8') # Assuming UTF-8 encoded binary
    except client.exceptions.ResourceNotFoundException:
        print(f"Secret '{secret_name}' not found.")
    except client.exceptions.ClientError as e:
        print(f"An AWS client error occurred: {e}")
    return ""

# Example usage (uncomment and replace with valid secret name and region)
# if __name__ == "__main__":
#     secret = get_secret_value_typed("my-test-secret", os.environ.get('AWS_REGION', 'us-east-1'))
#     if secret:
#         print(f"Retrieved secret: {secret}")