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_info(id, message=None)

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

The acknowledgement will apply to all child scopes

Parameters:

  • id (str) –

    • the id of the info 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_info("SomeInfoId", "This info can be ignored because...")
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_info_v2(id, message)

Adds an acknowledgeable info metadata entry to this construct.

The CLI will display the info when an app is synthesized.

If the info is acknowledged using acknowledgeInfo(), it will not be shown by the CLI.

Parameters:

  • id (str) – the unique identifier for the info. This can be used to acknowledge the info

  • message (str) – The info message.

Return type:

None

Example:

# my_construct: Construct

Annotations.of(my_construct).add_info_v2("my-library:Construct.someInfo", "Some message explaining the info")
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