mypy-boto3-organizations - Type annotations for AWS Organizations

Warnings

• breaking Support for Python 3.8 was removed in `mypy-boto3-builder` version 8.12.0. Consequently, `mypy-boto3-organizations` (and other generated stubs) now require Python 3.9 or newer.
  Fix: Upgrade your Python environment to 3.9 or higher.
• breaking The `mypy-boto3-builder` migrated to PEP 561-compliant packages in version 8.12.0. While this generally improves type checker compatibility, users might need to ensure their `mypy` or `pyright` configurations correctly resolve type stubs.
  Fix: Verify your type checker (e.g., mypy) is up-to-date and configured to correctly find stub packages. No direct code change is usually needed unless custom stub resolution paths were used.
• breaking TypeDef naming conventions changed in `mypy-boto3-builder` 8.9.0. Specifically, packed method arguments may use shorter names (e.g., `CreateDistributionRequestRequestTypeDef` became `CreateDistributionRequestTypeDef`). This applies to all generated service stubs, including Organizations.
  Fix: Update your code to use the new, shorter TypeDef names for request/response bodies as per the updated generated stubs. Consult the specific service's documentation for the correct TypeDef names.
• gotcha For optimal IDE auto-completion and static analysis, it is recommended to explicitly type-hint `boto3.client` calls with the imported client type (e.g., `client: OrganizationsClient = boto3.client("organizations")`), especially when using standalone service stub packages like `mypy-boto3-organizations`.
  Fix: Add explicit type annotations to your `boto3.client` and `session.client` calls to leverage full type-checking benefits.
• gotcha The `mypy-boto3` library is a legacy package. The current recommendation for `boto3` type annotations is to use `boto3-stubs` (for a collection of services) or specific standalone packages like `mypy-boto3-organizations`.
  Fix: If migrating from `mypy-boto3`, switch to `boto3-stubs` or the relevant `mypy-boto3-{service_name}` package. Ensure your imports reflect the new package structure (e.g., `from mypy_boto3_organizations import OrganizationsClient`).

Install

• pip install mypy-boto3-organizations Install standalone package
• pip install 'boto3-stubs[organizations]' Install as part of boto3-stubs

Imports

• OrganizationsClient

  from mypy_boto3_organizations import OrganizationsClient

• AcceptHandshakeRequestTypeDef

  from mypy_boto3_organizations.type_defs import AcceptHandshakeRequestTypeDef

Quickstart

Demonstrates how to use `mypy-boto3-organizations` to type-hint a `boto3` Organizations client and its method calls, including request and response `TypeDef` objects. This allows static analysis tools to validate your AWS API interactions.

import boto3
from mypy_boto3_organizations import OrganizationsClient
from mypy_boto3_organizations.type_defs import CreateAccountRequestTypeDef, CreateAccountResponseTypeDef


def create_aws_account(account_name: str, email: str, role_name: str) -> CreateAccountResponseTypeDef:
    """Creates a new AWS account within an organization."""
    client: OrganizationsClient = boto3.client("organizations")
    
    request: CreateAccountRequestTypeDef = {
        "Email": email,
        "AccountName": account_name,
        "RoleName": role_name,
        "Tags": [
            {"Key": "Project", "Value": "MyProject"}
        ]
    }
    
    response: CreateAccountResponseTypeDef = client.create_account(**request)
    print(f"Account creation requested: {response['CreateAccountStatus']['State']}")
    print(f"Account ID: {response['CreateAccountStatus'].get('AccountId', 'N/A')}")
    return response

# Example usage (requires AWS credentials configured for Organizations service)
if __name__ == "__main__":
    # In a real scenario, use unique values and ensure email is valid
    # and not already associated with an AWS account.
    # Replace with actual email and account name for testing.
    test_account_name = "MyTestOrgAccount"
    test_email = "test-account-owner@example.com" # Use a real, unique email
    test_role_name = "OrganizationAccountAccessRole"
    
    try:
        # This call will actually attempt to create an account in your AWS Organizations.
        # Be cautious when running this in a production environment.
        # For demonstration purposes, we'll comment out the actual call.
        # response = create_aws_account(test_account_name, test_email, test_role_name)
        print("To run, uncomment the create_aws_account call with valid parameters.")
    except Exception as e:
        print(f"An error occurred: {e}")