Annotations

class aws_cdk.Annotations(*args: Any, **kwargs)

Bases: object

Includes API for attaching annotations such as warning messages to constructs.

ExampleMetadata:: nofixture infused

Example:

import aws_cdk as cdk
from constructs import Construct, IConstruct

@jsii.implements(cdk.IAspect)
class MyAspect:
    def visit(self, node):
        if node instanceof cdk.CfnResource && node.cfn_resource_type == "Foo::Bar":
            self.error(node, "we do not want a Foo::Bar resource")

    def error(self, node, message):
        cdk.Annotations.of(node).add_error(message)

class MyStack(cdk.Stack):
    def __init__(self, scope, id):
        super().__init__(scope, id)

        stack = cdk.Stack()
        cdk.CfnResource(stack, "Foo",
            type="Foo::Bar",
            properties={
                "Fred": "Thud"
            }
        )
        cdk.Aspects.of(stack).add(MyAspect())

Methods

acknowledge_warning(id, message=None)

Acknowledge a warning. When a warning is acknowledged for a scope all warnings that match the id will be ignored.

The acknowledgement will apply to all child scopes

Parameters:

id (str) –
- the id of the warning message to acknowledge.
message (Optional[str]) – optional message to explain the reason for acknowledgement.

Return type:

None

Example:

# my_construct: Construct

Annotations.of(my_construct).acknowledge_warning("SomeWarningId", "This warning can be ignored because...")

add_deprecation(api, message)

Adds a deprecation warning for a specific API.

Deprecations will be added only once per construct as a warning and will be deduplicated based on the api.

If the environment variable CDK_BLOCK_DEPRECATIONS is set, this method will throw an error instead with the deprecation message.

Parameters:

api (str) – The API being deprecated in the format module.Class.property (e.g. @aws-cdk/core.Construct.node).
message (str) – The deprecation message to display, with information about alternatives.

Return type:

None

add_error(message)

Adds an { “error”: } metadata entry to this construct.

The toolkit will fail deployment of any stack that has errors reported against it.

Parameters:: message (str) – The error message.
Return type:: None

add_info(message)

Adds an info metadata entry to this construct.

The CLI will display the info message when apps are synthesized.

Parameters:: message (str) – The info message.
Return type:: None

add_warning(message)

Adds a warning metadata entry to this construct. Prefer using addWarningV2.

The CLI will display the warning when an app is synthesized, or fail if run in --strict mode.

Warnings added by this call cannot be acknowledged. This will block users from running in --strict mode until the deal with the warning, which makes it effectively not very different from addError. Prefer using addWarningV2 instead.

Parameters:: message (str) – The warning message.
Return type:: None

add_warning_v2(id, message)

Adds an acknowledgeable warning metadata entry to this construct.

The CLI will display the warning when an app is synthesized, or fail if run in --strict mode.

If the warning is acknowledged using acknowledgeWarning(), it will not be shown by the CLI, and will not cause --strict mode to fail synthesis.

Parameters:

id (str) – the unique identifier for the warning. This can be used to acknowledge the warning
message (str) – The warning message.

Return type:

None

Example:

# my_construct: Construct

Annotations.of(my_construct).add_warning_v2("my-library:Construct.someWarning", "Some message explaining the warning")

Static Methods

classmethod of(scope)

Returns the annotations API for a construct scope.

Parameters:: scope (IConstruct) – The scope.
Return type:: Annotations