mypy-boto3-ds: Type Annotations for boto3 DirectoryService

1.42.3 · active · verified Sat Apr 11

mypy-boto3-ds provides comprehensive type annotations for the `boto3` AWS SDK's DirectoryService client, enabling static type checking with tools like `mypy`. It's part of the larger `mypy-boto3` (now often referred to as `types-boto3`) project, which automatically generates stubs directly from botocore schemas. This ensures robust type-hinting, improved IDE autocompletion, and early error detection for your AWS interactions. The library is actively maintained, with new versions released in lockstep with `boto3` updates, currently at version 1.42.3.

Warnings

breaking Support for Python 3.8 was removed in `mypy-boto3-builder` version 8.12.0 (corresponding to `mypy-boto3-ds` 1.42.3 generation). Projects using Python 3.8 or older will encounter issues.
Fix: Upgrade your Python environment to 3.9 or higher. Adjust your `pyproject.toml` or `setup.py` to reflect the new minimum Python version.
breaking In `mypy-boto3-builder` 8.9.0, there were breaking changes to TypeDef naming conventions, such as `CreateDistributionRequestRequestTypeDef` becoming `CreateDistributionRequestTypeDef`. While this specific example is not for DirectoryService, similar renames could affect other service TypeDefs.
Fix: Review your code for explicit TypeDef imports and adjust names according to the latest `mypy-boto3-ds` documentation or your type checker's suggestions. Consider using an IDE with good type-hinting support.
gotcha It is crucial to wrap `mypy-boto3-ds` specific imports within an `if TYPE_CHECKING:` block. Without this guard, the stub packages may become unnecessary runtime dependencies, potentially increasing deployment size or causing import errors if not properly installed in the runtime environment.
Fix: Always use `from typing import TYPE_CHECKING` and enclose `from mypy_boto3_ds...` imports inside `if TYPE_CHECKING:` blocks.
gotcha While `mypy-boto3-ds` provides stubs for `boto3`, directly importing client objects like `from boto3.client import DirectoryServiceClient` will not work for type checking. The actual client objects are dynamically generated by `boto3` at runtime.
Fix: Import the client type directly from the stub package: `from mypy_boto3_ds.client import DirectoryServiceClient` (preferably under `if TYPE_CHECKING:`).
gotcha The `mypy-boto3` project is now often referred to as `types-boto3` for its meta-package that can install stubs for all services. While `mypy-boto3-ds` is a specific service stub, referring to `mypy-boto3` in general discussions might lead to outdated documentation or package names.
Fix: For general usage, consider `pip install boto3-stubs[ds]` or `pip install types-boto3-ds`. `mypy-boto3-ds` is the standalone package for DirectoryService stubs.

Install

pip install mypy-boto3-ds boto3 Install with pip

Imports

DirectoryServiceClient

from mypy_boto3_ds.client import DirectoryServiceClient

DescribeDirectoriesResponseTypeDef

from mypy_boto3_ds.type_defs import DescribeDirectoriesResponseTypeDef

DirectoryTypeDef

from mypy_boto3_ds.type_defs import DirectoryTypeDef

Client Type Hinting (general)
```
from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from mypy_boto3_ds.client import DirectoryServiceClient
```
boto3.client itself does not expose type-hintable service clients directly. Stubs are imported under a `TYPE_CHECKING` guard.

Quickstart

This quickstart demonstrates how to obtain a type-hinted DirectoryService client and use it to list directories. The `if TYPE_CHECKING` block ensures that the `mypy-boto3-ds` imports are only used by type checkers, preventing them from becoming runtime dependencies. It also shows how to type-hint the client object and the response structure, enabling better autocompletion and static analysis.

import boto3
from typing import TYPE_CHECKING, List, Dict, Any

# Using TYPE_CHECKING to ensure type imports are only for static analysis
if TYPE_CHECKING:
    from mypy_boto3_ds.client import DirectoryServiceClient
    from mypy_boto3_ds.type_defs import DirectoryTypeDef, DescribeDirectoriesResultTypeDef

def get_ds_client() -> "DirectoryServiceClient":
    """Returns a type-hinted DirectoryService client."""
    return boto3.client("ds")

def list_all_directories() -> List["DirectoryTypeDef"]:
    """Lists all Directory Service directories with type hints."""
    client: "DirectoryServiceClient" = get_ds_client()
    response: "DescribeDirectoriesResultTypeDef" = client.describe_directories()
    # Accessing 'DirectoryDescriptions' is now type-checked
    return response.get("DirectoryDescriptions", [])

if __name__ == "__main__":
    print("Attempting to list Directory Service directories...")
    try:
        directories = list_all_directories()
        if directories:
            print(f"Found {len(directories)} directories:")
            for directory in directories:
                # Dictionary access is also type-checked with TypedDicts
                print(f"- {directory['Name']} ({directory['DirectoryId']}) - {directory['Type']}")
        else:
            print("No Directory Service directories found.")
    except Exception as e:
        print(f"Error listing directories: {e}")
        print("Ensure you have AWS credentials configured (e.g., via environment variables, ~/.aws/credentials) and sufficient permissions.")

view raw JSON →