Metadata-Version: 2.1
Name: aws-cdk.cfn-property-mixins
Version: 2.243.0
Summary: Auto-generated CDK Mixins for CloudFormation resource properties.
Home-page: https://github.com/aws/aws-cdk
Author: Amazon Web Services
License: Apache-2.0
Project-URL: Source, https://github.com/aws/aws-cdk.git
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: JavaScript
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Typing :: Typed
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved
Classifier: Framework :: AWS CDK
Classifier: Framework :: AWS CDK :: 2
Requires-Python: ~=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: aws-cdk-lib <3.0.0,>=2.243.0
Requires-Dist: constructs <11.0.0,>=10.5.0
Requires-Dist: jsii <2.0.0,>=1.127.0
Requires-Dist: publication >=0.0.3
Requires-Dist: typeguard ==2.13.3

# CDK CloudFormation Property Mixins

<!--BEGIN STABILITY BANNER-->---


![cdk-constructs: Stable](https://img.shields.io/badge/cdk--constructs-stable-success.svg?style=for-the-badge)

---
<!--END STABILITY BANNER-->

Auto-generated, type-safe CDK Mixins for every CloudFormation resource property.
These allow you to apply L1 properties to any construct (L1, L2, or custom) using the Mixins mechanism from `aws-cdk-lib`.

## Usage

For every CloudFormation resource, this package provides a `CfnXxxPropsMixin` class.
Apply it using `.with()` or `Mixins.of()`:

```python
s3.Bucket(scope, "MyBucket").with(CfnBucketPropsMixin(
    versioning_configuration=CfnBucketPropsMixin.VersioningConfigurationProperty(status="Enabled"),
    public_access_block_configuration=CfnBucketPropsMixin.PublicAccessBlockConfigurationProperty(
        block_public_acls=True,
        block_public_policy=True
    )
))
```

### Cross-Service References

Deeply nested properties support cross-service references:

```python
my_key = kms.Key(scope, "MyKey")

s3.Bucket(scope, "EncryptedBucket").with(CfnBucketPropsMixin(
    bucket_encryption=CfnBucketPropsMixin.BucketEncryptionProperty(
        server_side_encryption_configuration=[CfnBucketPropsMixin.ServerSideEncryptionRuleProperty(
            server_side_encryption_by_default=CfnBucketPropsMixin.ServerSideEncryptionByDefaultProperty(
                sse_algorithm="aws:kms",
                kms_master_key_id=my_key
            )
        )]
    )
))
```

### Merge Strategies

When a mixin is applied, its properties are merged onto the target resource using a merge strategy.
The strategy controls what happens when both the mixin and the existing resource define the same property.

There are two built-in strategies:

#### `PropertyMergeStrategy.combine()` (default)

Deep merges nested objects from the mixin into the target.
When both the existing and new value for a property are plain objects, their keys are merged recursively — existing keys are preserved and new keys are added.
Primitives, arrays, and mismatched types are replaced by the mixin value.

This is useful when you want to add configuration without losing what's already set:

```python
combine_bucket = s3.CfnBucket(scope, "CombineBucket")
combine_bucket.public_access_block_configuration = s3.CfnBucket.PublicAccessBlockConfigurationProperty(block_public_acls=True)

# Adds blockPublicPolicy while preserving the existing blockPublicAcls
combine_bucket.with(CfnBucketPropsMixin(
    public_access_block_configuration=CfnBucketPropsMixin.PublicAccessBlockConfigurationProperty(block_public_policy=True)
))
```

#### `PropertyMergeStrategy.override()`

Replaces existing property values with the mixin values.
Each property is copied as-is without inspecting nested objects.
Any previous value on the target is discarded.

This is useful when you want to fully replace a configuration:

```python
from aws_cdk.cfn_property_mixins.aws_s3 import CfnBucketMixinProps
override_bucket = s3.CfnBucket(scope, "OverrideBucket")
override_bucket.public_access_block_configuration = s3.CfnBucket.PublicAccessBlockConfigurationProperty(block_public_acls=True)

# Replaces the entire publicAccessBlockConfiguration
override_bucket.with(CfnBucketPropsMixin(CfnBucketMixinProps(public_access_block_configuration=CfnBucketPropsMixin.PublicAccessBlockConfigurationProperty(block_public_policy=True)), strategy=PropertyMergeStrategy.override()))
```

#### Custom Strategies

You can implement `IMergeStrategy` to define your own merge behavior.
The `apply` method receives the target object, source object, and an allowlist of property keys:

```python
@jsii.implements(IMergeStrategy)
class ArrayAppendStrategy:
    def apply(self, target, source, allowed_keys):
        for key in allowed_keys:
            if key in source:
                if Array.is_array(target[key]):
                    # append to target
                    target[key] = target[key].concat(source[key])
                else:
                    # override
                    target[key] = source[key]
```

### CloudFormation Property Mixins for Every Service

This package provides auto-generated property mixins for every CloudFormation resource across all AWS services.
Each service has its own submodule that mirrors the `aws-cdk-lib` module structure.
Import the mixin for the resource you want to configure from the corresponding service submodule:

```python
from aws_cdk.cfn_property_mixins.aws_s3 import CfnBucketPropsMixin
from aws_cdk.cfn_property_mixins.aws_lambda import CfnFunctionPropsMixin
from aws_cdk.cfn_property_mixins.aws_dynamodb import CfnTablePropsMixin
from aws_cdk.cfn_property_mixins.aws_logs import CfnLogGroupPropsMixin
from aws_cdk.cfn_property_mixins.aws_cloudfront import CfnDistributionPropsMixin
from aws_cdk.cfn_property_mixins.aws_rds import CfnDBInstancePropsMixin
```

The naming convention follows a consistent pattern: for a CloudFormation resource `AWS::S3::Bucket`, the mixin class is `CfnBucketPropsMixin` and lives in the `aws-s3` submodule.
The mixin props interface is named `CfnBucketMixinProps` and all properties are optional, so you only need to specify the ones you want to set.

Property mixins work with any construct that has the target resource as its default child.
This means you can apply them to L1 constructs, L2 constructs, and custom constructs alike:

```python
# L1 construct
s3.CfnBucket(scope, "L1Bucket").with(CfnBucketPropsMixin(versioning_configuration=CfnBucketPropsMixin.VersioningConfigurationProperty(status="Enabled")))

# L2 construct — the mixin finds the CfnBucket default child
s3.Bucket(scope, "L2Bucket").with(CfnBucketPropsMixin(versioning_configuration=CfnBucketPropsMixin.VersioningConfigurationProperty(status="Enabled")))
```
