Understanding CDKit’s Parameter System¶

The CDKit Parameter System addresses common challenges in AWS CDK development by providing a more structured and type-safe approach to manage construct and stack parameters. This documentation compares the traditional approach with CDKit’s enhanced parameter management system.

The Problem with Traditional CDK Parameter Management¶

Traditional CDK stack implementation requires manually defining all parameters in the constructor, managing defaults, and handling type safety yourself. This approach becomes unwieldy as applications grow more complex.

Let’s examine the traditional approach:

# -*- coding: utf-8 -*-

import aws_cdk as cdk
from constructs import Construct


class MyStack(cdk.Stack):
    def __init__(
        self,
        scope: Construct,
        id: str,
        stack_name: str,
        env: cdk.Environment,
        your_custom_param_1: int,
        your_custom_param_2: str = "my_default_value",
        **kwargs,  # more parameters for the default cdk.Stack.__init__
    ):
        super().__init__(
            scope=scope,
            id=id,
            stack_name=stack_name,
            env=env,
            **kwargs,
        )
        self.your_custom_param_1 = your_custom_param_1
        self.your_custom_param_2 = your_custom_param_2


app = cdk.App()
stack = MyStack(
    scope=app,
    id="...",
    stack_name="my_stack_name",
    env=cdk.Environment(
        account="...",
        region="...",
    ),
    your_custom_param_1=42,
    your_custom_param_2="my_custom_value",
)

In this traditional approach, several issues emerge:

Repetitive Parameter Definitions: Each subclass needs to redefine all parameters in the constructor signature.
Loss of Type Information: Using **kwargs loses type hints and IDE completion support.
Manual Validation Required: You must manually validate required parameters.
Poor Maintainability: Adding or changing parameters requires updates in multiple places.
Inconsistent Parameter Handling: Different developers may implement parameter validation differently.

CDKit’s Enhanced Parameter System¶

CDKit solves these problems with a structured parameter system built on Python dataclasses:

# -*- coding: utf-8 -*-

import dataclasses

import aws_cdk as cdk
from constructs import Construct

import cdkit.api as cdkit
from func_args.api import REQ


@dataclasses.dataclass
class MyStackParams(cdkit.StackParams):
    your_custom_param_1: int = dataclasses.field(default=REQ)
    your_custom_param_2: str = dataclasses.field(default="my_default_value")


class MyStack(cdkit.BaseStack):
    def __init__(
        self,
        scope: Construct,
        params: MyStackParams,
    ):
        super().__init__(scope=scope, params=params)
        self.params = params


app = cdk.App()
stack = MyStack(
    scope=app,
    params=MyStackParams(
        id="...",
        stack_name="my_stack_name",
        env=cdk.Environment(
            account="...",
            region="...",
        ),
        your_custom_param_1=42,
        your_custom_param_2="my_custom_value",
    ),
)

Benefits of CDKit’s Parameter System¶

Type Safety and IDE Support
- All parameters are strongly typed with proper annotations
- Full IDE autocompletion for parameters
- Type checking catches errors at development time
Centralized Parameter Definition
- Parameters are defined once in the dataclass
- Changes to parameters happen in one place
- Consistent parameter handling across the project
Built-in Parameter Validation
- Required parameters are clearly marked (REQ)
- Optional parameters have explicit defaults (OPT)
- Validation happens automatically when parameters are instantiated

4. Cleaner Stack Implementation¶

Stack implementation focuses on business logic, not parameter handling
Constructor is simplified to just scope and params
Self-documenting parameter organization

5. Easy Extension¶

New parameters can be added by extending the parameter dataclass
Parameter inheritance mirrors the stack inheritance hierarchy
Common parameters are inherited, specific ones are added

Summary¶

The CDKit parameter system transforms AWS CDK development by providing a more structured, type-safe, and maintainable approach to parameter management. By leveraging Python dataclasses, it eliminates repetitive code, improves type safety, and ensures consistent parameter handling across your CDK applications.