From 31f548955ebb8c922b4e448a40bb9041a1986499 Mon Sep 17 00:00:00 2001 From: Momo Kornher Date: Wed, 20 Dec 2023 11:23:48 +0000 Subject: [PATCH] fix: cannot use splitBySubmodule and multiple languages together Fixes: #1250 --- src/cli.ts | 59 +- .../libraries/construct-library/lib/index.ts | 4 + .../construct-library/lib/submod1/index.ts | 4 + test/__snapshots__/cli.test.ts.snap | 6332 +++++++++++++++++ test/cli.test.ts | 26 + 5 files changed, 6398 insertions(+), 27 deletions(-) diff --git a/src/cli.ts b/src/cli.ts index 34717152..5ecac7c4 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -10,26 +10,18 @@ type GenerateOptions = { submodule?: string; allSubmodules?: boolean; splitBySubmodules?: boolean; - format?: 'md' | 'json'; - output?: string; + format: 'md' | 'json'; + output: string; } async function generateForLanguage(docs: Documentation, options: GenerateOptions) { - const { format, output = 'API' } = options; - const fileSuffix = format === 'md' ? 'md' : 'json'; - let submoduleSuffix = fileSuffix; - - const outputFileName = output.endsWith(`.${fileSuffix}`) - ? output.slice(0, -(fileSuffix.length + 1)) - : output; + const { format, output } = options; // e.g. API.typescript as name - if (outputFileName.includes('.')) { - const languageSeparator = outputFileName.split('.')[1]; - submoduleSuffix = `${languageSeparator}.${fileSuffix}`; - } + const splitByLanguage = output.endsWith(`.${options.language.name}`); + const submoduleSuffix = splitByLanguage ? `${options.language.name}.${format}` : format; // Ensure the output path exists - const outputPath = path.dirname(outputFileName); + const outputPath = path.dirname(output); await fs.mkdir(outputPath, { recursive: true }); if (options.splitBySubmodules) { @@ -49,10 +41,10 @@ async function generateForLanguage(docs: Documentation, options: GenerateOptions await fs.writeFile(path.join(outputPath, `${submoduleRelName(submodule)}.${submoduleSuffix}`), content.render()); } - await fs.writeFile(`${outputFileName}.${fileSuffix}`, await (await docs.toIndexMarkdown(submoduleSuffix, options)).render()); + await fs.writeFile(`${output}.${format}`, await (await docs.toIndexMarkdown(submoduleSuffix, options)).render()); } else { const content = await (format === 'md' ? docs.toMarkdown(options) : docs.toJson(options)); - await fs.writeFile(`${outputFileName}.${fileSuffix}`, content.render()); + await fs.writeFile(`${output}.${format}`, content.render()); } } @@ -78,22 +70,35 @@ export async function main() { ? Documentation.forPackage(args.package) : Documentation.forProject(process.cwd())); - const options = (lang: string, output?: string): GenerateOptions => ({ - readme, - language: Language.fromString(lang), - submodule, - allSubmodules, - splitBySubmodules, - format: args.format as 'md' | 'json', - output, - }); + const options = (lang: string, output: string = 'API', includeLanguageInOutputName = false): GenerateOptions => { + const format = args.format === 'md' ? 'md' : 'json'; + + // Clean the user provided output of a possible file ending + let outputFileName = output.endsWith(`.${format}`) + ? output.slice(0, -(format.length + 1)) + : output; + + // for multi language docs, include the language in the filename + if (includeLanguageInOutputName) { + outputFileName = `${outputFileName}.${lang}`; + } + + return ({ + readme, + language: Language.fromString(lang), + submodule, + allSubmodules, + splitBySubmodules, + format, + output: outputFileName, + }); + }; if (args.language.length <= 1) { await generateForLanguage(docs, options(args.language[0], args.output)); } else { for (const lang of args.language) { - const output = `${args.output ?? 'API'}.${lang}`; - await generateForLanguage(docs, options(lang, output)); + await generateForLanguage(docs, options(lang, args.output, true)); } } } diff --git a/test/__fixtures__/libraries/construct-library/lib/index.ts b/test/__fixtures__/libraries/construct-library/lib/index.ts index dc3063ea..42fd939c 100644 --- a/test/__fixtures__/libraries/construct-library/lib/index.ts +++ b/test/__fixtures__/libraries/construct-library/lib/index.ts @@ -5,6 +5,10 @@ export class GreeterBucket extends s3.Bucket { public greet() { console.log(this.bucketName); } + + public greetWithSalutation(salution: string) { + console.log(salution + ' ' + this.bucketName); + } } export * as submod1 from './submod1'; diff --git a/test/__fixtures__/libraries/construct-library/lib/submod1/index.ts b/test/__fixtures__/libraries/construct-library/lib/submod1/index.ts index 0aa7a334..6b640fa7 100644 --- a/test/__fixtures__/libraries/construct-library/lib/submod1/index.ts +++ b/test/__fixtures__/libraries/construct-library/lib/submod1/index.ts @@ -5,4 +5,8 @@ export class GoodbyeBucket extends s3.Bucket { public goodbye() { console.log(this.bucketName); } + + public goodbyeWithPhrase(phrase: string) { + console.log(phrase + ' ' + this.bucketName); + } } diff --git a/test/__snapshots__/cli.test.ts.snap b/test/__snapshots__/cli.test.ts.snap index 476e2c37..b2903e91 100644 --- a/test/__snapshots__/cli.test.ts.snap +++ b/test/__snapshots__/cli.test.ts.snap @@ -6239,6 +6239,6338 @@ first call to addToResourcePolicy(s). +" +`; + +exports[`specify languages and split-by-submodule creates submodule files next to output: API.python.md 1`] = ` +"# API Reference + +## Submodules + +The following submodules are available: + +- [submod1](./submod1.python.md) + +## Constructs + +### GreeterBucket + +#### Initializers + +\`\`\`python +import construct_library + +construct_library.GreeterBucket( + scope: Construct, + id: str, + access_control: BucketAccessControl = None, + auto_delete_objects: bool = None, + block_public_access: BlockPublicAccess = None, + bucket_key_enabled: bool = None, + bucket_name: str = None, + cors: typing.List[CorsRule] = None, + encryption: BucketEncryption = None, + encryption_key: IKey = None, + enforce_ss_l: bool = None, + event_bridge_enabled: bool = None, + intelligent_tiering_configurations: typing.List[IntelligentTieringConfiguration] = None, + inventories: typing.List[Inventory] = None, + lifecycle_rules: typing.List[LifecycleRule] = None, + metrics: typing.List[BucketMetrics] = None, + notifications_handler_role: IRole = None, + object_ownership: ObjectOwnership = None, + public_read_access: bool = None, + removal_policy: RemovalPolicy = None, + server_access_logs_bucket: IBucket = None, + server_access_logs_prefix: str = None, + transfer_acceleration: bool = None, + versioned: bool = None, + website_error_document: str = None, + website_index_document: str = None, + website_redirect: RedirectTarget = None, + website_routing_rules: typing.List[RoutingRule] = None +) +\`\`\` + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| scope | constructs.Construct | *No description.* | +| id | str | *No description.* | +| access_control | aws_cdk.aws_s3.BucketAccessControl | Specifies a canned ACL that grants predefined permissions to the bucket. | +| auto_delete_objects | bool | Whether all objects should be automatically deleted when the bucket is removed from the stack or when the stack is deleted. | +| block_public_access | aws_cdk.aws_s3.BlockPublicAccess | The block public access configuration of this bucket. | +| bucket_key_enabled | bool | Specifies whether Amazon S3 should use an S3 Bucket Key with server-side encryption using KMS (SSE-KMS) for new objects in the bucket. | +| bucket_name | str | Physical name of this bucket. | +| cors | typing.List[aws_cdk.aws_s3.CorsRule] | The CORS configuration of this bucket. | +| encryption | aws_cdk.aws_s3.BucketEncryption | The kind of server-side encryption to apply to this bucket. | +| encryption_key | aws_cdk.aws_kms.IKey | External KMS key to use for bucket encryption. | +| enforce_ss_l | bool | Enforces SSL for requests. | +| event_bridge_enabled | bool | Whether this bucket should send notifications to Amazon EventBridge or not. | +| intelligent_tiering_configurations | typing.List[aws_cdk.aws_s3.IntelligentTieringConfiguration] | Inteligent Tiering Configurations. | +| inventories | typing.List[aws_cdk.aws_s3.Inventory] | The inventory configuration of the bucket. | +| lifecycle_rules | typing.List[aws_cdk.aws_s3.LifecycleRule] | Rules that define how Amazon S3 manages objects during their lifetime. | +| metrics | typing.List[aws_cdk.aws_s3.BucketMetrics] | The metrics configuration of this bucket. | +| notifications_handler_role | aws_cdk.aws_iam.IRole | The role to be used by the notifications handler. | +| object_ownership | aws_cdk.aws_s3.ObjectOwnership | The objectOwnership of the bucket. | +| public_read_access | bool | Grants public read access to all objects in the bucket. | +| removal_policy | aws_cdk.core.RemovalPolicy | Policy to apply when the bucket is removed from this stack. | +| server_access_logs_bucket | aws_cdk.aws_s3.IBucket | Destination bucket for the server access logs. | +| server_access_logs_prefix | str | Optional log file prefix to use for the bucket's access logs. | +| transfer_acceleration | bool | Whether this bucket should have transfer acceleration turned on or not. | +| versioned | bool | Whether this bucket should have versioning turned on or not. | +| website_error_document | str | The name of the error document (e.g. "404.html") for the website. \`websiteIndexDocument\` must also be set if this is set. | +| website_index_document | str | The name of the index document (e.g. "index.html") for the website. Enables static website hosting for this bucket. | +| website_redirect | aws_cdk.aws_s3.RedirectTarget | Specifies the redirect behavior of all requests to a website endpoint of a bucket. | +| website_routing_rules | typing.List[aws_cdk.aws_s3.RoutingRule] | Rules that define when a redirect is applied and the redirect behavior. | + +--- + +##### \`scope\`Required + +- *Type:* constructs.Construct + +--- + +##### \`id\`Required + +- *Type:* str + +--- + +##### \`access_control\`Optional + +- *Type:* aws_cdk.aws_s3.BucketAccessControl +- *Default:* BucketAccessControl.PRIVATE + +Specifies a canned ACL that grants predefined permissions to the bucket. + +--- + +##### \`auto_delete_objects\`Optional + +- *Type:* bool +- *Default:* false + +Whether all objects should be automatically deleted when the bucket is removed from the stack or when the stack is deleted. + +Requires the \`removalPolicy\` to be set to \`RemovalPolicy.DESTROY\`. + +**Warning** if you have deployed a bucket with \`autoDeleteObjects: true\`, +switching this to \`false\` in a CDK version *before* \`1.126.0\` will lead to +all objects in the bucket being deleted. Be sure to update your bucket resources +by deploying with CDK version \`1.126.0\` or later **before** switching this value to \`false\`. + +--- + +##### \`block_public_access\`Optional + +- *Type:* aws_cdk.aws_s3.BlockPublicAccess +- *Default:* CloudFormation defaults will apply. New buckets and objects don't allow public access, but users can modify bucket policies or object permissions to allow public access + +The block public access configuration of this bucket. + +> [https://docs.aws.amazon.com/AmazonS3/latest/dev/access-control-block-public-access.html](https://docs.aws.amazon.com/AmazonS3/latest/dev/access-control-block-public-access.html) + +--- + +##### \`bucket_key_enabled\`Optional + +- *Type:* bool +- *Default:* false + +Specifies whether Amazon S3 should use an S3 Bucket Key with server-side encryption using KMS (SSE-KMS) for new objects in the bucket. + +Only relevant, when Encryption is set to {@link BucketEncryption.KMS} + +--- + +##### \`bucket_name\`Optional + +- *Type:* str +- *Default:* Assigned by CloudFormation (recommended). + +Physical name of this bucket. + +--- + +##### \`cors\`Optional + +- *Type:* typing.List[aws_cdk.aws_s3.CorsRule] +- *Default:* No CORS configuration. + +The CORS configuration of this bucket. + +> [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-s3-bucket-cors.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-s3-bucket-cors.html) + +--- + +##### \`encryption\`Optional + +- *Type:* aws_cdk.aws_s3.BucketEncryption +- *Default:* \`Kms\` if \`encryptionKey\` is specified, or \`Unencrypted\` otherwise. + +The kind of server-side encryption to apply to this bucket. + +If you choose KMS, you can specify a KMS key via \`encryptionKey\`. If +encryption key is not specified, a key will automatically be created. + +--- + +##### \`encryption_key\`Optional + +- *Type:* aws_cdk.aws_kms.IKey +- *Default:* If encryption is set to "Kms" and this property is undefined, a new KMS key will be created and associated with this bucket. + +External KMS key to use for bucket encryption. + +The 'encryption' property must be either not specified or set to "Kms". +An error will be emitted if encryption is set to "Unencrypted" or +"Managed". + +--- + +##### \`enforce_ss_l\`Optional + +- *Type:* bool +- *Default:* false + +Enforces SSL for requests. + +S3.5 of the AWS Foundational Security Best Practices Regarding S3. + +> [https://docs.aws.amazon.com/config/latest/developerguide/s3-bucket-ssl-requests-only.html](https://docs.aws.amazon.com/config/latest/developerguide/s3-bucket-ssl-requests-only.html) + +--- + +##### \`event_bridge_enabled\`Optional + +- *Type:* bool +- *Default:* false + +Whether this bucket should send notifications to Amazon EventBridge or not. + +--- + +##### \`intelligent_tiering_configurations\`Optional + +- *Type:* typing.List[aws_cdk.aws_s3.IntelligentTieringConfiguration] +- *Default:* No Intelligent Tiiering Configurations. + +Inteligent Tiering Configurations. + +> [https://docs.aws.amazon.com/AmazonS3/latest/userguide/intelligent-tiering.html](https://docs.aws.amazon.com/AmazonS3/latest/userguide/intelligent-tiering.html) + +--- + +##### \`inventories\`Optional + +- *Type:* typing.List[aws_cdk.aws_s3.Inventory] +- *Default:* No inventory configuration + +The inventory configuration of the bucket. + +> [https://docs.aws.amazon.com/AmazonS3/latest/dev/storage-inventory.html](https://docs.aws.amazon.com/AmazonS3/latest/dev/storage-inventory.html) + +--- + +##### \`lifecycle_rules\`Optional + +- *Type:* typing.List[aws_cdk.aws_s3.LifecycleRule] +- *Default:* No lifecycle rules. + +Rules that define how Amazon S3 manages objects during their lifetime. + +--- + +##### \`metrics\`Optional + +- *Type:* typing.List[aws_cdk.aws_s3.BucketMetrics] +- *Default:* No metrics configuration. + +The metrics configuration of this bucket. + +> [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-s3-bucket-metricsconfiguration.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-s3-bucket-metricsconfiguration.html) + +--- + +##### \`notifications_handler_role\`Optional + +- *Type:* aws_cdk.aws_iam.IRole +- *Default:* a new role will be created. + +The role to be used by the notifications handler. + +--- + +##### \`object_ownership\`Optional + +- *Type:* aws_cdk.aws_s3.ObjectOwnership +- *Default:* No ObjectOwnership configuration, uploading account will own the object. + +The objectOwnership of the bucket. + +> [https://docs.aws.amazon.com/AmazonS3/latest/dev/about-object-ownership.html](https://docs.aws.amazon.com/AmazonS3/latest/dev/about-object-ownership.html) + +--- + +##### \`public_read_access\`Optional + +- *Type:* bool +- *Default:* false + +Grants public read access to all objects in the bucket. + +Similar to calling \`bucket.grantPublicAccess()\` + +--- + +##### \`removal_policy\`Optional + +- *Type:* aws_cdk.core.RemovalPolicy +- *Default:* The bucket will be orphaned. + +Policy to apply when the bucket is removed from this stack. + +--- + +##### \`server_access_logs_bucket\`Optional + +- *Type:* aws_cdk.aws_s3.IBucket +- *Default:* If "serverAccessLogsPrefix" undefined - access logs disabled, otherwise - log to current bucket. + +Destination bucket for the server access logs. + +--- + +##### \`server_access_logs_prefix\`Optional + +- *Type:* str +- *Default:* No log file prefix + +Optional log file prefix to use for the bucket's access logs. + +If defined without "serverAccessLogsBucket", enables access logs to current bucket with this prefix. + +--- + +##### \`transfer_acceleration\`Optional + +- *Type:* bool +- *Default:* false + +Whether this bucket should have transfer acceleration turned on or not. + +--- + +##### \`versioned\`Optional + +- *Type:* bool +- *Default:* false + +Whether this bucket should have versioning turned on or not. + +--- + +##### \`website_error_document\`Optional + +- *Type:* str +- *Default:* No error document. + +The name of the error document (e.g. "404.html") for the website. \`websiteIndexDocument\` must also be set if this is set. + +--- + +##### \`website_index_document\`Optional + +- *Type:* str +- *Default:* No index document. + +The name of the index document (e.g. "index.html") for the website. Enables static website hosting for this bucket. + +--- + +##### \`website_redirect\`Optional + +- *Type:* aws_cdk.aws_s3.RedirectTarget +- *Default:* No redirection. + +Specifies the redirect behavior of all requests to a website endpoint of a bucket. + +If you specify this property, you can't specify "websiteIndexDocument", "websiteErrorDocument" nor , "websiteRoutingRules". + +--- + +##### \`website_routing_rules\`Optional + +- *Type:* typing.List[aws_cdk.aws_s3.RoutingRule] +- *Default:* No redirection rules. + +Rules that define when a redirect is applied and the redirect behavior. + +--- + +#### Methods + +| **Name** | **Description** | +| --- | --- | +| to_string | Returns a string representation of this construct. | +| apply_removal_policy | Apply the given removal policy to this resource. | +| add_event_notification | Adds a bucket notification event destination. | +| add_object_created_notification | Subscribes a destination to receive notifications when an object is created in the bucket. | +| add_object_removed_notification | Subscribes a destination to receive notifications when an object is removed from the bucket. | +| add_to_resource_policy | Adds a statement to the resource policy for a principal (i.e. account/role/service) to perform actions on this bucket and/or its contents. Use \`bucketArn\` and \`arnForObjects(keys)\` to obtain ARNs for this bucket or objects. | +| arn_for_objects | Returns an ARN that represents all objects within the bucket that match the key pattern specified. | +| grant_delete | Grants s3:DeleteObject* permission to an IAM principal for objects in this bucket. | +| grant_public_access | Allows unrestricted access to objects from this bucket. | +| grant_put | Grants s3:PutObject* and s3:Abort* permissions for this bucket to an IAM principal. | +| grant_put_acl | Grant the given IAM identity permissions to modify the ACLs of objects in the given Bucket. | +| grant_read | Grant read permissions for this bucket and it's contents to an IAM principal (Role/Group/User). | +| grant_read_write | Grants read/write permissions for this bucket and it's contents to an IAM principal (Role/Group/User). | +| grant_write | Grant write permissions to this bucket to an IAM principal. | +| on_cloud_trail_event | Define a CloudWatch event that triggers when something happens to this repository. | +| on_cloud_trail_put_object | Defines an AWS CloudWatch event that triggers when an object is uploaded to the specified paths (keys) in this bucket using the PutObject API call. | +| on_cloud_trail_write_object | Defines an AWS CloudWatch event that triggers when an object at the specified paths (keys) in this bucket are written to. | +| s3_url_for_object | The S3 URL of an S3 object. For example:. | +| transfer_acceleration_url_for_object | The https Transfer Acceleration URL of an S3 object. | +| url_for_object | The https URL of an S3 object. Specify \`regional: false\` at the options for non-regional URLs. For example:. | +| virtual_hosted_url_for_object | The virtual hosted-style URL of an S3 object. Specify \`regional: false\` at the options for non-regional URL. For example:. | +| add_cors_rule | Adds a cross-origin access configuration for objects in an Amazon S3 bucket. | +| add_inventory | Add an inventory configuration. | +| add_lifecycle_rule | Add a lifecycle rule to the bucket. | +| add_metric | Adds a metrics configuration for the CloudWatch request metrics from the bucket. | +| greet | *No description.* | +| greet_with_salutation | *No description.* | + +--- + +##### \`to_string\` + +\`\`\`python +def to_string() -> str +\`\`\` + +Returns a string representation of this construct. + +##### \`apply_removal_policy\` + +\`\`\`python +def apply_removal_policy( + policy: RemovalPolicy +) -> None +\`\`\` + +Apply the given removal policy to this resource. + +The Removal Policy controls what happens to this resource when it stops +being managed by CloudFormation, either because you've removed it from the +CDK application or because you've made a change that requires the resource +to be replaced. + +The resource can be deleted (\`RemovalPolicy.DESTROY\`), or left in your AWS +account for data recovery and cleanup later (\`RemovalPolicy.RETAIN\`). + +###### \`policy\`Required + +- *Type:* aws_cdk.core.RemovalPolicy + +--- + +##### \`add_event_notification\` + +\`\`\`python +def add_event_notification( + event: EventType, + dest: IBucketNotificationDestination, + prefix: str = None, + suffix: str = None +) -> None +\`\`\` + +Adds a bucket notification event destination. + +> [https://docs.aws.amazon.com/AmazonS3/latest/dev/NotificationHowTo.html](https://docs.aws.amazon.com/AmazonS3/latest/dev/NotificationHowTo.html) + +*Example* + +\`\`\`python + declare const myLambda: lambda.Function; + const bucket = new s3.Bucket(this, 'MyBucket'); + bucket.addEventNotification(s3.EventType.OBJECT_CREATED, new s3n.LambdaDestination(myLambda), {prefix: 'home/myusername/*'}); +\`\`\` + + +###### \`event\`Required + +- *Type:* aws_cdk.aws_s3.EventType + +The event to trigger the notification. + +--- + +###### \`dest\`Required + +- *Type:* aws_cdk.aws_s3.IBucketNotificationDestination + +The notification destination (Lambda, SNS Topic or SQS Queue). + +--- + +###### \`prefix\`Optional + +- *Type:* str + +S3 keys must have the specified prefix. + +--- + +###### \`suffix\`Optional + +- *Type:* str + +S3 keys must have the specified suffix. + +--- + +##### \`add_object_created_notification\` + +\`\`\`python +def add_object_created_notification( + dest: IBucketNotificationDestination, + prefix: str = None, + suffix: str = None +) -> None +\`\`\` + +Subscribes a destination to receive notifications when an object is created in the bucket. + +This is identical to calling +\`onEvent(EventType.OBJECT_CREATED)\`. + +###### \`dest\`Required + +- *Type:* aws_cdk.aws_s3.IBucketNotificationDestination + +The notification destination (see onEvent). + +--- + +###### \`prefix\`Optional + +- *Type:* str + +S3 keys must have the specified prefix. + +--- + +###### \`suffix\`Optional + +- *Type:* str + +S3 keys must have the specified suffix. + +--- + +##### \`add_object_removed_notification\` + +\`\`\`python +def add_object_removed_notification( + dest: IBucketNotificationDestination, + prefix: str = None, + suffix: str = None +) -> None +\`\`\` + +Subscribes a destination to receive notifications when an object is removed from the bucket. + +This is identical to calling +\`onEvent(EventType.OBJECT_REMOVED)\`. + +###### \`dest\`Required + +- *Type:* aws_cdk.aws_s3.IBucketNotificationDestination + +The notification destination (see onEvent). + +--- + +###### \`prefix\`Optional + +- *Type:* str + +S3 keys must have the specified prefix. + +--- + +###### \`suffix\`Optional + +- *Type:* str + +S3 keys must have the specified suffix. + +--- + +##### \`add_to_resource_policy\` + +\`\`\`python +def add_to_resource_policy( + permission: PolicyStatement +) -> AddToResourcePolicyResult +\`\`\` + +Adds a statement to the resource policy for a principal (i.e. account/role/service) to perform actions on this bucket and/or its contents. Use \`bucketArn\` and \`arnForObjects(keys)\` to obtain ARNs for this bucket or objects. + +Note that the policy statement may or may not be added to the policy. +For example, when an \`IBucket\` is created from an existing bucket, +it's not possible to tell whether the bucket already has a policy +attached, let alone to re-use that policy to add more statements to it. +So it's safest to do nothing in these cases. + +###### \`permission\`Required + +- *Type:* aws_cdk.aws_iam.PolicyStatement + +the policy statement to be added to the bucket's policy. + +--- + +##### \`arn_for_objects\` + +\`\`\`python +def arn_for_objects( + key_pattern: str +) -> str +\`\`\` + +Returns an ARN that represents all objects within the bucket that match the key pattern specified. + +To represent all keys, specify \`\`"*"\`\`. + +If you need to specify a keyPattern with multiple components, concatenate them into a single string, e.g.: + + arnForObjects(\`home/\${team}/\${user}/*\`) + +###### \`key_pattern\`Required + +- *Type:* str + +--- + +##### \`grant_delete\` + +\`\`\`python +def grant_delete( + identity: IGrantable, + objects_key_pattern: typing.Any = None +) -> Grant +\`\`\` + +Grants s3:DeleteObject* permission to an IAM principal for objects in this bucket. + +###### \`identity\`Required + +- *Type:* aws_cdk.aws_iam.IGrantable + +The principal. + +--- + +###### \`objects_key_pattern\`Optional + +- *Type:* typing.Any + +Restrict the permission to a certain key pattern (default '*'). + +--- + +##### \`grant_public_access\` + +\`\`\`python +def grant_public_access( + allowed_actions: str, + key_prefix: str = None +) -> Grant +\`\`\` + +Allows unrestricted access to objects from this bucket. + +IMPORTANT: This permission allows anyone to perform actions on S3 objects +in this bucket, which is useful for when you configure your bucket as a +website and want everyone to be able to read objects in the bucket without +needing to authenticate. + +Without arguments, this method will grant read ("s3:GetObject") access to +all objects ("*") in the bucket. + +The method returns the \`iam.Grant\` object, which can then be modified +as needed. For example, you can add a condition that will restrict access only +to an IPv4 range like this: + + const grant = bucket.grantPublicAccess(); + grant.resourceStatement!.addCondition(‘IpAddress’, { “aws:SourceIp”: “54.240.143.0/24” }); + +Note that if this \`IBucket\` refers to an existing bucket, possibly not +managed by CloudFormation, this method will have no effect, since it's +impossible to modify the policy of an existing bucket. + +###### \`allowed_actions\`Required + +- *Type:* str + +the set of S3 actions to allow. + +Default is "s3:GetObject". + +--- + +###### \`key_prefix\`Optional + +- *Type:* str + +the prefix of S3 object keys (e.g. \`home/*\`). Default is "*". + +--- + +##### \`grant_put\` + +\`\`\`python +def grant_put( + identity: IGrantable, + objects_key_pattern: typing.Any = None +) -> Grant +\`\`\` + +Grants s3:PutObject* and s3:Abort* permissions for this bucket to an IAM principal. + +If encryption is used, permission to use the key to encrypt the contents +of written files will also be granted to the same principal. + +###### \`identity\`Required + +- *Type:* aws_cdk.aws_iam.IGrantable + +The principal. + +--- + +###### \`objects_key_pattern\`Optional + +- *Type:* typing.Any + +Restrict the permission to a certain key pattern (default '*'). + +--- + +##### \`grant_put_acl\` + +\`\`\`python +def grant_put_acl( + identity: IGrantable, + objects_key_pattern: str = None +) -> Grant +\`\`\` + +Grant the given IAM identity permissions to modify the ACLs of objects in the given Bucket. + +If your application has the '@aws-cdk/aws-s3:grantWriteWithoutAcl' feature flag set, +calling {@link grantWrite} or {@link grantReadWrite} no longer grants permissions to modify the ACLs of the objects; +in this case, if you need to modify object ACLs, call this method explicitly. + +###### \`identity\`Required + +- *Type:* aws_cdk.aws_iam.IGrantable + +--- + +###### \`objects_key_pattern\`Optional + +- *Type:* str + +--- + +##### \`grant_read\` + +\`\`\`python +def grant_read( + identity: IGrantable, + objects_key_pattern: typing.Any = None +) -> Grant +\`\`\` + +Grant read permissions for this bucket and it's contents to an IAM principal (Role/Group/User). + +If encryption is used, permission to use the key to decrypt the contents +of the bucket will also be granted to the same principal. + +###### \`identity\`Required + +- *Type:* aws_cdk.aws_iam.IGrantable + +The principal. + +--- + +###### \`objects_key_pattern\`Optional + +- *Type:* typing.Any + +Restrict the permission to a certain key pattern (default '*'). + +--- + +##### \`grant_read_write\` + +\`\`\`python +def grant_read_write( + identity: IGrantable, + objects_key_pattern: typing.Any = None +) -> Grant +\`\`\` + +Grants read/write permissions for this bucket and it's contents to an IAM principal (Role/Group/User). + +If an encryption key is used, permission to use the key for +encrypt/decrypt will also be granted. + +Before CDK version 1.85.0, this method granted the \`s3:PutObject*\` permission that included \`s3:PutObjectAcl\`, +which could be used to grant read/write object access to IAM principals in other accounts. +If you want to get rid of that behavior, update your CDK version to 1.85.0 or later, +and make sure the \`@aws-cdk/aws-s3:grantWriteWithoutAcl\` feature flag is set to \`true\` +in the \`context\` key of your cdk.json file. +If you've already updated, but still need the principal to have permissions to modify the ACLs, +use the {@link grantPutAcl} method. + +###### \`identity\`Required + +- *Type:* aws_cdk.aws_iam.IGrantable + +--- + +###### \`objects_key_pattern\`Optional + +- *Type:* typing.Any + +--- + +##### \`grant_write\` + +\`\`\`python +def grant_write( + identity: IGrantable, + objects_key_pattern: typing.Any = None +) -> Grant +\`\`\` + +Grant write permissions to this bucket to an IAM principal. + +If encryption is used, permission to use the key to encrypt the contents +of written files will also be granted to the same principal. + +Before CDK version 1.85.0, this method granted the \`s3:PutObject*\` permission that included \`s3:PutObjectAcl\`, +which could be used to grant read/write object access to IAM principals in other accounts. +If you want to get rid of that behavior, update your CDK version to 1.85.0 or later, +and make sure the \`@aws-cdk/aws-s3:grantWriteWithoutAcl\` feature flag is set to \`true\` +in the \`context\` key of your cdk.json file. +If you've already updated, but still need the principal to have permissions to modify the ACLs, +use the {@link grantPutAcl} method. + +###### \`identity\`Required + +- *Type:* aws_cdk.aws_iam.IGrantable + +--- + +###### \`objects_key_pattern\`Optional + +- *Type:* typing.Any + +--- + +##### \`on_cloud_trail_event\` + +\`\`\`python +def on_cloud_trail_event( + id: str, + description: str = None, + event_pattern: EventPattern = None, + rule_name: str = None, + target: IRuleTarget = None, + paths: typing.List[str] = None +) -> Rule +\`\`\` + +Define a CloudWatch event that triggers when something happens to this repository. + +Requires that there exists at least one CloudTrail Trail in your account +that captures the event. This method will not create the Trail. + +###### \`id\`Required + +- *Type:* str + +The id of the rule. + +--- + +###### \`description\`Optional + +- *Type:* str +- *Default:* No description + +A description of the rule's purpose. + +--- + +###### \`event_pattern\`Optional + +- *Type:* aws_cdk.aws_events.EventPattern +- *Default:* No additional filtering based on an event pattern. + +Additional restrictions for the event to route to the specified target. + +The method that generates the rule probably imposes some type of event +filtering. The filtering implied by what you pass here is added +on top of that filtering. + +> [https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-and-event-patterns.html](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-and-event-patterns.html) + +--- + +###### \`rule_name\`Optional + +- *Type:* str +- *Default:* AWS CloudFormation generates a unique physical ID. + +A name for the rule. + +--- + +###### \`target\`Optional + +- *Type:* aws_cdk.aws_events.IRuleTarget +- *Default:* No target is added to the rule. Use \`addTarget()\` to add a target. + +The target to register for the event. + +--- + +###### \`paths\`Optional + +- *Type:* typing.List[str] +- *Default:* Watch changes to all objects + +Only watch changes to these object paths. + +--- + +##### \`on_cloud_trail_put_object\` + +\`\`\`python +def on_cloud_trail_put_object( + id: str, + description: str = None, + event_pattern: EventPattern = None, + rule_name: str = None, + target: IRuleTarget = None, + paths: typing.List[str] = None +) -> Rule +\`\`\` + +Defines an AWS CloudWatch event that triggers when an object is uploaded to the specified paths (keys) in this bucket using the PutObject API call. + +Note that some tools like \`aws s3 cp\` will automatically use either +PutObject or the multipart upload API depending on the file size, +so using \`onCloudTrailWriteObject\` may be preferable. + +Requires that there exists at least one CloudTrail Trail in your account +that captures the event. This method will not create the Trail. + +###### \`id\`Required + +- *Type:* str + +The id of the rule. + +--- + +###### \`description\`Optional + +- *Type:* str +- *Default:* No description + +A description of the rule's purpose. + +--- + +###### \`event_pattern\`Optional + +- *Type:* aws_cdk.aws_events.EventPattern +- *Default:* No additional filtering based on an event pattern. + +Additional restrictions for the event to route to the specified target. + +The method that generates the rule probably imposes some type of event +filtering. The filtering implied by what you pass here is added +on top of that filtering. + +> [https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-and-event-patterns.html](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-and-event-patterns.html) + +--- + +###### \`rule_name\`Optional + +- *Type:* str +- *Default:* AWS CloudFormation generates a unique physical ID. + +A name for the rule. + +--- + +###### \`target\`Optional + +- *Type:* aws_cdk.aws_events.IRuleTarget +- *Default:* No target is added to the rule. Use \`addTarget()\` to add a target. + +The target to register for the event. + +--- + +###### \`paths\`Optional + +- *Type:* typing.List[str] +- *Default:* Watch changes to all objects + +Only watch changes to these object paths. + +--- + +##### \`on_cloud_trail_write_object\` + +\`\`\`python +def on_cloud_trail_write_object( + id: str, + description: str = None, + event_pattern: EventPattern = None, + rule_name: str = None, + target: IRuleTarget = None, + paths: typing.List[str] = None +) -> Rule +\`\`\` + +Defines an AWS CloudWatch event that triggers when an object at the specified paths (keys) in this bucket are written to. + +This includes +the events PutObject, CopyObject, and CompleteMultipartUpload. + +Note that some tools like \`aws s3 cp\` will automatically use either +PutObject or the multipart upload API depending on the file size, +so using this method may be preferable to \`onCloudTrailPutObject\`. + +Requires that there exists at least one CloudTrail Trail in your account +that captures the event. This method will not create the Trail. + +###### \`id\`Required + +- *Type:* str + +The id of the rule. + +--- + +###### \`description\`Optional + +- *Type:* str +- *Default:* No description + +A description of the rule's purpose. + +--- + +###### \`event_pattern\`Optional + +- *Type:* aws_cdk.aws_events.EventPattern +- *Default:* No additional filtering based on an event pattern. + +Additional restrictions for the event to route to the specified target. + +The method that generates the rule probably imposes some type of event +filtering. The filtering implied by what you pass here is added +on top of that filtering. + +> [https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-and-event-patterns.html](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-and-event-patterns.html) + +--- + +###### \`rule_name\`Optional + +- *Type:* str +- *Default:* AWS CloudFormation generates a unique physical ID. + +A name for the rule. + +--- + +###### \`target\`Optional + +- *Type:* aws_cdk.aws_events.IRuleTarget +- *Default:* No target is added to the rule. Use \`addTarget()\` to add a target. + +The target to register for the event. + +--- + +###### \`paths\`Optional + +- *Type:* typing.List[str] +- *Default:* Watch changes to all objects + +Only watch changes to these object paths. + +--- + +##### \`s3_url_for_object\` + +\`\`\`python +def s3_url_for_object( + key: str = None +) -> str +\`\`\` + +The S3 URL of an S3 object. For example:. + +\`s3://onlybucket\` +- \`s3://bucket/key\` + +###### \`key\`Optional + +- *Type:* str + +The S3 key of the object. + +If not specified, the S3 URL of the +bucket is returned. + +--- + +##### \`transfer_acceleration_url_for_object\` + +\`\`\`python +def transfer_acceleration_url_for_object( + key: str = None, + dual_stack: bool = None +) -> str +\`\`\` + +The https Transfer Acceleration URL of an S3 object. + +Specify \`dualStack: true\` at the options +for dual-stack endpoint (connect to the bucket over IPv6). For example: + +- \`https://bucket.s3-accelerate.amazonaws.com\` +- \`https://bucket.s3-accelerate.amazonaws.com/key\` + +###### \`key\`Optional + +- *Type:* str + +The S3 key of the object. + +If not specified, the URL of the +bucket is returned. + +--- + +###### \`dual_stack\`Optional + +- *Type:* bool +- *Default:* false + +Dual-stack support to connect to the bucket over IPv6. + +--- + +##### \`url_for_object\` + +\`\`\`python +def url_for_object( + key: str = None +) -> str +\`\`\` + +The https URL of an S3 object. Specify \`regional: false\` at the options for non-regional URLs. For example:. + +\`https://s3.us-west-1.amazonaws.com/onlybucket\` +- \`https://s3.us-west-1.amazonaws.com/bucket/key\` +- \`https://s3.cn-north-1.amazonaws.com.cn/china-bucket/mykey\` + +###### \`key\`Optional + +- *Type:* str + +The S3 key of the object. + +If not specified, the URL of the +bucket is returned. + +--- + +##### \`virtual_hosted_url_for_object\` + +\`\`\`python +def virtual_hosted_url_for_object( + key: str = None, + regional: bool = None +) -> str +\`\`\` + +The virtual hosted-style URL of an S3 object. Specify \`regional: false\` at the options for non-regional URL. For example:. + +\`https://only-bucket.s3.us-west-1.amazonaws.com\` +- \`https://bucket.s3.us-west-1.amazonaws.com/key\` +- \`https://bucket.s3.amazonaws.com/key\` +- \`https://china-bucket.s3.cn-north-1.amazonaws.com.cn/mykey\` + +###### \`key\`Optional + +- *Type:* str + +The S3 key of the object. + +If not specified, the URL of the +bucket is returned. + +--- + +###### \`regional\`Optional + +- *Type:* bool +- *Default:* true + +Specifies the URL includes the region. + +--- + +##### \`add_cors_rule\` + +\`\`\`python +def add_cors_rule( + allowed_methods: typing.List[HttpMethods], + allowed_origins: typing.List[str], + allowed_headers: typing.List[str] = None, + exposed_headers: typing.List[str] = None, + id: str = None, + max_age: typing.Union[int, float] = None +) -> None +\`\`\` + +Adds a cross-origin access configuration for objects in an Amazon S3 bucket. + +###### \`allowed_methods\`Required + +- *Type:* typing.List[aws_cdk.aws_s3.HttpMethods] + +An HTTP method that you allow the origin to execute. + +--- + +###### \`allowed_origins\`Required + +- *Type:* typing.List[str] + +One or more origins you want customers to be able to access the bucket from. + +--- + +###### \`allowed_headers\`Optional + +- *Type:* typing.List[str] +- *Default:* No headers allowed. + +Headers that are specified in the Access-Control-Request-Headers header. + +--- + +###### \`exposed_headers\`Optional + +- *Type:* typing.List[str] +- *Default:* No headers exposed. + +One or more headers in the response that you want customers to be able to access from their applications. + +--- + +###### \`id\`Optional + +- *Type:* str +- *Default:* No id specified. + +A unique identifier for this rule. + +--- + +###### \`max_age\`Optional + +- *Type:* typing.Union[int, float] +- *Default:* No caching. + +The time in seconds that your browser is to cache the preflight response for the specified resource. + +--- + +##### \`add_inventory\` + +\`\`\`python +def add_inventory( + destination: InventoryDestination, + enabled: bool = None, + format: InventoryFormat = None, + frequency: InventoryFrequency = None, + include_object_versions: InventoryObjectVersion = None, + inventory_id: str = None, + objects_prefix: str = None, + optional_fields: typing.List[str] = None +) -> None +\`\`\` + +Add an inventory configuration. + +###### \`destination\`Required + +- *Type:* aws_cdk.aws_s3.InventoryDestination + +The destination of the inventory. + +--- + +###### \`enabled\`Optional + +- *Type:* bool +- *Default:* true + +Whether the inventory is enabled or disabled. + +--- + +###### \`format\`Optional + +- *Type:* aws_cdk.aws_s3.InventoryFormat +- *Default:* InventoryFormat.CSV + +The format of the inventory. + +--- + +###### \`frequency\`Optional + +- *Type:* aws_cdk.aws_s3.InventoryFrequency +- *Default:* InventoryFrequency.WEEKLY + +Frequency at which the inventory should be generated. + +--- + +###### \`include_object_versions\`Optional + +- *Type:* aws_cdk.aws_s3.InventoryObjectVersion +- *Default:* InventoryObjectVersion.ALL + +If the inventory should contain all the object versions or only the current one. + +--- + +###### \`inventory_id\`Optional + +- *Type:* str +- *Default:* generated ID. + +The inventory configuration ID. + +--- + +###### \`objects_prefix\`Optional + +- *Type:* str +- *Default:* No objects prefix + +The inventory will only include objects that meet the prefix filter criteria. + +--- + +###### \`optional_fields\`Optional + +- *Type:* typing.List[str] +- *Default:* No optional fields. + +A list of optional fields to be included in the inventory result. + +--- + +##### \`add_lifecycle_rule\` + +\`\`\`python +def add_lifecycle_rule( + abort_incomplete_multipart_upload_after: Duration = None, + enabled: bool = None, + expiration: Duration = None, + expiration_date: datetime.datetime = None, + expired_object_delete_marker: bool = None, + id: str = None, + noncurrent_version_expiration: Duration = None, + noncurrent_versions_to_retain: typing.Union[int, float] = None, + noncurrent_version_transitions: typing.List[NoncurrentVersionTransition] = None, + object_size_greater_than: typing.Union[int, float] = None, + object_size_less_than: typing.Union[int, float] = None, + prefix: str = None, + tag_filters: typing.Mapping[typing.Any] = None, + transitions: typing.List[Transition] = None +) -> None +\`\`\` + +Add a lifecycle rule to the bucket. + +###### \`abort_incomplete_multipart_upload_after\`Optional + +- *Type:* aws_cdk.core.Duration +- *Default:* Incomplete uploads are never aborted + +Specifies a lifecycle rule that aborts incomplete multipart uploads to an Amazon S3 bucket. + +The AbortIncompleteMultipartUpload property type creates a lifecycle +rule that aborts incomplete multipart uploads to an Amazon S3 bucket. +When Amazon S3 aborts a multipart upload, it deletes all parts +associated with the multipart upload. + +--- + +###### \`enabled\`Optional + +- *Type:* bool +- *Default:* true + +Whether this rule is enabled. + +--- + +###### \`expiration\`Optional + +- *Type:* aws_cdk.core.Duration +- *Default:* No expiration timeout + +Indicates the number of days after creation when objects are deleted from Amazon S3 and Amazon Glacier. + +If you specify an expiration and transition time, you must use the same +time unit for both properties (either in days or by date). The +expiration time must also be later than the transition time. + +--- + +###### \`expiration_date\`Optional + +- *Type:* datetime.datetime +- *Default:* No expiration date + +Indicates when objects are deleted from Amazon S3 and Amazon Glacier. + +The date value must be in ISO 8601 format. The time is always midnight UTC. + +If you specify an expiration and transition time, you must use the same +time unit for both properties (either in days or by date). The +expiration time must also be later than the transition time. + +--- + +###### \`expired_object_delete_marker\`Optional + +- *Type:* bool +- *Default:* false + +Indicates whether Amazon S3 will remove a delete marker with no noncurrent versions. + +If set to true, the delete marker will be expired. + +--- + +###### \`id\`Optional + +- *Type:* str + +A unique identifier for this rule. + +The value cannot be more than 255 characters. + +--- + +###### \`noncurrent_version_expiration\`Optional + +- *Type:* aws_cdk.core.Duration +- *Default:* No noncurrent version expiration + +Time between when a new version of the object is uploaded to the bucket and when old versions of the object expire. + +For buckets with versioning enabled (or suspended), specifies the time, +in days, between when a new version of the object is uploaded to the +bucket and when old versions of the object expire. When object versions +expire, Amazon S3 permanently deletes them. If you specify a transition +and expiration time, the expiration time must be later than the +transition time. + +--- + +###### \`noncurrent_versions_to_retain\`Optional + +- *Type:* typing.Union[int, float] +- *Default:* No noncurrent versions to retain + +Indicates a maximum number of noncurrent versions to retain. + +If there are this many more noncurrent versions, +Amazon S3 permanently deletes them. + +--- + +###### \`noncurrent_version_transitions\`Optional + +- *Type:* typing.List[aws_cdk.aws_s3.NoncurrentVersionTransition] + +One or more transition rules that specify when non-current objects transition to a specified storage class. + +Only for for buckets with versioning enabled (or suspended). + +If you specify a transition and expiration time, the expiration time +must be later than the transition time. + +--- + +###### \`object_size_greater_than\`Optional + +- *Type:* typing.Union[int, float] +- *Default:* No rule + +Specifies the minimum object size in bytes for this rule to apply to. + +--- + +###### \`object_size_less_than\`Optional + +- *Type:* typing.Union[int, float] +- *Default:* No rule + +Specifies the maximum object size in bytes for this rule to apply to. + +--- + +###### \`prefix\`Optional + +- *Type:* str +- *Default:* Rule applies to all objects + +Object key prefix that identifies one or more objects to which this rule applies. + +--- + +###### \`tag_filters\`Optional + +- *Type:* typing.Mapping[typing.Any] +- *Default:* Rule applies to all objects + +The TagFilter property type specifies tags to use to identify a subset of objects for an Amazon S3 bucket. + +--- + +###### \`transitions\`Optional + +- *Type:* typing.List[aws_cdk.aws_s3.Transition] +- *Default:* No transition rules + +One or more transition rules that specify when an object transitions to a specified storage class. + +If you specify an expiration and transition time, you must use the same +time unit for both properties (either in days or by date). The +expiration time must also be later than the transition time. + +--- + +##### \`add_metric\` + +\`\`\`python +def add_metric( + id: str, + prefix: str = None, + tag_filters: typing.Mapping[typing.Any] = None +) -> None +\`\`\` + +Adds a metrics configuration for the CloudWatch request metrics from the bucket. + +###### \`id\`Required + +- *Type:* str + +The ID used to identify the metrics configuration. + +--- + +###### \`prefix\`Optional + +- *Type:* str + +The prefix that an object must have to be included in the metrics results. + +--- + +###### \`tag_filters\`Optional + +- *Type:* typing.Mapping[typing.Any] + +Specifies a list of tag filters to use as a metrics configuration filter. + +The metrics configuration includes only objects that meet the filter's criteria. + +--- + +##### \`greet\` + +\`\`\`python +def greet() -> None +\`\`\` + +##### \`greet_with_salutation\` + +\`\`\`python +def greet_with_salutation( + salution: str +) -> None +\`\`\` + +###### \`salution\`Required + +- *Type:* str + +--- + +#### Static Functions + +| **Name** | **Description** | +| --- | --- | +| is_construct | Return whether the given object is a Construct. | +| is_resource | Check whether the given construct is a Resource. | +| from_bucket_arn | *No description.* | +| from_bucket_attributes | Creates a Bucket construct that represents an external bucket. | +| from_bucket_name | *No description.* | +| validate_bucket_name | Thrown an exception if the given bucket name is not valid. | + +--- + +##### \`is_construct\` + +\`\`\`python +import construct_library + +construct_library.GreeterBucket.is_construct( + x: typing.Any +) +\`\`\` + +Return whether the given object is a Construct. + +###### \`x\`Required + +- *Type:* typing.Any + +--- + +##### \`is_resource\` + +\`\`\`python +import construct_library + +construct_library.GreeterBucket.is_resource( + construct: IConstruct +) +\`\`\` + +Check whether the given construct is a Resource. + +###### \`construct\`Required + +- *Type:* aws_cdk.core.IConstruct + +--- + +##### \`from_bucket_arn\` + +\`\`\`python +import construct_library + +construct_library.GreeterBucket.from_bucket_arn( + scope: Construct, + id: str, + bucket_arn: str +) +\`\`\` + +###### \`scope\`Required + +- *Type:* constructs.Construct + +--- + +###### \`id\`Required + +- *Type:* str + +--- + +###### \`bucket_arn\`Required + +- *Type:* str + +--- + +##### \`from_bucket_attributes\` + +\`\`\`python +import construct_library + +construct_library.GreeterBucket.from_bucket_attributes( + scope: Construct, + id: str, + account: str = None, + bucket_arn: str = None, + bucket_domain_name: str = None, + bucket_dual_stack_domain_name: str = None, + bucket_name: str = None, + bucket_regional_domain_name: str = None, + bucket_website_new_url_format: bool = None, + bucket_website_url: str = None, + encryption_key: IKey = None, + is_website: bool = None, + notifications_handler_role: IRole = None, + region: str = None +) +\`\`\` + +Creates a Bucket construct that represents an external bucket. + +###### \`scope\`Required + +- *Type:* constructs.Construct + +The parent creating construct (usually \`this\`). + +--- + +###### \`id\`Required + +- *Type:* str + +The construct's name. + +--- + +###### \`account\`Optional + +- *Type:* str +- *Default:* it's assumed the bucket belongs to the same account as the scope it's being imported into + +The account this existing bucket belongs to. + +--- + +###### \`bucket_arn\`Optional + +- *Type:* str + +The ARN of the bucket. + +At least one of bucketArn or bucketName must be +defined in order to initialize a bucket ref. + +--- + +###### \`bucket_domain_name\`Optional + +- *Type:* str +- *Default:* Inferred from bucket name + +The domain name of the bucket. + +--- + +###### \`bucket_dual_stack_domain_name\`Optional + +- *Type:* str + +The IPv6 DNS name of the specified bucket. + +--- + +###### \`bucket_name\`Optional + +- *Type:* str + +The name of the bucket. + +If the underlying value of ARN is a string, the +name will be parsed from the ARN. Otherwise, the name is optional, but +some features that require the bucket name such as auto-creating a bucket +policy, won't work. + +--- + +###### \`bucket_regional_domain_name\`Optional + +- *Type:* str + +The regional domain name of the specified bucket. + +--- + +###### \`bucket_website_new_url_format\`Optional + +- *Type:* bool +- *Default:* false + +The format of the website URL of the bucket. + +This should be true for +regions launched since 2014. + +--- + +###### \`bucket_website_url\`Optional + +- *Type:* str +- *Default:* Inferred from bucket name + +The website URL of the bucket (if static web hosting is enabled). + +--- + +###### \`encryption_key\`Optional + +- *Type:* aws_cdk.aws_kms.IKey + +--- + +###### \`is_website\`Optional + +- *Type:* bool +- *Default:* false + +If this bucket has been configured for static website hosting. + +--- + +###### \`notifications_handler_role\`Optional + +- *Type:* aws_cdk.aws_iam.IRole +- *Default:* a new role will be created. + +The role to be used by the notifications handler. + +--- + +###### \`region\`Optional + +- *Type:* str +- *Default:* it's assumed the bucket is in the same region as the scope it's being imported into + +The region this existing bucket is in. + +--- + +##### \`from_bucket_name\` + +\`\`\`python +import construct_library + +construct_library.GreeterBucket.from_bucket_name( + scope: Construct, + id: str, + bucket_name: str +) +\`\`\` + +###### \`scope\`Required + +- *Type:* constructs.Construct + +--- + +###### \`id\`Required + +- *Type:* str + +--- + +###### \`bucket_name\`Required + +- *Type:* str + +--- + +##### \`validate_bucket_name\` + +\`\`\`python +import construct_library + +construct_library.GreeterBucket.validate_bucket_name( + physical_name: str +) +\`\`\` + +Thrown an exception if the given bucket name is not valid. + +###### \`physical_name\`Required + +- *Type:* str + +name of the bucket. + +--- + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| node | aws_cdk.core.ConstructNode | The construct tree node associated with this construct. | +| env | aws_cdk.core.ResourceEnvironment | The environment this resource belongs to. | +| stack | aws_cdk.core.Stack | The stack in which this resource is defined. | +| bucket_arn | str | The ARN of the bucket. | +| bucket_domain_name | str | The IPv4 DNS name of the specified bucket. | +| bucket_dual_stack_domain_name | str | The IPv6 DNS name of the specified bucket. | +| bucket_name | str | The name of the bucket. | +| bucket_regional_domain_name | str | The regional domain name of the specified bucket. | +| bucket_website_domain_name | str | The Domain name of the static website. | +| bucket_website_url | str | The URL of the static website. | +| encryption_key | aws_cdk.aws_kms.IKey | Optional KMS encryption key associated with this bucket. | +| is_website | bool | If this bucket has been configured for static website hosting. | +| policy | aws_cdk.aws_s3.BucketPolicy | The resource policy associated with this bucket. | + +--- + +##### \`node\`Required + +\`\`\`python +node: ConstructNode +\`\`\` + +- *Type:* aws_cdk.core.ConstructNode + +The construct tree node associated with this construct. + +--- + +##### \`env\`Required + +\`\`\`python +env: ResourceEnvironment +\`\`\` + +- *Type:* aws_cdk.core.ResourceEnvironment + +The environment this resource belongs to. + +For resources that are created and managed by the CDK +(generally, those created by creating new class instances like Role, Bucket, etc.), +this is always the same as the environment of the stack they belong to; +however, for imported resources +(those obtained from static methods like fromRoleArn, fromBucketName, etc.), +that might be different than the stack they were imported into. + +--- + +##### \`stack\`Required + +\`\`\`python +stack: Stack +\`\`\` + +- *Type:* aws_cdk.core.Stack + +The stack in which this resource is defined. + +--- + +##### \`bucket_arn\`Required + +\`\`\`python +bucket_arn: str +\`\`\` + +- *Type:* str + +The ARN of the bucket. + +--- + +##### \`bucket_domain_name\`Required + +\`\`\`python +bucket_domain_name: str +\`\`\` + +- *Type:* str + +The IPv4 DNS name of the specified bucket. + +--- + +##### \`bucket_dual_stack_domain_name\`Required + +\`\`\`python +bucket_dual_stack_domain_name: str +\`\`\` + +- *Type:* str + +The IPv6 DNS name of the specified bucket. + +--- + +##### \`bucket_name\`Required + +\`\`\`python +bucket_name: str +\`\`\` + +- *Type:* str + +The name of the bucket. + +--- + +##### \`bucket_regional_domain_name\`Required + +\`\`\`python +bucket_regional_domain_name: str +\`\`\` + +- *Type:* str + +The regional domain name of the specified bucket. + +--- + +##### \`bucket_website_domain_name\`Required + +\`\`\`python +bucket_website_domain_name: str +\`\`\` + +- *Type:* str + +The Domain name of the static website. + +--- + +##### \`bucket_website_url\`Required + +\`\`\`python +bucket_website_url: str +\`\`\` + +- *Type:* str + +The URL of the static website. + +--- + +##### \`encryption_key\`Optional + +\`\`\`python +encryption_key: IKey +\`\`\` + +- *Type:* aws_cdk.aws_kms.IKey + +Optional KMS encryption key associated with this bucket. + +--- + +##### \`is_website\`Optional + +\`\`\`python +is_website: bool +\`\`\` + +- *Type:* bool + +If this bucket has been configured for static website hosting. + +--- + +##### \`policy\`Optional + +\`\`\`python +policy: BucketPolicy +\`\`\` + +- *Type:* aws_cdk.aws_s3.BucketPolicy + +The resource policy associated with this bucket. + +If \`autoCreatePolicy\` is true, a \`BucketPolicy\` will be created upon the +first call to addToResourcePolicy(s). + +--- + + + + + +" +`; + +exports[`specify languages and split-by-submodule creates submodule files next to output: API.typescript.md 1`] = ` +"# API Reference + +## Submodules + +The following submodules are available: + +- [submod1](./submod1.typescript.md) + +## Constructs + +### GreeterBucket + +#### Initializers + +\`\`\`typescript +import { GreeterBucket } from 'construct-library' + +new GreeterBucket(scope: Construct, id: string, props?: BucketProps) +\`\`\` + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| scope | constructs.Construct | *No description.* | +| id | string | *No description.* | +| props | @aws-cdk/aws-s3.BucketProps | *No description.* | + +--- + +##### \`scope\`Required + +- *Type:* constructs.Construct + +--- + +##### \`id\`Required + +- *Type:* string + +--- + +##### \`props\`Optional + +- *Type:* @aws-cdk/aws-s3.BucketProps + +--- + +#### Methods + +| **Name** | **Description** | +| --- | --- | +| toString | Returns a string representation of this construct. | +| applyRemovalPolicy | Apply the given removal policy to this resource. | +| addEventNotification | Adds a bucket notification event destination. | +| addObjectCreatedNotification | Subscribes a destination to receive notifications when an object is created in the bucket. | +| addObjectRemovedNotification | Subscribes a destination to receive notifications when an object is removed from the bucket. | +| addToResourcePolicy | Adds a statement to the resource policy for a principal (i.e. account/role/service) to perform actions on this bucket and/or its contents. Use \`bucketArn\` and \`arnForObjects(keys)\` to obtain ARNs for this bucket or objects. | +| arnForObjects | Returns an ARN that represents all objects within the bucket that match the key pattern specified. | +| grantDelete | Grants s3:DeleteObject* permission to an IAM principal for objects in this bucket. | +| grantPublicAccess | Allows unrestricted access to objects from this bucket. | +| grantPut | Grants s3:PutObject* and s3:Abort* permissions for this bucket to an IAM principal. | +| grantPutAcl | Grant the given IAM identity permissions to modify the ACLs of objects in the given Bucket. | +| grantRead | Grant read permissions for this bucket and it's contents to an IAM principal (Role/Group/User). | +| grantReadWrite | Grants read/write permissions for this bucket and it's contents to an IAM principal (Role/Group/User). | +| grantWrite | Grant write permissions to this bucket to an IAM principal. | +| onCloudTrailEvent | Define a CloudWatch event that triggers when something happens to this repository. | +| onCloudTrailPutObject | Defines an AWS CloudWatch event that triggers when an object is uploaded to the specified paths (keys) in this bucket using the PutObject API call. | +| onCloudTrailWriteObject | Defines an AWS CloudWatch event that triggers when an object at the specified paths (keys) in this bucket are written to. | +| s3UrlForObject | The S3 URL of an S3 object. For example:. | +| transferAccelerationUrlForObject | The https Transfer Acceleration URL of an S3 object. | +| urlForObject | The https URL of an S3 object. Specify \`regional: false\` at the options for non-regional URLs. For example:. | +| virtualHostedUrlForObject | The virtual hosted-style URL of an S3 object. Specify \`regional: false\` at the options for non-regional URL. For example:. | +| addCorsRule | Adds a cross-origin access configuration for objects in an Amazon S3 bucket. | +| addInventory | Add an inventory configuration. | +| addLifecycleRule | Add a lifecycle rule to the bucket. | +| addMetric | Adds a metrics configuration for the CloudWatch request metrics from the bucket. | +| greet | *No description.* | +| greetWithSalutation | *No description.* | + +--- + +##### \`toString\` + +\`\`\`typescript +public toString(): string +\`\`\` + +Returns a string representation of this construct. + +##### \`applyRemovalPolicy\` + +\`\`\`typescript +public applyRemovalPolicy(policy: RemovalPolicy): void +\`\`\` + +Apply the given removal policy to this resource. + +The Removal Policy controls what happens to this resource when it stops +being managed by CloudFormation, either because you've removed it from the +CDK application or because you've made a change that requires the resource +to be replaced. + +The resource can be deleted (\`RemovalPolicy.DESTROY\`), or left in your AWS +account for data recovery and cleanup later (\`RemovalPolicy.RETAIN\`). + +###### \`policy\`Required + +- *Type:* @aws-cdk/core.RemovalPolicy + +--- + +##### \`addEventNotification\` + +\`\`\`typescript +public addEventNotification(event: EventType, dest: IBucketNotificationDestination, filters: NotificationKeyFilter): void +\`\`\` + +Adds a bucket notification event destination. + +> [https://docs.aws.amazon.com/AmazonS3/latest/dev/NotificationHowTo.html](https://docs.aws.amazon.com/AmazonS3/latest/dev/NotificationHowTo.html) + +*Example* + +\`\`\`typescript + declare const myLambda: lambda.Function; + const bucket = new s3.Bucket(this, 'MyBucket'); + bucket.addEventNotification(s3.EventType.OBJECT_CREATED, new s3n.LambdaDestination(myLambda), {prefix: 'home/myusername/*'}); +\`\`\` + + +###### \`event\`Required + +- *Type:* @aws-cdk/aws-s3.EventType + +The event to trigger the notification. + +--- + +###### \`dest\`Required + +- *Type:* @aws-cdk/aws-s3.IBucketNotificationDestination + +The notification destination (Lambda, SNS Topic or SQS Queue). + +--- + +###### \`filters\`Required + +- *Type:* @aws-cdk/aws-s3.NotificationKeyFilter + +S3 object key filter rules to determine which objects trigger this event. + +Each filter must include a \`prefix\` and/or \`suffix\` +that will be matched against the s3 object key. Refer to the S3 Developer Guide +for details about allowed filter rules. + +--- + +##### \`addObjectCreatedNotification\` + +\`\`\`typescript +public addObjectCreatedNotification(dest: IBucketNotificationDestination, filters: NotificationKeyFilter): void +\`\`\` + +Subscribes a destination to receive notifications when an object is created in the bucket. + +This is identical to calling +\`onEvent(EventType.OBJECT_CREATED)\`. + +###### \`dest\`Required + +- *Type:* @aws-cdk/aws-s3.IBucketNotificationDestination + +The notification destination (see onEvent). + +--- + +###### \`filters\`Required + +- *Type:* @aws-cdk/aws-s3.NotificationKeyFilter + +Filters (see onEvent). + +--- + +##### \`addObjectRemovedNotification\` + +\`\`\`typescript +public addObjectRemovedNotification(dest: IBucketNotificationDestination, filters: NotificationKeyFilter): void +\`\`\` + +Subscribes a destination to receive notifications when an object is removed from the bucket. + +This is identical to calling +\`onEvent(EventType.OBJECT_REMOVED)\`. + +###### \`dest\`Required + +- *Type:* @aws-cdk/aws-s3.IBucketNotificationDestination + +The notification destination (see onEvent). + +--- + +###### \`filters\`Required + +- *Type:* @aws-cdk/aws-s3.NotificationKeyFilter + +Filters (see onEvent). + +--- + +##### \`addToResourcePolicy\` + +\`\`\`typescript +public addToResourcePolicy(permission: PolicyStatement): AddToResourcePolicyResult +\`\`\` + +Adds a statement to the resource policy for a principal (i.e. account/role/service) to perform actions on this bucket and/or its contents. Use \`bucketArn\` and \`arnForObjects(keys)\` to obtain ARNs for this bucket or objects. + +Note that the policy statement may or may not be added to the policy. +For example, when an \`IBucket\` is created from an existing bucket, +it's not possible to tell whether the bucket already has a policy +attached, let alone to re-use that policy to add more statements to it. +So it's safest to do nothing in these cases. + +###### \`permission\`Required + +- *Type:* @aws-cdk/aws-iam.PolicyStatement + +the policy statement to be added to the bucket's policy. + +--- + +##### \`arnForObjects\` + +\`\`\`typescript +public arnForObjects(keyPattern: string): string +\`\`\` + +Returns an ARN that represents all objects within the bucket that match the key pattern specified. + +To represent all keys, specify \`\`"*"\`\`. + +If you need to specify a keyPattern with multiple components, concatenate them into a single string, e.g.: + + arnForObjects(\`home/\${team}/\${user}/*\`) + +###### \`keyPattern\`Required + +- *Type:* string + +--- + +##### \`grantDelete\` + +\`\`\`typescript +public grantDelete(identity: IGrantable, objectsKeyPattern?: any): Grant +\`\`\` + +Grants s3:DeleteObject* permission to an IAM principal for objects in this bucket. + +###### \`identity\`Required + +- *Type:* @aws-cdk/aws-iam.IGrantable + +The principal. + +--- + +###### \`objectsKeyPattern\`Optional + +- *Type:* any + +Restrict the permission to a certain key pattern (default '*'). + +--- + +##### \`grantPublicAccess\` + +\`\`\`typescript +public grantPublicAccess(allowedActions: string, keyPrefix?: string): Grant +\`\`\` + +Allows unrestricted access to objects from this bucket. + +IMPORTANT: This permission allows anyone to perform actions on S3 objects +in this bucket, which is useful for when you configure your bucket as a +website and want everyone to be able to read objects in the bucket without +needing to authenticate. + +Without arguments, this method will grant read ("s3:GetObject") access to +all objects ("*") in the bucket. + +The method returns the \`iam.Grant\` object, which can then be modified +as needed. For example, you can add a condition that will restrict access only +to an IPv4 range like this: + + const grant = bucket.grantPublicAccess(); + grant.resourceStatement!.addCondition(‘IpAddress’, { “aws:SourceIp”: “54.240.143.0/24” }); + +Note that if this \`IBucket\` refers to an existing bucket, possibly not +managed by CloudFormation, this method will have no effect, since it's +impossible to modify the policy of an existing bucket. + +###### \`allowedActions\`Required + +- *Type:* string + +the set of S3 actions to allow. + +Default is "s3:GetObject". + +--- + +###### \`keyPrefix\`Optional + +- *Type:* string + +the prefix of S3 object keys (e.g. \`home/*\`). Default is "*". + +--- + +##### \`grantPut\` + +\`\`\`typescript +public grantPut(identity: IGrantable, objectsKeyPattern?: any): Grant +\`\`\` + +Grants s3:PutObject* and s3:Abort* permissions for this bucket to an IAM principal. + +If encryption is used, permission to use the key to encrypt the contents +of written files will also be granted to the same principal. + +###### \`identity\`Required + +- *Type:* @aws-cdk/aws-iam.IGrantable + +The principal. + +--- + +###### \`objectsKeyPattern\`Optional + +- *Type:* any + +Restrict the permission to a certain key pattern (default '*'). + +--- + +##### \`grantPutAcl\` + +\`\`\`typescript +public grantPutAcl(identity: IGrantable, objectsKeyPattern?: string): Grant +\`\`\` + +Grant the given IAM identity permissions to modify the ACLs of objects in the given Bucket. + +If your application has the '@aws-cdk/aws-s3:grantWriteWithoutAcl' feature flag set, +calling {@link grantWrite} or {@link grantReadWrite} no longer grants permissions to modify the ACLs of the objects; +in this case, if you need to modify object ACLs, call this method explicitly. + +###### \`identity\`Required + +- *Type:* @aws-cdk/aws-iam.IGrantable + +--- + +###### \`objectsKeyPattern\`Optional + +- *Type:* string + +--- + +##### \`grantRead\` + +\`\`\`typescript +public grantRead(identity: IGrantable, objectsKeyPattern?: any): Grant +\`\`\` + +Grant read permissions for this bucket and it's contents to an IAM principal (Role/Group/User). + +If encryption is used, permission to use the key to decrypt the contents +of the bucket will also be granted to the same principal. + +###### \`identity\`Required + +- *Type:* @aws-cdk/aws-iam.IGrantable + +The principal. + +--- + +###### \`objectsKeyPattern\`Optional + +- *Type:* any + +Restrict the permission to a certain key pattern (default '*'). + +--- + +##### \`grantReadWrite\` + +\`\`\`typescript +public grantReadWrite(identity: IGrantable, objectsKeyPattern?: any): Grant +\`\`\` + +Grants read/write permissions for this bucket and it's contents to an IAM principal (Role/Group/User). + +If an encryption key is used, permission to use the key for +encrypt/decrypt will also be granted. + +Before CDK version 1.85.0, this method granted the \`s3:PutObject*\` permission that included \`s3:PutObjectAcl\`, +which could be used to grant read/write object access to IAM principals in other accounts. +If you want to get rid of that behavior, update your CDK version to 1.85.0 or later, +and make sure the \`@aws-cdk/aws-s3:grantWriteWithoutAcl\` feature flag is set to \`true\` +in the \`context\` key of your cdk.json file. +If you've already updated, but still need the principal to have permissions to modify the ACLs, +use the {@link grantPutAcl} method. + +###### \`identity\`Required + +- *Type:* @aws-cdk/aws-iam.IGrantable + +--- + +###### \`objectsKeyPattern\`Optional + +- *Type:* any + +--- + +##### \`grantWrite\` + +\`\`\`typescript +public grantWrite(identity: IGrantable, objectsKeyPattern?: any): Grant +\`\`\` + +Grant write permissions to this bucket to an IAM principal. + +If encryption is used, permission to use the key to encrypt the contents +of written files will also be granted to the same principal. + +Before CDK version 1.85.0, this method granted the \`s3:PutObject*\` permission that included \`s3:PutObjectAcl\`, +which could be used to grant read/write object access to IAM principals in other accounts. +If you want to get rid of that behavior, update your CDK version to 1.85.0 or later, +and make sure the \`@aws-cdk/aws-s3:grantWriteWithoutAcl\` feature flag is set to \`true\` +in the \`context\` key of your cdk.json file. +If you've already updated, but still need the principal to have permissions to modify the ACLs, +use the {@link grantPutAcl} method. + +###### \`identity\`Required + +- *Type:* @aws-cdk/aws-iam.IGrantable + +--- + +###### \`objectsKeyPattern\`Optional + +- *Type:* any + +--- + +##### \`onCloudTrailEvent\` + +\`\`\`typescript +public onCloudTrailEvent(id: string, options?: OnCloudTrailBucketEventOptions): Rule +\`\`\` + +Define a CloudWatch event that triggers when something happens to this repository. + +Requires that there exists at least one CloudTrail Trail in your account +that captures the event. This method will not create the Trail. + +###### \`id\`Required + +- *Type:* string + +The id of the rule. + +--- + +###### \`options\`Optional + +- *Type:* @aws-cdk/aws-s3.OnCloudTrailBucketEventOptions + +Options for adding the rule. + +--- + +##### \`onCloudTrailPutObject\` + +\`\`\`typescript +public onCloudTrailPutObject(id: string, options?: OnCloudTrailBucketEventOptions): Rule +\`\`\` + +Defines an AWS CloudWatch event that triggers when an object is uploaded to the specified paths (keys) in this bucket using the PutObject API call. + +Note that some tools like \`aws s3 cp\` will automatically use either +PutObject or the multipart upload API depending on the file size, +so using \`onCloudTrailWriteObject\` may be preferable. + +Requires that there exists at least one CloudTrail Trail in your account +that captures the event. This method will not create the Trail. + +###### \`id\`Required + +- *Type:* string + +The id of the rule. + +--- + +###### \`options\`Optional + +- *Type:* @aws-cdk/aws-s3.OnCloudTrailBucketEventOptions + +Options for adding the rule. + +--- + +##### \`onCloudTrailWriteObject\` + +\`\`\`typescript +public onCloudTrailWriteObject(id: string, options?: OnCloudTrailBucketEventOptions): Rule +\`\`\` + +Defines an AWS CloudWatch event that triggers when an object at the specified paths (keys) in this bucket are written to. + +This includes +the events PutObject, CopyObject, and CompleteMultipartUpload. + +Note that some tools like \`aws s3 cp\` will automatically use either +PutObject or the multipart upload API depending on the file size, +so using this method may be preferable to \`onCloudTrailPutObject\`. + +Requires that there exists at least one CloudTrail Trail in your account +that captures the event. This method will not create the Trail. + +###### \`id\`Required + +- *Type:* string + +The id of the rule. + +--- + +###### \`options\`Optional + +- *Type:* @aws-cdk/aws-s3.OnCloudTrailBucketEventOptions + +Options for adding the rule. + +--- + +##### \`s3UrlForObject\` + +\`\`\`typescript +public s3UrlForObject(key?: string): string +\`\`\` + +The S3 URL of an S3 object. For example:. + +\`s3://onlybucket\` +- \`s3://bucket/key\` + +###### \`key\`Optional + +- *Type:* string + +The S3 key of the object. + +If not specified, the S3 URL of the +bucket is returned. + +--- + +##### \`transferAccelerationUrlForObject\` + +\`\`\`typescript +public transferAccelerationUrlForObject(key?: string, options?: TransferAccelerationUrlOptions): string +\`\`\` + +The https Transfer Acceleration URL of an S3 object. + +Specify \`dualStack: true\` at the options +for dual-stack endpoint (connect to the bucket over IPv6). For example: + +- \`https://bucket.s3-accelerate.amazonaws.com\` +- \`https://bucket.s3-accelerate.amazonaws.com/key\` + +###### \`key\`Optional + +- *Type:* string + +The S3 key of the object. + +If not specified, the URL of the +bucket is returned. + +--- + +###### \`options\`Optional + +- *Type:* @aws-cdk/aws-s3.TransferAccelerationUrlOptions + +Options for generating URL. + +--- + +##### \`urlForObject\` + +\`\`\`typescript +public urlForObject(key?: string): string +\`\`\` + +The https URL of an S3 object. Specify \`regional: false\` at the options for non-regional URLs. For example:. + +\`https://s3.us-west-1.amazonaws.com/onlybucket\` +- \`https://s3.us-west-1.amazonaws.com/bucket/key\` +- \`https://s3.cn-north-1.amazonaws.com.cn/china-bucket/mykey\` + +###### \`key\`Optional + +- *Type:* string + +The S3 key of the object. + +If not specified, the URL of the +bucket is returned. + +--- + +##### \`virtualHostedUrlForObject\` + +\`\`\`typescript +public virtualHostedUrlForObject(key?: string, options?: VirtualHostedStyleUrlOptions): string +\`\`\` + +The virtual hosted-style URL of an S3 object. Specify \`regional: false\` at the options for non-regional URL. For example:. + +\`https://only-bucket.s3.us-west-1.amazonaws.com\` +- \`https://bucket.s3.us-west-1.amazonaws.com/key\` +- \`https://bucket.s3.amazonaws.com/key\` +- \`https://china-bucket.s3.cn-north-1.amazonaws.com.cn/mykey\` + +###### \`key\`Optional + +- *Type:* string + +The S3 key of the object. + +If not specified, the URL of the +bucket is returned. + +--- + +###### \`options\`Optional + +- *Type:* @aws-cdk/aws-s3.VirtualHostedStyleUrlOptions + +Options for generating URL. + +--- + +##### \`addCorsRule\` + +\`\`\`typescript +public addCorsRule(rule: CorsRule): void +\`\`\` + +Adds a cross-origin access configuration for objects in an Amazon S3 bucket. + +###### \`rule\`Required + +- *Type:* @aws-cdk/aws-s3.CorsRule + +The CORS configuration rule to add. + +--- + +##### \`addInventory\` + +\`\`\`typescript +public addInventory(inventory: Inventory): void +\`\`\` + +Add an inventory configuration. + +###### \`inventory\`Required + +- *Type:* @aws-cdk/aws-s3.Inventory + +configuration to add. + +--- + +##### \`addLifecycleRule\` + +\`\`\`typescript +public addLifecycleRule(rule: LifecycleRule): void +\`\`\` + +Add a lifecycle rule to the bucket. + +###### \`rule\`Required + +- *Type:* @aws-cdk/aws-s3.LifecycleRule + +The rule to add. + +--- + +##### \`addMetric\` + +\`\`\`typescript +public addMetric(metric: BucketMetrics): void +\`\`\` + +Adds a metrics configuration for the CloudWatch request metrics from the bucket. + +###### \`metric\`Required + +- *Type:* @aws-cdk/aws-s3.BucketMetrics + +The metric configuration to add. + +--- + +##### \`greet\` + +\`\`\`typescript +public greet(): void +\`\`\` + +##### \`greetWithSalutation\` + +\`\`\`typescript +public greetWithSalutation(salution: string): void +\`\`\` + +###### \`salution\`Required + +- *Type:* string + +--- + +#### Static Functions + +| **Name** | **Description** | +| --- | --- | +| isConstruct | Return whether the given object is a Construct. | +| isResource | Check whether the given construct is a Resource. | +| fromBucketArn | *No description.* | +| fromBucketAttributes | Creates a Bucket construct that represents an external bucket. | +| fromBucketName | *No description.* | +| validateBucketName | Thrown an exception if the given bucket name is not valid. | + +--- + +##### \`isConstruct\` + +\`\`\`typescript +import { GreeterBucket } from 'construct-library' + +GreeterBucket.isConstruct(x: any) +\`\`\` + +Return whether the given object is a Construct. + +###### \`x\`Required + +- *Type:* any + +--- + +##### \`isResource\` + +\`\`\`typescript +import { GreeterBucket } from 'construct-library' + +GreeterBucket.isResource(construct: IConstruct) +\`\`\` + +Check whether the given construct is a Resource. + +###### \`construct\`Required + +- *Type:* @aws-cdk/core.IConstruct + +--- + +##### \`fromBucketArn\` + +\`\`\`typescript +import { GreeterBucket } from 'construct-library' + +GreeterBucket.fromBucketArn(scope: Construct, id: string, bucketArn: string) +\`\`\` + +###### \`scope\`Required + +- *Type:* constructs.Construct + +--- + +###### \`id\`Required + +- *Type:* string + +--- + +###### \`bucketArn\`Required + +- *Type:* string + +--- + +##### \`fromBucketAttributes\` + +\`\`\`typescript +import { GreeterBucket } from 'construct-library' + +GreeterBucket.fromBucketAttributes(scope: Construct, id: string, attrs: BucketAttributes) +\`\`\` + +Creates a Bucket construct that represents an external bucket. + +###### \`scope\`Required + +- *Type:* constructs.Construct + +The parent creating construct (usually \`this\`). + +--- + +###### \`id\`Required + +- *Type:* string + +The construct's name. + +--- + +###### \`attrs\`Required + +- *Type:* @aws-cdk/aws-s3.BucketAttributes + +A \`BucketAttributes\` object. + +Can be obtained from a call to +\`bucket.export()\` or manually created. + +--- + +##### \`fromBucketName\` + +\`\`\`typescript +import { GreeterBucket } from 'construct-library' + +GreeterBucket.fromBucketName(scope: Construct, id: string, bucketName: string) +\`\`\` + +###### \`scope\`Required + +- *Type:* constructs.Construct + +--- + +###### \`id\`Required + +- *Type:* string + +--- + +###### \`bucketName\`Required + +- *Type:* string + +--- + +##### \`validateBucketName\` + +\`\`\`typescript +import { GreeterBucket } from 'construct-library' + +GreeterBucket.validateBucketName(physicalName: string) +\`\`\` + +Thrown an exception if the given bucket name is not valid. + +###### \`physicalName\`Required + +- *Type:* string + +name of the bucket. + +--- + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| node | @aws-cdk/core.ConstructNode | The construct tree node associated with this construct. | +| env | @aws-cdk/core.ResourceEnvironment | The environment this resource belongs to. | +| stack | @aws-cdk/core.Stack | The stack in which this resource is defined. | +| bucketArn | string | The ARN of the bucket. | +| bucketDomainName | string | The IPv4 DNS name of the specified bucket. | +| bucketDualStackDomainName | string | The IPv6 DNS name of the specified bucket. | +| bucketName | string | The name of the bucket. | +| bucketRegionalDomainName | string | The regional domain name of the specified bucket. | +| bucketWebsiteDomainName | string | The Domain name of the static website. | +| bucketWebsiteUrl | string | The URL of the static website. | +| encryptionKey | @aws-cdk/aws-kms.IKey | Optional KMS encryption key associated with this bucket. | +| isWebsite | boolean | If this bucket has been configured for static website hosting. | +| policy | @aws-cdk/aws-s3.BucketPolicy | The resource policy associated with this bucket. | + +--- + +##### \`node\`Required + +\`\`\`typescript +public readonly node: ConstructNode; +\`\`\` + +- *Type:* @aws-cdk/core.ConstructNode + +The construct tree node associated with this construct. + +--- + +##### \`env\`Required + +\`\`\`typescript +public readonly env: ResourceEnvironment; +\`\`\` + +- *Type:* @aws-cdk/core.ResourceEnvironment + +The environment this resource belongs to. + +For resources that are created and managed by the CDK +(generally, those created by creating new class instances like Role, Bucket, etc.), +this is always the same as the environment of the stack they belong to; +however, for imported resources +(those obtained from static methods like fromRoleArn, fromBucketName, etc.), +that might be different than the stack they were imported into. + +--- + +##### \`stack\`Required + +\`\`\`typescript +public readonly stack: Stack; +\`\`\` + +- *Type:* @aws-cdk/core.Stack + +The stack in which this resource is defined. + +--- + +##### \`bucketArn\`Required + +\`\`\`typescript +public readonly bucketArn: string; +\`\`\` + +- *Type:* string + +The ARN of the bucket. + +--- + +##### \`bucketDomainName\`Required + +\`\`\`typescript +public readonly bucketDomainName: string; +\`\`\` + +- *Type:* string + +The IPv4 DNS name of the specified bucket. + +--- + +##### \`bucketDualStackDomainName\`Required + +\`\`\`typescript +public readonly bucketDualStackDomainName: string; +\`\`\` + +- *Type:* string + +The IPv6 DNS name of the specified bucket. + +--- + +##### \`bucketName\`Required + +\`\`\`typescript +public readonly bucketName: string; +\`\`\` + +- *Type:* string + +The name of the bucket. + +--- + +##### \`bucketRegionalDomainName\`Required + +\`\`\`typescript +public readonly bucketRegionalDomainName: string; +\`\`\` + +- *Type:* string + +The regional domain name of the specified bucket. + +--- + +##### \`bucketWebsiteDomainName\`Required + +\`\`\`typescript +public readonly bucketWebsiteDomainName: string; +\`\`\` + +- *Type:* string + +The Domain name of the static website. + +--- + +##### \`bucketWebsiteUrl\`Required + +\`\`\`typescript +public readonly bucketWebsiteUrl: string; +\`\`\` + +- *Type:* string + +The URL of the static website. + +--- + +##### \`encryptionKey\`Optional + +\`\`\`typescript +public readonly encryptionKey: IKey; +\`\`\` + +- *Type:* @aws-cdk/aws-kms.IKey + +Optional KMS encryption key associated with this bucket. + +--- + +##### \`isWebsite\`Optional + +\`\`\`typescript +public readonly isWebsite: boolean; +\`\`\` + +- *Type:* boolean + +If this bucket has been configured for static website hosting. + +--- + +##### \`policy\`Optional + +\`\`\`typescript +public readonly policy: BucketPolicy; +\`\`\` + +- *Type:* @aws-cdk/aws-s3.BucketPolicy + +The resource policy associated with this bucket. + +If \`autoCreatePolicy\` is true, a \`BucketPolicy\` will be created upon the +first call to addToResourcePolicy(s). + +--- + + + + + +" +`; + +exports[`specify languages and split-by-submodule creates submodule files next to output: submod1.python.md 1`] = ` +"# \`submod1\` Submodule + +## Constructs + +### GoodbyeBucket + +#### Initializers + +\`\`\`python +from construct_library import submod1 + +submod1.GoodbyeBucket( + scope: Construct, + id: str, + access_control: BucketAccessControl = None, + auto_delete_objects: bool = None, + block_public_access: BlockPublicAccess = None, + bucket_key_enabled: bool = None, + bucket_name: str = None, + cors: typing.List[CorsRule] = None, + encryption: BucketEncryption = None, + encryption_key: IKey = None, + enforce_ss_l: bool = None, + event_bridge_enabled: bool = None, + intelligent_tiering_configurations: typing.List[IntelligentTieringConfiguration] = None, + inventories: typing.List[Inventory] = None, + lifecycle_rules: typing.List[LifecycleRule] = None, + metrics: typing.List[BucketMetrics] = None, + notifications_handler_role: IRole = None, + object_ownership: ObjectOwnership = None, + public_read_access: bool = None, + removal_policy: RemovalPolicy = None, + server_access_logs_bucket: IBucket = None, + server_access_logs_prefix: str = None, + transfer_acceleration: bool = None, + versioned: bool = None, + website_error_document: str = None, + website_index_document: str = None, + website_redirect: RedirectTarget = None, + website_routing_rules: typing.List[RoutingRule] = None +) +\`\`\` + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| scope | constructs.Construct | *No description.* | +| id | str | *No description.* | +| access_control | aws_cdk.aws_s3.BucketAccessControl | Specifies a canned ACL that grants predefined permissions to the bucket. | +| auto_delete_objects | bool | Whether all objects should be automatically deleted when the bucket is removed from the stack or when the stack is deleted. | +| block_public_access | aws_cdk.aws_s3.BlockPublicAccess | The block public access configuration of this bucket. | +| bucket_key_enabled | bool | Specifies whether Amazon S3 should use an S3 Bucket Key with server-side encryption using KMS (SSE-KMS) for new objects in the bucket. | +| bucket_name | str | Physical name of this bucket. | +| cors | typing.List[aws_cdk.aws_s3.CorsRule] | The CORS configuration of this bucket. | +| encryption | aws_cdk.aws_s3.BucketEncryption | The kind of server-side encryption to apply to this bucket. | +| encryption_key | aws_cdk.aws_kms.IKey | External KMS key to use for bucket encryption. | +| enforce_ss_l | bool | Enforces SSL for requests. | +| event_bridge_enabled | bool | Whether this bucket should send notifications to Amazon EventBridge or not. | +| intelligent_tiering_configurations | typing.List[aws_cdk.aws_s3.IntelligentTieringConfiguration] | Inteligent Tiering Configurations. | +| inventories | typing.List[aws_cdk.aws_s3.Inventory] | The inventory configuration of the bucket. | +| lifecycle_rules | typing.List[aws_cdk.aws_s3.LifecycleRule] | Rules that define how Amazon S3 manages objects during their lifetime. | +| metrics | typing.List[aws_cdk.aws_s3.BucketMetrics] | The metrics configuration of this bucket. | +| notifications_handler_role | aws_cdk.aws_iam.IRole | The role to be used by the notifications handler. | +| object_ownership | aws_cdk.aws_s3.ObjectOwnership | The objectOwnership of the bucket. | +| public_read_access | bool | Grants public read access to all objects in the bucket. | +| removal_policy | aws_cdk.core.RemovalPolicy | Policy to apply when the bucket is removed from this stack. | +| server_access_logs_bucket | aws_cdk.aws_s3.IBucket | Destination bucket for the server access logs. | +| server_access_logs_prefix | str | Optional log file prefix to use for the bucket's access logs. | +| transfer_acceleration | bool | Whether this bucket should have transfer acceleration turned on or not. | +| versioned | bool | Whether this bucket should have versioning turned on or not. | +| website_error_document | str | The name of the error document (e.g. "404.html") for the website. \`websiteIndexDocument\` must also be set if this is set. | +| website_index_document | str | The name of the index document (e.g. "index.html") for the website. Enables static website hosting for this bucket. | +| website_redirect | aws_cdk.aws_s3.RedirectTarget | Specifies the redirect behavior of all requests to a website endpoint of a bucket. | +| website_routing_rules | typing.List[aws_cdk.aws_s3.RoutingRule] | Rules that define when a redirect is applied and the redirect behavior. | + +--- + +##### \`scope\`Required + +- *Type:* constructs.Construct + +--- + +##### \`id\`Required + +- *Type:* str + +--- + +##### \`access_control\`Optional + +- *Type:* aws_cdk.aws_s3.BucketAccessControl +- *Default:* BucketAccessControl.PRIVATE + +Specifies a canned ACL that grants predefined permissions to the bucket. + +--- + +##### \`auto_delete_objects\`Optional + +- *Type:* bool +- *Default:* false + +Whether all objects should be automatically deleted when the bucket is removed from the stack or when the stack is deleted. + +Requires the \`removalPolicy\` to be set to \`RemovalPolicy.DESTROY\`. + +**Warning** if you have deployed a bucket with \`autoDeleteObjects: true\`, +switching this to \`false\` in a CDK version *before* \`1.126.0\` will lead to +all objects in the bucket being deleted. Be sure to update your bucket resources +by deploying with CDK version \`1.126.0\` or later **before** switching this value to \`false\`. + +--- + +##### \`block_public_access\`Optional + +- *Type:* aws_cdk.aws_s3.BlockPublicAccess +- *Default:* CloudFormation defaults will apply. New buckets and objects don't allow public access, but users can modify bucket policies or object permissions to allow public access + +The block public access configuration of this bucket. + +> [https://docs.aws.amazon.com/AmazonS3/latest/dev/access-control-block-public-access.html](https://docs.aws.amazon.com/AmazonS3/latest/dev/access-control-block-public-access.html) + +--- + +##### \`bucket_key_enabled\`Optional + +- *Type:* bool +- *Default:* false + +Specifies whether Amazon S3 should use an S3 Bucket Key with server-side encryption using KMS (SSE-KMS) for new objects in the bucket. + +Only relevant, when Encryption is set to {@link BucketEncryption.KMS} + +--- + +##### \`bucket_name\`Optional + +- *Type:* str +- *Default:* Assigned by CloudFormation (recommended). + +Physical name of this bucket. + +--- + +##### \`cors\`Optional + +- *Type:* typing.List[aws_cdk.aws_s3.CorsRule] +- *Default:* No CORS configuration. + +The CORS configuration of this bucket. + +> [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-s3-bucket-cors.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-s3-bucket-cors.html) + +--- + +##### \`encryption\`Optional + +- *Type:* aws_cdk.aws_s3.BucketEncryption +- *Default:* \`Kms\` if \`encryptionKey\` is specified, or \`Unencrypted\` otherwise. + +The kind of server-side encryption to apply to this bucket. + +If you choose KMS, you can specify a KMS key via \`encryptionKey\`. If +encryption key is not specified, a key will automatically be created. + +--- + +##### \`encryption_key\`Optional + +- *Type:* aws_cdk.aws_kms.IKey +- *Default:* If encryption is set to "Kms" and this property is undefined, a new KMS key will be created and associated with this bucket. + +External KMS key to use for bucket encryption. + +The 'encryption' property must be either not specified or set to "Kms". +An error will be emitted if encryption is set to "Unencrypted" or +"Managed". + +--- + +##### \`enforce_ss_l\`Optional + +- *Type:* bool +- *Default:* false + +Enforces SSL for requests. + +S3.5 of the AWS Foundational Security Best Practices Regarding S3. + +> [https://docs.aws.amazon.com/config/latest/developerguide/s3-bucket-ssl-requests-only.html](https://docs.aws.amazon.com/config/latest/developerguide/s3-bucket-ssl-requests-only.html) + +--- + +##### \`event_bridge_enabled\`Optional + +- *Type:* bool +- *Default:* false + +Whether this bucket should send notifications to Amazon EventBridge or not. + +--- + +##### \`intelligent_tiering_configurations\`Optional + +- *Type:* typing.List[aws_cdk.aws_s3.IntelligentTieringConfiguration] +- *Default:* No Intelligent Tiiering Configurations. + +Inteligent Tiering Configurations. + +> [https://docs.aws.amazon.com/AmazonS3/latest/userguide/intelligent-tiering.html](https://docs.aws.amazon.com/AmazonS3/latest/userguide/intelligent-tiering.html) + +--- + +##### \`inventories\`Optional + +- *Type:* typing.List[aws_cdk.aws_s3.Inventory] +- *Default:* No inventory configuration + +The inventory configuration of the bucket. + +> [https://docs.aws.amazon.com/AmazonS3/latest/dev/storage-inventory.html](https://docs.aws.amazon.com/AmazonS3/latest/dev/storage-inventory.html) + +--- + +##### \`lifecycle_rules\`Optional + +- *Type:* typing.List[aws_cdk.aws_s3.LifecycleRule] +- *Default:* No lifecycle rules. + +Rules that define how Amazon S3 manages objects during their lifetime. + +--- + +##### \`metrics\`Optional + +- *Type:* typing.List[aws_cdk.aws_s3.BucketMetrics] +- *Default:* No metrics configuration. + +The metrics configuration of this bucket. + +> [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-s3-bucket-metricsconfiguration.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-s3-bucket-metricsconfiguration.html) + +--- + +##### \`notifications_handler_role\`Optional + +- *Type:* aws_cdk.aws_iam.IRole +- *Default:* a new role will be created. + +The role to be used by the notifications handler. + +--- + +##### \`object_ownership\`Optional + +- *Type:* aws_cdk.aws_s3.ObjectOwnership +- *Default:* No ObjectOwnership configuration, uploading account will own the object. + +The objectOwnership of the bucket. + +> [https://docs.aws.amazon.com/AmazonS3/latest/dev/about-object-ownership.html](https://docs.aws.amazon.com/AmazonS3/latest/dev/about-object-ownership.html) + +--- + +##### \`public_read_access\`Optional + +- *Type:* bool +- *Default:* false + +Grants public read access to all objects in the bucket. + +Similar to calling \`bucket.grantPublicAccess()\` + +--- + +##### \`removal_policy\`Optional + +- *Type:* aws_cdk.core.RemovalPolicy +- *Default:* The bucket will be orphaned. + +Policy to apply when the bucket is removed from this stack. + +--- + +##### \`server_access_logs_bucket\`Optional + +- *Type:* aws_cdk.aws_s3.IBucket +- *Default:* If "serverAccessLogsPrefix" undefined - access logs disabled, otherwise - log to current bucket. + +Destination bucket for the server access logs. + +--- + +##### \`server_access_logs_prefix\`Optional + +- *Type:* str +- *Default:* No log file prefix + +Optional log file prefix to use for the bucket's access logs. + +If defined without "serverAccessLogsBucket", enables access logs to current bucket with this prefix. + +--- + +##### \`transfer_acceleration\`Optional + +- *Type:* bool +- *Default:* false + +Whether this bucket should have transfer acceleration turned on or not. + +--- + +##### \`versioned\`Optional + +- *Type:* bool +- *Default:* false + +Whether this bucket should have versioning turned on or not. + +--- + +##### \`website_error_document\`Optional + +- *Type:* str +- *Default:* No error document. + +The name of the error document (e.g. "404.html") for the website. \`websiteIndexDocument\` must also be set if this is set. + +--- + +##### \`website_index_document\`Optional + +- *Type:* str +- *Default:* No index document. + +The name of the index document (e.g. "index.html") for the website. Enables static website hosting for this bucket. + +--- + +##### \`website_redirect\`Optional + +- *Type:* aws_cdk.aws_s3.RedirectTarget +- *Default:* No redirection. + +Specifies the redirect behavior of all requests to a website endpoint of a bucket. + +If you specify this property, you can't specify "websiteIndexDocument", "websiteErrorDocument" nor , "websiteRoutingRules". + +--- + +##### \`website_routing_rules\`Optional + +- *Type:* typing.List[aws_cdk.aws_s3.RoutingRule] +- *Default:* No redirection rules. + +Rules that define when a redirect is applied and the redirect behavior. + +--- + +#### Methods + +| **Name** | **Description** | +| --- | --- | +| to_string | Returns a string representation of this construct. | +| apply_removal_policy | Apply the given removal policy to this resource. | +| add_event_notification | Adds a bucket notification event destination. | +| add_object_created_notification | Subscribes a destination to receive notifications when an object is created in the bucket. | +| add_object_removed_notification | Subscribes a destination to receive notifications when an object is removed from the bucket. | +| add_to_resource_policy | Adds a statement to the resource policy for a principal (i.e. account/role/service) to perform actions on this bucket and/or its contents. Use \`bucketArn\` and \`arnForObjects(keys)\` to obtain ARNs for this bucket or objects. | +| arn_for_objects | Returns an ARN that represents all objects within the bucket that match the key pattern specified. | +| grant_delete | Grants s3:DeleteObject* permission to an IAM principal for objects in this bucket. | +| grant_public_access | Allows unrestricted access to objects from this bucket. | +| grant_put | Grants s3:PutObject* and s3:Abort* permissions for this bucket to an IAM principal. | +| grant_put_acl | Grant the given IAM identity permissions to modify the ACLs of objects in the given Bucket. | +| grant_read | Grant read permissions for this bucket and it's contents to an IAM principal (Role/Group/User). | +| grant_read_write | Grants read/write permissions for this bucket and it's contents to an IAM principal (Role/Group/User). | +| grant_write | Grant write permissions to this bucket to an IAM principal. | +| on_cloud_trail_event | Define a CloudWatch event that triggers when something happens to this repository. | +| on_cloud_trail_put_object | Defines an AWS CloudWatch event that triggers when an object is uploaded to the specified paths (keys) in this bucket using the PutObject API call. | +| on_cloud_trail_write_object | Defines an AWS CloudWatch event that triggers when an object at the specified paths (keys) in this bucket are written to. | +| s3_url_for_object | The S3 URL of an S3 object. For example:. | +| transfer_acceleration_url_for_object | The https Transfer Acceleration URL of an S3 object. | +| url_for_object | The https URL of an S3 object. Specify \`regional: false\` at the options for non-regional URLs. For example:. | +| virtual_hosted_url_for_object | The virtual hosted-style URL of an S3 object. Specify \`regional: false\` at the options for non-regional URL. For example:. | +| add_cors_rule | Adds a cross-origin access configuration for objects in an Amazon S3 bucket. | +| add_inventory | Add an inventory configuration. | +| add_lifecycle_rule | Add a lifecycle rule to the bucket. | +| add_metric | Adds a metrics configuration for the CloudWatch request metrics from the bucket. | +| goodbye | *No description.* | +| goodbye_with_phrase | *No description.* | + +--- + +##### \`to_string\` + +\`\`\`python +def to_string() -> str +\`\`\` + +Returns a string representation of this construct. + +##### \`apply_removal_policy\` + +\`\`\`python +def apply_removal_policy( + policy: RemovalPolicy +) -> None +\`\`\` + +Apply the given removal policy to this resource. + +The Removal Policy controls what happens to this resource when it stops +being managed by CloudFormation, either because you've removed it from the +CDK application or because you've made a change that requires the resource +to be replaced. + +The resource can be deleted (\`RemovalPolicy.DESTROY\`), or left in your AWS +account for data recovery and cleanup later (\`RemovalPolicy.RETAIN\`). + +###### \`policy\`Required + +- *Type:* aws_cdk.core.RemovalPolicy + +--- + +##### \`add_event_notification\` + +\`\`\`python +def add_event_notification( + event: EventType, + dest: IBucketNotificationDestination, + prefix: str = None, + suffix: str = None +) -> None +\`\`\` + +Adds a bucket notification event destination. + +> [https://docs.aws.amazon.com/AmazonS3/latest/dev/NotificationHowTo.html](https://docs.aws.amazon.com/AmazonS3/latest/dev/NotificationHowTo.html) + +*Example* + +\`\`\`python + declare const myLambda: lambda.Function; + const bucket = new s3.Bucket(this, 'MyBucket'); + bucket.addEventNotification(s3.EventType.OBJECT_CREATED, new s3n.LambdaDestination(myLambda), {prefix: 'home/myusername/*'}); +\`\`\` + + +###### \`event\`Required + +- *Type:* aws_cdk.aws_s3.EventType + +The event to trigger the notification. + +--- + +###### \`dest\`Required + +- *Type:* aws_cdk.aws_s3.IBucketNotificationDestination + +The notification destination (Lambda, SNS Topic or SQS Queue). + +--- + +###### \`prefix\`Optional + +- *Type:* str + +S3 keys must have the specified prefix. + +--- + +###### \`suffix\`Optional + +- *Type:* str + +S3 keys must have the specified suffix. + +--- + +##### \`add_object_created_notification\` + +\`\`\`python +def add_object_created_notification( + dest: IBucketNotificationDestination, + prefix: str = None, + suffix: str = None +) -> None +\`\`\` + +Subscribes a destination to receive notifications when an object is created in the bucket. + +This is identical to calling +\`onEvent(EventType.OBJECT_CREATED)\`. + +###### \`dest\`Required + +- *Type:* aws_cdk.aws_s3.IBucketNotificationDestination + +The notification destination (see onEvent). + +--- + +###### \`prefix\`Optional + +- *Type:* str + +S3 keys must have the specified prefix. + +--- + +###### \`suffix\`Optional + +- *Type:* str + +S3 keys must have the specified suffix. + +--- + +##### \`add_object_removed_notification\` + +\`\`\`python +def add_object_removed_notification( + dest: IBucketNotificationDestination, + prefix: str = None, + suffix: str = None +) -> None +\`\`\` + +Subscribes a destination to receive notifications when an object is removed from the bucket. + +This is identical to calling +\`onEvent(EventType.OBJECT_REMOVED)\`. + +###### \`dest\`Required + +- *Type:* aws_cdk.aws_s3.IBucketNotificationDestination + +The notification destination (see onEvent). + +--- + +###### \`prefix\`Optional + +- *Type:* str + +S3 keys must have the specified prefix. + +--- + +###### \`suffix\`Optional + +- *Type:* str + +S3 keys must have the specified suffix. + +--- + +##### \`add_to_resource_policy\` + +\`\`\`python +def add_to_resource_policy( + permission: PolicyStatement +) -> AddToResourcePolicyResult +\`\`\` + +Adds a statement to the resource policy for a principal (i.e. account/role/service) to perform actions on this bucket and/or its contents. Use \`bucketArn\` and \`arnForObjects(keys)\` to obtain ARNs for this bucket or objects. + +Note that the policy statement may or may not be added to the policy. +For example, when an \`IBucket\` is created from an existing bucket, +it's not possible to tell whether the bucket already has a policy +attached, let alone to re-use that policy to add more statements to it. +So it's safest to do nothing in these cases. + +###### \`permission\`Required + +- *Type:* aws_cdk.aws_iam.PolicyStatement + +the policy statement to be added to the bucket's policy. + +--- + +##### \`arn_for_objects\` + +\`\`\`python +def arn_for_objects( + key_pattern: str +) -> str +\`\`\` + +Returns an ARN that represents all objects within the bucket that match the key pattern specified. + +To represent all keys, specify \`\`"*"\`\`. + +If you need to specify a keyPattern with multiple components, concatenate them into a single string, e.g.: + + arnForObjects(\`home/\${team}/\${user}/*\`) + +###### \`key_pattern\`Required + +- *Type:* str + +--- + +##### \`grant_delete\` + +\`\`\`python +def grant_delete( + identity: IGrantable, + objects_key_pattern: typing.Any = None +) -> Grant +\`\`\` + +Grants s3:DeleteObject* permission to an IAM principal for objects in this bucket. + +###### \`identity\`Required + +- *Type:* aws_cdk.aws_iam.IGrantable + +The principal. + +--- + +###### \`objects_key_pattern\`Optional + +- *Type:* typing.Any + +Restrict the permission to a certain key pattern (default '*'). + +--- + +##### \`grant_public_access\` + +\`\`\`python +def grant_public_access( + allowed_actions: str, + key_prefix: str = None +) -> Grant +\`\`\` + +Allows unrestricted access to objects from this bucket. + +IMPORTANT: This permission allows anyone to perform actions on S3 objects +in this bucket, which is useful for when you configure your bucket as a +website and want everyone to be able to read objects in the bucket without +needing to authenticate. + +Without arguments, this method will grant read ("s3:GetObject") access to +all objects ("*") in the bucket. + +The method returns the \`iam.Grant\` object, which can then be modified +as needed. For example, you can add a condition that will restrict access only +to an IPv4 range like this: + + const grant = bucket.grantPublicAccess(); + grant.resourceStatement!.addCondition(‘IpAddress’, { “aws:SourceIp”: “54.240.143.0/24” }); + +Note that if this \`IBucket\` refers to an existing bucket, possibly not +managed by CloudFormation, this method will have no effect, since it's +impossible to modify the policy of an existing bucket. + +###### \`allowed_actions\`Required + +- *Type:* str + +the set of S3 actions to allow. + +Default is "s3:GetObject". + +--- + +###### \`key_prefix\`Optional + +- *Type:* str + +the prefix of S3 object keys (e.g. \`home/*\`). Default is "*". + +--- + +##### \`grant_put\` + +\`\`\`python +def grant_put( + identity: IGrantable, + objects_key_pattern: typing.Any = None +) -> Grant +\`\`\` + +Grants s3:PutObject* and s3:Abort* permissions for this bucket to an IAM principal. + +If encryption is used, permission to use the key to encrypt the contents +of written files will also be granted to the same principal. + +###### \`identity\`Required + +- *Type:* aws_cdk.aws_iam.IGrantable + +The principal. + +--- + +###### \`objects_key_pattern\`Optional + +- *Type:* typing.Any + +Restrict the permission to a certain key pattern (default '*'). + +--- + +##### \`grant_put_acl\` + +\`\`\`python +def grant_put_acl( + identity: IGrantable, + objects_key_pattern: str = None +) -> Grant +\`\`\` + +Grant the given IAM identity permissions to modify the ACLs of objects in the given Bucket. + +If your application has the '@aws-cdk/aws-s3:grantWriteWithoutAcl' feature flag set, +calling {@link grantWrite} or {@link grantReadWrite} no longer grants permissions to modify the ACLs of the objects; +in this case, if you need to modify object ACLs, call this method explicitly. + +###### \`identity\`Required + +- *Type:* aws_cdk.aws_iam.IGrantable + +--- + +###### \`objects_key_pattern\`Optional + +- *Type:* str + +--- + +##### \`grant_read\` + +\`\`\`python +def grant_read( + identity: IGrantable, + objects_key_pattern: typing.Any = None +) -> Grant +\`\`\` + +Grant read permissions for this bucket and it's contents to an IAM principal (Role/Group/User). + +If encryption is used, permission to use the key to decrypt the contents +of the bucket will also be granted to the same principal. + +###### \`identity\`Required + +- *Type:* aws_cdk.aws_iam.IGrantable + +The principal. + +--- + +###### \`objects_key_pattern\`Optional + +- *Type:* typing.Any + +Restrict the permission to a certain key pattern (default '*'). + +--- + +##### \`grant_read_write\` + +\`\`\`python +def grant_read_write( + identity: IGrantable, + objects_key_pattern: typing.Any = None +) -> Grant +\`\`\` + +Grants read/write permissions for this bucket and it's contents to an IAM principal (Role/Group/User). + +If an encryption key is used, permission to use the key for +encrypt/decrypt will also be granted. + +Before CDK version 1.85.0, this method granted the \`s3:PutObject*\` permission that included \`s3:PutObjectAcl\`, +which could be used to grant read/write object access to IAM principals in other accounts. +If you want to get rid of that behavior, update your CDK version to 1.85.0 or later, +and make sure the \`@aws-cdk/aws-s3:grantWriteWithoutAcl\` feature flag is set to \`true\` +in the \`context\` key of your cdk.json file. +If you've already updated, but still need the principal to have permissions to modify the ACLs, +use the {@link grantPutAcl} method. + +###### \`identity\`Required + +- *Type:* aws_cdk.aws_iam.IGrantable + +--- + +###### \`objects_key_pattern\`Optional + +- *Type:* typing.Any + +--- + +##### \`grant_write\` + +\`\`\`python +def grant_write( + identity: IGrantable, + objects_key_pattern: typing.Any = None +) -> Grant +\`\`\` + +Grant write permissions to this bucket to an IAM principal. + +If encryption is used, permission to use the key to encrypt the contents +of written files will also be granted to the same principal. + +Before CDK version 1.85.0, this method granted the \`s3:PutObject*\` permission that included \`s3:PutObjectAcl\`, +which could be used to grant read/write object access to IAM principals in other accounts. +If you want to get rid of that behavior, update your CDK version to 1.85.0 or later, +and make sure the \`@aws-cdk/aws-s3:grantWriteWithoutAcl\` feature flag is set to \`true\` +in the \`context\` key of your cdk.json file. +If you've already updated, but still need the principal to have permissions to modify the ACLs, +use the {@link grantPutAcl} method. + +###### \`identity\`Required + +- *Type:* aws_cdk.aws_iam.IGrantable + +--- + +###### \`objects_key_pattern\`Optional + +- *Type:* typing.Any + +--- + +##### \`on_cloud_trail_event\` + +\`\`\`python +def on_cloud_trail_event( + id: str, + description: str = None, + event_pattern: EventPattern = None, + rule_name: str = None, + target: IRuleTarget = None, + paths: typing.List[str] = None +) -> Rule +\`\`\` + +Define a CloudWatch event that triggers when something happens to this repository. + +Requires that there exists at least one CloudTrail Trail in your account +that captures the event. This method will not create the Trail. + +###### \`id\`Required + +- *Type:* str + +The id of the rule. + +--- + +###### \`description\`Optional + +- *Type:* str +- *Default:* No description + +A description of the rule's purpose. + +--- + +###### \`event_pattern\`Optional + +- *Type:* aws_cdk.aws_events.EventPattern +- *Default:* No additional filtering based on an event pattern. + +Additional restrictions for the event to route to the specified target. + +The method that generates the rule probably imposes some type of event +filtering. The filtering implied by what you pass here is added +on top of that filtering. + +> [https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-and-event-patterns.html](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-and-event-patterns.html) + +--- + +###### \`rule_name\`Optional + +- *Type:* str +- *Default:* AWS CloudFormation generates a unique physical ID. + +A name for the rule. + +--- + +###### \`target\`Optional + +- *Type:* aws_cdk.aws_events.IRuleTarget +- *Default:* No target is added to the rule. Use \`addTarget()\` to add a target. + +The target to register for the event. + +--- + +###### \`paths\`Optional + +- *Type:* typing.List[str] +- *Default:* Watch changes to all objects + +Only watch changes to these object paths. + +--- + +##### \`on_cloud_trail_put_object\` + +\`\`\`python +def on_cloud_trail_put_object( + id: str, + description: str = None, + event_pattern: EventPattern = None, + rule_name: str = None, + target: IRuleTarget = None, + paths: typing.List[str] = None +) -> Rule +\`\`\` + +Defines an AWS CloudWatch event that triggers when an object is uploaded to the specified paths (keys) in this bucket using the PutObject API call. + +Note that some tools like \`aws s3 cp\` will automatically use either +PutObject or the multipart upload API depending on the file size, +so using \`onCloudTrailWriteObject\` may be preferable. + +Requires that there exists at least one CloudTrail Trail in your account +that captures the event. This method will not create the Trail. + +###### \`id\`Required + +- *Type:* str + +The id of the rule. + +--- + +###### \`description\`Optional + +- *Type:* str +- *Default:* No description + +A description of the rule's purpose. + +--- + +###### \`event_pattern\`Optional + +- *Type:* aws_cdk.aws_events.EventPattern +- *Default:* No additional filtering based on an event pattern. + +Additional restrictions for the event to route to the specified target. + +The method that generates the rule probably imposes some type of event +filtering. The filtering implied by what you pass here is added +on top of that filtering. + +> [https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-and-event-patterns.html](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-and-event-patterns.html) + +--- + +###### \`rule_name\`Optional + +- *Type:* str +- *Default:* AWS CloudFormation generates a unique physical ID. + +A name for the rule. + +--- + +###### \`target\`Optional + +- *Type:* aws_cdk.aws_events.IRuleTarget +- *Default:* No target is added to the rule. Use \`addTarget()\` to add a target. + +The target to register for the event. + +--- + +###### \`paths\`Optional + +- *Type:* typing.List[str] +- *Default:* Watch changes to all objects + +Only watch changes to these object paths. + +--- + +##### \`on_cloud_trail_write_object\` + +\`\`\`python +def on_cloud_trail_write_object( + id: str, + description: str = None, + event_pattern: EventPattern = None, + rule_name: str = None, + target: IRuleTarget = None, + paths: typing.List[str] = None +) -> Rule +\`\`\` + +Defines an AWS CloudWatch event that triggers when an object at the specified paths (keys) in this bucket are written to. + +This includes +the events PutObject, CopyObject, and CompleteMultipartUpload. + +Note that some tools like \`aws s3 cp\` will automatically use either +PutObject or the multipart upload API depending on the file size, +so using this method may be preferable to \`onCloudTrailPutObject\`. + +Requires that there exists at least one CloudTrail Trail in your account +that captures the event. This method will not create the Trail. + +###### \`id\`Required + +- *Type:* str + +The id of the rule. + +--- + +###### \`description\`Optional + +- *Type:* str +- *Default:* No description + +A description of the rule's purpose. + +--- + +###### \`event_pattern\`Optional + +- *Type:* aws_cdk.aws_events.EventPattern +- *Default:* No additional filtering based on an event pattern. + +Additional restrictions for the event to route to the specified target. + +The method that generates the rule probably imposes some type of event +filtering. The filtering implied by what you pass here is added +on top of that filtering. + +> [https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-and-event-patterns.html](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-and-event-patterns.html) + +--- + +###### \`rule_name\`Optional + +- *Type:* str +- *Default:* AWS CloudFormation generates a unique physical ID. + +A name for the rule. + +--- + +###### \`target\`Optional + +- *Type:* aws_cdk.aws_events.IRuleTarget +- *Default:* No target is added to the rule. Use \`addTarget()\` to add a target. + +The target to register for the event. + +--- + +###### \`paths\`Optional + +- *Type:* typing.List[str] +- *Default:* Watch changes to all objects + +Only watch changes to these object paths. + +--- + +##### \`s3_url_for_object\` + +\`\`\`python +def s3_url_for_object( + key: str = None +) -> str +\`\`\` + +The S3 URL of an S3 object. For example:. + +\`s3://onlybucket\` +- \`s3://bucket/key\` + +###### \`key\`Optional + +- *Type:* str + +The S3 key of the object. + +If not specified, the S3 URL of the +bucket is returned. + +--- + +##### \`transfer_acceleration_url_for_object\` + +\`\`\`python +def transfer_acceleration_url_for_object( + key: str = None, + dual_stack: bool = None +) -> str +\`\`\` + +The https Transfer Acceleration URL of an S3 object. + +Specify \`dualStack: true\` at the options +for dual-stack endpoint (connect to the bucket over IPv6). For example: + +- \`https://bucket.s3-accelerate.amazonaws.com\` +- \`https://bucket.s3-accelerate.amazonaws.com/key\` + +###### \`key\`Optional + +- *Type:* str + +The S3 key of the object. + +If not specified, the URL of the +bucket is returned. + +--- + +###### \`dual_stack\`Optional + +- *Type:* bool +- *Default:* false + +Dual-stack support to connect to the bucket over IPv6. + +--- + +##### \`url_for_object\` + +\`\`\`python +def url_for_object( + key: str = None +) -> str +\`\`\` + +The https URL of an S3 object. Specify \`regional: false\` at the options for non-regional URLs. For example:. + +\`https://s3.us-west-1.amazonaws.com/onlybucket\` +- \`https://s3.us-west-1.amazonaws.com/bucket/key\` +- \`https://s3.cn-north-1.amazonaws.com.cn/china-bucket/mykey\` + +###### \`key\`Optional + +- *Type:* str + +The S3 key of the object. + +If not specified, the URL of the +bucket is returned. + +--- + +##### \`virtual_hosted_url_for_object\` + +\`\`\`python +def virtual_hosted_url_for_object( + key: str = None, + regional: bool = None +) -> str +\`\`\` + +The virtual hosted-style URL of an S3 object. Specify \`regional: false\` at the options for non-regional URL. For example:. + +\`https://only-bucket.s3.us-west-1.amazonaws.com\` +- \`https://bucket.s3.us-west-1.amazonaws.com/key\` +- \`https://bucket.s3.amazonaws.com/key\` +- \`https://china-bucket.s3.cn-north-1.amazonaws.com.cn/mykey\` + +###### \`key\`Optional + +- *Type:* str + +The S3 key of the object. + +If not specified, the URL of the +bucket is returned. + +--- + +###### \`regional\`Optional + +- *Type:* bool +- *Default:* true + +Specifies the URL includes the region. + +--- + +##### \`add_cors_rule\` + +\`\`\`python +def add_cors_rule( + allowed_methods: typing.List[HttpMethods], + allowed_origins: typing.List[str], + allowed_headers: typing.List[str] = None, + exposed_headers: typing.List[str] = None, + id: str = None, + max_age: typing.Union[int, float] = None +) -> None +\`\`\` + +Adds a cross-origin access configuration for objects in an Amazon S3 bucket. + +###### \`allowed_methods\`Required + +- *Type:* typing.List[aws_cdk.aws_s3.HttpMethods] + +An HTTP method that you allow the origin to execute. + +--- + +###### \`allowed_origins\`Required + +- *Type:* typing.List[str] + +One or more origins you want customers to be able to access the bucket from. + +--- + +###### \`allowed_headers\`Optional + +- *Type:* typing.List[str] +- *Default:* No headers allowed. + +Headers that are specified in the Access-Control-Request-Headers header. + +--- + +###### \`exposed_headers\`Optional + +- *Type:* typing.List[str] +- *Default:* No headers exposed. + +One or more headers in the response that you want customers to be able to access from their applications. + +--- + +###### \`id\`Optional + +- *Type:* str +- *Default:* No id specified. + +A unique identifier for this rule. + +--- + +###### \`max_age\`Optional + +- *Type:* typing.Union[int, float] +- *Default:* No caching. + +The time in seconds that your browser is to cache the preflight response for the specified resource. + +--- + +##### \`add_inventory\` + +\`\`\`python +def add_inventory( + destination: InventoryDestination, + enabled: bool = None, + format: InventoryFormat = None, + frequency: InventoryFrequency = None, + include_object_versions: InventoryObjectVersion = None, + inventory_id: str = None, + objects_prefix: str = None, + optional_fields: typing.List[str] = None +) -> None +\`\`\` + +Add an inventory configuration. + +###### \`destination\`Required + +- *Type:* aws_cdk.aws_s3.InventoryDestination + +The destination of the inventory. + +--- + +###### \`enabled\`Optional + +- *Type:* bool +- *Default:* true + +Whether the inventory is enabled or disabled. + +--- + +###### \`format\`Optional + +- *Type:* aws_cdk.aws_s3.InventoryFormat +- *Default:* InventoryFormat.CSV + +The format of the inventory. + +--- + +###### \`frequency\`Optional + +- *Type:* aws_cdk.aws_s3.InventoryFrequency +- *Default:* InventoryFrequency.WEEKLY + +Frequency at which the inventory should be generated. + +--- + +###### \`include_object_versions\`Optional + +- *Type:* aws_cdk.aws_s3.InventoryObjectVersion +- *Default:* InventoryObjectVersion.ALL + +If the inventory should contain all the object versions or only the current one. + +--- + +###### \`inventory_id\`Optional + +- *Type:* str +- *Default:* generated ID. + +The inventory configuration ID. + +--- + +###### \`objects_prefix\`Optional + +- *Type:* str +- *Default:* No objects prefix + +The inventory will only include objects that meet the prefix filter criteria. + +--- + +###### \`optional_fields\`Optional + +- *Type:* typing.List[str] +- *Default:* No optional fields. + +A list of optional fields to be included in the inventory result. + +--- + +##### \`add_lifecycle_rule\` + +\`\`\`python +def add_lifecycle_rule( + abort_incomplete_multipart_upload_after: Duration = None, + enabled: bool = None, + expiration: Duration = None, + expiration_date: datetime.datetime = None, + expired_object_delete_marker: bool = None, + id: str = None, + noncurrent_version_expiration: Duration = None, + noncurrent_versions_to_retain: typing.Union[int, float] = None, + noncurrent_version_transitions: typing.List[NoncurrentVersionTransition] = None, + object_size_greater_than: typing.Union[int, float] = None, + object_size_less_than: typing.Union[int, float] = None, + prefix: str = None, + tag_filters: typing.Mapping[typing.Any] = None, + transitions: typing.List[Transition] = None +) -> None +\`\`\` + +Add a lifecycle rule to the bucket. + +###### \`abort_incomplete_multipart_upload_after\`Optional + +- *Type:* aws_cdk.core.Duration +- *Default:* Incomplete uploads are never aborted + +Specifies a lifecycle rule that aborts incomplete multipart uploads to an Amazon S3 bucket. + +The AbortIncompleteMultipartUpload property type creates a lifecycle +rule that aborts incomplete multipart uploads to an Amazon S3 bucket. +When Amazon S3 aborts a multipart upload, it deletes all parts +associated with the multipart upload. + +--- + +###### \`enabled\`Optional + +- *Type:* bool +- *Default:* true + +Whether this rule is enabled. + +--- + +###### \`expiration\`Optional + +- *Type:* aws_cdk.core.Duration +- *Default:* No expiration timeout + +Indicates the number of days after creation when objects are deleted from Amazon S3 and Amazon Glacier. + +If you specify an expiration and transition time, you must use the same +time unit for both properties (either in days or by date). The +expiration time must also be later than the transition time. + +--- + +###### \`expiration_date\`Optional + +- *Type:* datetime.datetime +- *Default:* No expiration date + +Indicates when objects are deleted from Amazon S3 and Amazon Glacier. + +The date value must be in ISO 8601 format. The time is always midnight UTC. + +If you specify an expiration and transition time, you must use the same +time unit for both properties (either in days or by date). The +expiration time must also be later than the transition time. + +--- + +###### \`expired_object_delete_marker\`Optional + +- *Type:* bool +- *Default:* false + +Indicates whether Amazon S3 will remove a delete marker with no noncurrent versions. + +If set to true, the delete marker will be expired. + +--- + +###### \`id\`Optional + +- *Type:* str + +A unique identifier for this rule. + +The value cannot be more than 255 characters. + +--- + +###### \`noncurrent_version_expiration\`Optional + +- *Type:* aws_cdk.core.Duration +- *Default:* No noncurrent version expiration + +Time between when a new version of the object is uploaded to the bucket and when old versions of the object expire. + +For buckets with versioning enabled (or suspended), specifies the time, +in days, between when a new version of the object is uploaded to the +bucket and when old versions of the object expire. When object versions +expire, Amazon S3 permanently deletes them. If you specify a transition +and expiration time, the expiration time must be later than the +transition time. + +--- + +###### \`noncurrent_versions_to_retain\`Optional + +- *Type:* typing.Union[int, float] +- *Default:* No noncurrent versions to retain + +Indicates a maximum number of noncurrent versions to retain. + +If there are this many more noncurrent versions, +Amazon S3 permanently deletes them. + +--- + +###### \`noncurrent_version_transitions\`Optional + +- *Type:* typing.List[aws_cdk.aws_s3.NoncurrentVersionTransition] + +One or more transition rules that specify when non-current objects transition to a specified storage class. + +Only for for buckets with versioning enabled (or suspended). + +If you specify a transition and expiration time, the expiration time +must be later than the transition time. + +--- + +###### \`object_size_greater_than\`Optional + +- *Type:* typing.Union[int, float] +- *Default:* No rule + +Specifies the minimum object size in bytes for this rule to apply to. + +--- + +###### \`object_size_less_than\`Optional + +- *Type:* typing.Union[int, float] +- *Default:* No rule + +Specifies the maximum object size in bytes for this rule to apply to. + +--- + +###### \`prefix\`Optional + +- *Type:* str +- *Default:* Rule applies to all objects + +Object key prefix that identifies one or more objects to which this rule applies. + +--- + +###### \`tag_filters\`Optional + +- *Type:* typing.Mapping[typing.Any] +- *Default:* Rule applies to all objects + +The TagFilter property type specifies tags to use to identify a subset of objects for an Amazon S3 bucket. + +--- + +###### \`transitions\`Optional + +- *Type:* typing.List[aws_cdk.aws_s3.Transition] +- *Default:* No transition rules + +One or more transition rules that specify when an object transitions to a specified storage class. + +If you specify an expiration and transition time, you must use the same +time unit for both properties (either in days or by date). The +expiration time must also be later than the transition time. + +--- + +##### \`add_metric\` + +\`\`\`python +def add_metric( + id: str, + prefix: str = None, + tag_filters: typing.Mapping[typing.Any] = None +) -> None +\`\`\` + +Adds a metrics configuration for the CloudWatch request metrics from the bucket. + +###### \`id\`Required + +- *Type:* str + +The ID used to identify the metrics configuration. + +--- + +###### \`prefix\`Optional + +- *Type:* str + +The prefix that an object must have to be included in the metrics results. + +--- + +###### \`tag_filters\`Optional + +- *Type:* typing.Mapping[typing.Any] + +Specifies a list of tag filters to use as a metrics configuration filter. + +The metrics configuration includes only objects that meet the filter's criteria. + +--- + +##### \`goodbye\` + +\`\`\`python +def goodbye() -> None +\`\`\` + +##### \`goodbye_with_phrase\` + +\`\`\`python +def goodbye_with_phrase( + phrase: str +) -> None +\`\`\` + +###### \`phrase\`Required + +- *Type:* str + +--- + +#### Static Functions + +| **Name** | **Description** | +| --- | --- | +| is_construct | Return whether the given object is a Construct. | +| is_resource | Check whether the given construct is a Resource. | +| from_bucket_arn | *No description.* | +| from_bucket_attributes | Creates a Bucket construct that represents an external bucket. | +| from_bucket_name | *No description.* | +| validate_bucket_name | Thrown an exception if the given bucket name is not valid. | + +--- + +##### \`is_construct\` + +\`\`\`python +from construct_library import submod1 + +submod1.GoodbyeBucket.is_construct( + x: typing.Any +) +\`\`\` + +Return whether the given object is a Construct. + +###### \`x\`Required + +- *Type:* typing.Any + +--- + +##### \`is_resource\` + +\`\`\`python +from construct_library import submod1 + +submod1.GoodbyeBucket.is_resource( + construct: IConstruct +) +\`\`\` + +Check whether the given construct is a Resource. + +###### \`construct\`Required + +- *Type:* aws_cdk.core.IConstruct + +--- + +##### \`from_bucket_arn\` + +\`\`\`python +from construct_library import submod1 + +submod1.GoodbyeBucket.from_bucket_arn( + scope: Construct, + id: str, + bucket_arn: str +) +\`\`\` + +###### \`scope\`Required + +- *Type:* constructs.Construct + +--- + +###### \`id\`Required + +- *Type:* str + +--- + +###### \`bucket_arn\`Required + +- *Type:* str + +--- + +##### \`from_bucket_attributes\` + +\`\`\`python +from construct_library import submod1 + +submod1.GoodbyeBucket.from_bucket_attributes( + scope: Construct, + id: str, + account: str = None, + bucket_arn: str = None, + bucket_domain_name: str = None, + bucket_dual_stack_domain_name: str = None, + bucket_name: str = None, + bucket_regional_domain_name: str = None, + bucket_website_new_url_format: bool = None, + bucket_website_url: str = None, + encryption_key: IKey = None, + is_website: bool = None, + notifications_handler_role: IRole = None, + region: str = None +) +\`\`\` + +Creates a Bucket construct that represents an external bucket. + +###### \`scope\`Required + +- *Type:* constructs.Construct + +The parent creating construct (usually \`this\`). + +--- + +###### \`id\`Required + +- *Type:* str + +The construct's name. + +--- + +###### \`account\`Optional + +- *Type:* str +- *Default:* it's assumed the bucket belongs to the same account as the scope it's being imported into + +The account this existing bucket belongs to. + +--- + +###### \`bucket_arn\`Optional + +- *Type:* str + +The ARN of the bucket. + +At least one of bucketArn or bucketName must be +defined in order to initialize a bucket ref. + +--- + +###### \`bucket_domain_name\`Optional + +- *Type:* str +- *Default:* Inferred from bucket name + +The domain name of the bucket. + +--- + +###### \`bucket_dual_stack_domain_name\`Optional + +- *Type:* str + +The IPv6 DNS name of the specified bucket. + +--- + +###### \`bucket_name\`Optional + +- *Type:* str + +The name of the bucket. + +If the underlying value of ARN is a string, the +name will be parsed from the ARN. Otherwise, the name is optional, but +some features that require the bucket name such as auto-creating a bucket +policy, won't work. + +--- + +###### \`bucket_regional_domain_name\`Optional + +- *Type:* str + +The regional domain name of the specified bucket. + +--- + +###### \`bucket_website_new_url_format\`Optional + +- *Type:* bool +- *Default:* false + +The format of the website URL of the bucket. + +This should be true for +regions launched since 2014. + +--- + +###### \`bucket_website_url\`Optional + +- *Type:* str +- *Default:* Inferred from bucket name + +The website URL of the bucket (if static web hosting is enabled). + +--- + +###### \`encryption_key\`Optional + +- *Type:* aws_cdk.aws_kms.IKey + +--- + +###### \`is_website\`Optional + +- *Type:* bool +- *Default:* false + +If this bucket has been configured for static website hosting. + +--- + +###### \`notifications_handler_role\`Optional + +- *Type:* aws_cdk.aws_iam.IRole +- *Default:* a new role will be created. + +The role to be used by the notifications handler. + +--- + +###### \`region\`Optional + +- *Type:* str +- *Default:* it's assumed the bucket is in the same region as the scope it's being imported into + +The region this existing bucket is in. + +--- + +##### \`from_bucket_name\` + +\`\`\`python +from construct_library import submod1 + +submod1.GoodbyeBucket.from_bucket_name( + scope: Construct, + id: str, + bucket_name: str +) +\`\`\` + +###### \`scope\`Required + +- *Type:* constructs.Construct + +--- + +###### \`id\`Required + +- *Type:* str + +--- + +###### \`bucket_name\`Required + +- *Type:* str + +--- + +##### \`validate_bucket_name\` + +\`\`\`python +from construct_library import submod1 + +submod1.GoodbyeBucket.validate_bucket_name( + physical_name: str +) +\`\`\` + +Thrown an exception if the given bucket name is not valid. + +###### \`physical_name\`Required + +- *Type:* str + +name of the bucket. + +--- + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| node | aws_cdk.core.ConstructNode | The construct tree node associated with this construct. | +| env | aws_cdk.core.ResourceEnvironment | The environment this resource belongs to. | +| stack | aws_cdk.core.Stack | The stack in which this resource is defined. | +| bucket_arn | str | The ARN of the bucket. | +| bucket_domain_name | str | The IPv4 DNS name of the specified bucket. | +| bucket_dual_stack_domain_name | str | The IPv6 DNS name of the specified bucket. | +| bucket_name | str | The name of the bucket. | +| bucket_regional_domain_name | str | The regional domain name of the specified bucket. | +| bucket_website_domain_name | str | The Domain name of the static website. | +| bucket_website_url | str | The URL of the static website. | +| encryption_key | aws_cdk.aws_kms.IKey | Optional KMS encryption key associated with this bucket. | +| is_website | bool | If this bucket has been configured for static website hosting. | +| policy | aws_cdk.aws_s3.BucketPolicy | The resource policy associated with this bucket. | + +--- + +##### \`node\`Required + +\`\`\`python +node: ConstructNode +\`\`\` + +- *Type:* aws_cdk.core.ConstructNode + +The construct tree node associated with this construct. + +--- + +##### \`env\`Required + +\`\`\`python +env: ResourceEnvironment +\`\`\` + +- *Type:* aws_cdk.core.ResourceEnvironment + +The environment this resource belongs to. + +For resources that are created and managed by the CDK +(generally, those created by creating new class instances like Role, Bucket, etc.), +this is always the same as the environment of the stack they belong to; +however, for imported resources +(those obtained from static methods like fromRoleArn, fromBucketName, etc.), +that might be different than the stack they were imported into. + +--- + +##### \`stack\`Required + +\`\`\`python +stack: Stack +\`\`\` + +- *Type:* aws_cdk.core.Stack + +The stack in which this resource is defined. + +--- + +##### \`bucket_arn\`Required + +\`\`\`python +bucket_arn: str +\`\`\` + +- *Type:* str + +The ARN of the bucket. + +--- + +##### \`bucket_domain_name\`Required + +\`\`\`python +bucket_domain_name: str +\`\`\` + +- *Type:* str + +The IPv4 DNS name of the specified bucket. + +--- + +##### \`bucket_dual_stack_domain_name\`Required + +\`\`\`python +bucket_dual_stack_domain_name: str +\`\`\` + +- *Type:* str + +The IPv6 DNS name of the specified bucket. + +--- + +##### \`bucket_name\`Required + +\`\`\`python +bucket_name: str +\`\`\` + +- *Type:* str + +The name of the bucket. + +--- + +##### \`bucket_regional_domain_name\`Required + +\`\`\`python +bucket_regional_domain_name: str +\`\`\` + +- *Type:* str + +The regional domain name of the specified bucket. + +--- + +##### \`bucket_website_domain_name\`Required + +\`\`\`python +bucket_website_domain_name: str +\`\`\` + +- *Type:* str + +The Domain name of the static website. + +--- + +##### \`bucket_website_url\`Required + +\`\`\`python +bucket_website_url: str +\`\`\` + +- *Type:* str + +The URL of the static website. + +--- + +##### \`encryption_key\`Optional + +\`\`\`python +encryption_key: IKey +\`\`\` + +- *Type:* aws_cdk.aws_kms.IKey + +Optional KMS encryption key associated with this bucket. + +--- + +##### \`is_website\`Optional + +\`\`\`python +is_website: bool +\`\`\` + +- *Type:* bool + +If this bucket has been configured for static website hosting. + +--- + +##### \`policy\`Optional + +\`\`\`python +policy: BucketPolicy +\`\`\` + +- *Type:* aws_cdk.aws_s3.BucketPolicy + +The resource policy associated with this bucket. + +If \`autoCreatePolicy\` is true, a \`BucketPolicy\` will be created upon the +first call to addToResourcePolicy(s). + +--- + + + + + +" +`; + +exports[`specify languages and split-by-submodule creates submodule files next to output: submod1.typescript.md 1`] = ` +"# \`submod1\` Submodule + +## Constructs + +### GoodbyeBucket + +#### Initializers + +\`\`\`typescript +import { submod1 } from 'construct-library' + +new submod1.GoodbyeBucket(scope: Construct, id: string, props?: BucketProps) +\`\`\` + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| scope | constructs.Construct | *No description.* | +| id | string | *No description.* | +| props | @aws-cdk/aws-s3.BucketProps | *No description.* | + +--- + +##### \`scope\`Required + +- *Type:* constructs.Construct + +--- + +##### \`id\`Required + +- *Type:* string + +--- + +##### \`props\`Optional + +- *Type:* @aws-cdk/aws-s3.BucketProps + +--- + +#### Methods + +| **Name** | **Description** | +| --- | --- | +| toString | Returns a string representation of this construct. | +| applyRemovalPolicy | Apply the given removal policy to this resource. | +| addEventNotification | Adds a bucket notification event destination. | +| addObjectCreatedNotification | Subscribes a destination to receive notifications when an object is created in the bucket. | +| addObjectRemovedNotification | Subscribes a destination to receive notifications when an object is removed from the bucket. | +| addToResourcePolicy | Adds a statement to the resource policy for a principal (i.e. account/role/service) to perform actions on this bucket and/or its contents. Use \`bucketArn\` and \`arnForObjects(keys)\` to obtain ARNs for this bucket or objects. | +| arnForObjects | Returns an ARN that represents all objects within the bucket that match the key pattern specified. | +| grantDelete | Grants s3:DeleteObject* permission to an IAM principal for objects in this bucket. | +| grantPublicAccess | Allows unrestricted access to objects from this bucket. | +| grantPut | Grants s3:PutObject* and s3:Abort* permissions for this bucket to an IAM principal. | +| grantPutAcl | Grant the given IAM identity permissions to modify the ACLs of objects in the given Bucket. | +| grantRead | Grant read permissions for this bucket and it's contents to an IAM principal (Role/Group/User). | +| grantReadWrite | Grants read/write permissions for this bucket and it's contents to an IAM principal (Role/Group/User). | +| grantWrite | Grant write permissions to this bucket to an IAM principal. | +| onCloudTrailEvent | Define a CloudWatch event that triggers when something happens to this repository. | +| onCloudTrailPutObject | Defines an AWS CloudWatch event that triggers when an object is uploaded to the specified paths (keys) in this bucket using the PutObject API call. | +| onCloudTrailWriteObject | Defines an AWS CloudWatch event that triggers when an object at the specified paths (keys) in this bucket are written to. | +| s3UrlForObject | The S3 URL of an S3 object. For example:. | +| transferAccelerationUrlForObject | The https Transfer Acceleration URL of an S3 object. | +| urlForObject | The https URL of an S3 object. Specify \`regional: false\` at the options for non-regional URLs. For example:. | +| virtualHostedUrlForObject | The virtual hosted-style URL of an S3 object. Specify \`regional: false\` at the options for non-regional URL. For example:. | +| addCorsRule | Adds a cross-origin access configuration for objects in an Amazon S3 bucket. | +| addInventory | Add an inventory configuration. | +| addLifecycleRule | Add a lifecycle rule to the bucket. | +| addMetric | Adds a metrics configuration for the CloudWatch request metrics from the bucket. | +| goodbye | *No description.* | +| goodbyeWithPhrase | *No description.* | + +--- + +##### \`toString\` + +\`\`\`typescript +public toString(): string +\`\`\` + +Returns a string representation of this construct. + +##### \`applyRemovalPolicy\` + +\`\`\`typescript +public applyRemovalPolicy(policy: RemovalPolicy): void +\`\`\` + +Apply the given removal policy to this resource. + +The Removal Policy controls what happens to this resource when it stops +being managed by CloudFormation, either because you've removed it from the +CDK application or because you've made a change that requires the resource +to be replaced. + +The resource can be deleted (\`RemovalPolicy.DESTROY\`), or left in your AWS +account for data recovery and cleanup later (\`RemovalPolicy.RETAIN\`). + +###### \`policy\`Required + +- *Type:* @aws-cdk/core.RemovalPolicy + +--- + +##### \`addEventNotification\` + +\`\`\`typescript +public addEventNotification(event: EventType, dest: IBucketNotificationDestination, filters: NotificationKeyFilter): void +\`\`\` + +Adds a bucket notification event destination. + +> [https://docs.aws.amazon.com/AmazonS3/latest/dev/NotificationHowTo.html](https://docs.aws.amazon.com/AmazonS3/latest/dev/NotificationHowTo.html) + +*Example* + +\`\`\`typescript + declare const myLambda: lambda.Function; + const bucket = new s3.Bucket(this, 'MyBucket'); + bucket.addEventNotification(s3.EventType.OBJECT_CREATED, new s3n.LambdaDestination(myLambda), {prefix: 'home/myusername/*'}); +\`\`\` + + +###### \`event\`Required + +- *Type:* @aws-cdk/aws-s3.EventType + +The event to trigger the notification. + +--- + +###### \`dest\`Required + +- *Type:* @aws-cdk/aws-s3.IBucketNotificationDestination + +The notification destination (Lambda, SNS Topic or SQS Queue). + +--- + +###### \`filters\`Required + +- *Type:* @aws-cdk/aws-s3.NotificationKeyFilter + +S3 object key filter rules to determine which objects trigger this event. + +Each filter must include a \`prefix\` and/or \`suffix\` +that will be matched against the s3 object key. Refer to the S3 Developer Guide +for details about allowed filter rules. + +--- + +##### \`addObjectCreatedNotification\` + +\`\`\`typescript +public addObjectCreatedNotification(dest: IBucketNotificationDestination, filters: NotificationKeyFilter): void +\`\`\` + +Subscribes a destination to receive notifications when an object is created in the bucket. + +This is identical to calling +\`onEvent(EventType.OBJECT_CREATED)\`. + +###### \`dest\`Required + +- *Type:* @aws-cdk/aws-s3.IBucketNotificationDestination + +The notification destination (see onEvent). + +--- + +###### \`filters\`Required + +- *Type:* @aws-cdk/aws-s3.NotificationKeyFilter + +Filters (see onEvent). + +--- + +##### \`addObjectRemovedNotification\` + +\`\`\`typescript +public addObjectRemovedNotification(dest: IBucketNotificationDestination, filters: NotificationKeyFilter): void +\`\`\` + +Subscribes a destination to receive notifications when an object is removed from the bucket. + +This is identical to calling +\`onEvent(EventType.OBJECT_REMOVED)\`. + +###### \`dest\`Required + +- *Type:* @aws-cdk/aws-s3.IBucketNotificationDestination + +The notification destination (see onEvent). + +--- + +###### \`filters\`Required + +- *Type:* @aws-cdk/aws-s3.NotificationKeyFilter + +Filters (see onEvent). + +--- + +##### \`addToResourcePolicy\` + +\`\`\`typescript +public addToResourcePolicy(permission: PolicyStatement): AddToResourcePolicyResult +\`\`\` + +Adds a statement to the resource policy for a principal (i.e. account/role/service) to perform actions on this bucket and/or its contents. Use \`bucketArn\` and \`arnForObjects(keys)\` to obtain ARNs for this bucket or objects. + +Note that the policy statement may or may not be added to the policy. +For example, when an \`IBucket\` is created from an existing bucket, +it's not possible to tell whether the bucket already has a policy +attached, let alone to re-use that policy to add more statements to it. +So it's safest to do nothing in these cases. + +###### \`permission\`Required + +- *Type:* @aws-cdk/aws-iam.PolicyStatement + +the policy statement to be added to the bucket's policy. + +--- + +##### \`arnForObjects\` + +\`\`\`typescript +public arnForObjects(keyPattern: string): string +\`\`\` + +Returns an ARN that represents all objects within the bucket that match the key pattern specified. + +To represent all keys, specify \`\`"*"\`\`. + +If you need to specify a keyPattern with multiple components, concatenate them into a single string, e.g.: + + arnForObjects(\`home/\${team}/\${user}/*\`) + +###### \`keyPattern\`Required + +- *Type:* string + +--- + +##### \`grantDelete\` + +\`\`\`typescript +public grantDelete(identity: IGrantable, objectsKeyPattern?: any): Grant +\`\`\` + +Grants s3:DeleteObject* permission to an IAM principal for objects in this bucket. + +###### \`identity\`Required + +- *Type:* @aws-cdk/aws-iam.IGrantable + +The principal. + +--- + +###### \`objectsKeyPattern\`Optional + +- *Type:* any + +Restrict the permission to a certain key pattern (default '*'). + +--- + +##### \`grantPublicAccess\` + +\`\`\`typescript +public grantPublicAccess(allowedActions: string, keyPrefix?: string): Grant +\`\`\` + +Allows unrestricted access to objects from this bucket. + +IMPORTANT: This permission allows anyone to perform actions on S3 objects +in this bucket, which is useful for when you configure your bucket as a +website and want everyone to be able to read objects in the bucket without +needing to authenticate. + +Without arguments, this method will grant read ("s3:GetObject") access to +all objects ("*") in the bucket. + +The method returns the \`iam.Grant\` object, which can then be modified +as needed. For example, you can add a condition that will restrict access only +to an IPv4 range like this: + + const grant = bucket.grantPublicAccess(); + grant.resourceStatement!.addCondition(‘IpAddress’, { “aws:SourceIp”: “54.240.143.0/24” }); + +Note that if this \`IBucket\` refers to an existing bucket, possibly not +managed by CloudFormation, this method will have no effect, since it's +impossible to modify the policy of an existing bucket. + +###### \`allowedActions\`Required + +- *Type:* string + +the set of S3 actions to allow. + +Default is "s3:GetObject". + +--- + +###### \`keyPrefix\`Optional + +- *Type:* string + +the prefix of S3 object keys (e.g. \`home/*\`). Default is "*". + +--- + +##### \`grantPut\` + +\`\`\`typescript +public grantPut(identity: IGrantable, objectsKeyPattern?: any): Grant +\`\`\` + +Grants s3:PutObject* and s3:Abort* permissions for this bucket to an IAM principal. + +If encryption is used, permission to use the key to encrypt the contents +of written files will also be granted to the same principal. + +###### \`identity\`Required + +- *Type:* @aws-cdk/aws-iam.IGrantable + +The principal. + +--- + +###### \`objectsKeyPattern\`Optional + +- *Type:* any + +Restrict the permission to a certain key pattern (default '*'). + +--- + +##### \`grantPutAcl\` + +\`\`\`typescript +public grantPutAcl(identity: IGrantable, objectsKeyPattern?: string): Grant +\`\`\` + +Grant the given IAM identity permissions to modify the ACLs of objects in the given Bucket. + +If your application has the '@aws-cdk/aws-s3:grantWriteWithoutAcl' feature flag set, +calling {@link grantWrite} or {@link grantReadWrite} no longer grants permissions to modify the ACLs of the objects; +in this case, if you need to modify object ACLs, call this method explicitly. + +###### \`identity\`Required + +- *Type:* @aws-cdk/aws-iam.IGrantable + +--- + +###### \`objectsKeyPattern\`Optional + +- *Type:* string + +--- + +##### \`grantRead\` + +\`\`\`typescript +public grantRead(identity: IGrantable, objectsKeyPattern?: any): Grant +\`\`\` + +Grant read permissions for this bucket and it's contents to an IAM principal (Role/Group/User). + +If encryption is used, permission to use the key to decrypt the contents +of the bucket will also be granted to the same principal. + +###### \`identity\`Required + +- *Type:* @aws-cdk/aws-iam.IGrantable + +The principal. + +--- + +###### \`objectsKeyPattern\`Optional + +- *Type:* any + +Restrict the permission to a certain key pattern (default '*'). + +--- + +##### \`grantReadWrite\` + +\`\`\`typescript +public grantReadWrite(identity: IGrantable, objectsKeyPattern?: any): Grant +\`\`\` + +Grants read/write permissions for this bucket and it's contents to an IAM principal (Role/Group/User). + +If an encryption key is used, permission to use the key for +encrypt/decrypt will also be granted. + +Before CDK version 1.85.0, this method granted the \`s3:PutObject*\` permission that included \`s3:PutObjectAcl\`, +which could be used to grant read/write object access to IAM principals in other accounts. +If you want to get rid of that behavior, update your CDK version to 1.85.0 or later, +and make sure the \`@aws-cdk/aws-s3:grantWriteWithoutAcl\` feature flag is set to \`true\` +in the \`context\` key of your cdk.json file. +If you've already updated, but still need the principal to have permissions to modify the ACLs, +use the {@link grantPutAcl} method. + +###### \`identity\`Required + +- *Type:* @aws-cdk/aws-iam.IGrantable + +--- + +###### \`objectsKeyPattern\`Optional + +- *Type:* any + +--- + +##### \`grantWrite\` + +\`\`\`typescript +public grantWrite(identity: IGrantable, objectsKeyPattern?: any): Grant +\`\`\` + +Grant write permissions to this bucket to an IAM principal. + +If encryption is used, permission to use the key to encrypt the contents +of written files will also be granted to the same principal. + +Before CDK version 1.85.0, this method granted the \`s3:PutObject*\` permission that included \`s3:PutObjectAcl\`, +which could be used to grant read/write object access to IAM principals in other accounts. +If you want to get rid of that behavior, update your CDK version to 1.85.0 or later, +and make sure the \`@aws-cdk/aws-s3:grantWriteWithoutAcl\` feature flag is set to \`true\` +in the \`context\` key of your cdk.json file. +If you've already updated, but still need the principal to have permissions to modify the ACLs, +use the {@link grantPutAcl} method. + +###### \`identity\`Required + +- *Type:* @aws-cdk/aws-iam.IGrantable + +--- + +###### \`objectsKeyPattern\`Optional + +- *Type:* any + +--- + +##### \`onCloudTrailEvent\` + +\`\`\`typescript +public onCloudTrailEvent(id: string, options?: OnCloudTrailBucketEventOptions): Rule +\`\`\` + +Define a CloudWatch event that triggers when something happens to this repository. + +Requires that there exists at least one CloudTrail Trail in your account +that captures the event. This method will not create the Trail. + +###### \`id\`Required + +- *Type:* string + +The id of the rule. + +--- + +###### \`options\`Optional + +- *Type:* @aws-cdk/aws-s3.OnCloudTrailBucketEventOptions + +Options for adding the rule. + +--- + +##### \`onCloudTrailPutObject\` + +\`\`\`typescript +public onCloudTrailPutObject(id: string, options?: OnCloudTrailBucketEventOptions): Rule +\`\`\` + +Defines an AWS CloudWatch event that triggers when an object is uploaded to the specified paths (keys) in this bucket using the PutObject API call. + +Note that some tools like \`aws s3 cp\` will automatically use either +PutObject or the multipart upload API depending on the file size, +so using \`onCloudTrailWriteObject\` may be preferable. + +Requires that there exists at least one CloudTrail Trail in your account +that captures the event. This method will not create the Trail. + +###### \`id\`Required + +- *Type:* string + +The id of the rule. + +--- + +###### \`options\`Optional + +- *Type:* @aws-cdk/aws-s3.OnCloudTrailBucketEventOptions + +Options for adding the rule. + +--- + +##### \`onCloudTrailWriteObject\` + +\`\`\`typescript +public onCloudTrailWriteObject(id: string, options?: OnCloudTrailBucketEventOptions): Rule +\`\`\` + +Defines an AWS CloudWatch event that triggers when an object at the specified paths (keys) in this bucket are written to. + +This includes +the events PutObject, CopyObject, and CompleteMultipartUpload. + +Note that some tools like \`aws s3 cp\` will automatically use either +PutObject or the multipart upload API depending on the file size, +so using this method may be preferable to \`onCloudTrailPutObject\`. + +Requires that there exists at least one CloudTrail Trail in your account +that captures the event. This method will not create the Trail. + +###### \`id\`Required + +- *Type:* string + +The id of the rule. + +--- + +###### \`options\`Optional + +- *Type:* @aws-cdk/aws-s3.OnCloudTrailBucketEventOptions + +Options for adding the rule. + +--- + +##### \`s3UrlForObject\` + +\`\`\`typescript +public s3UrlForObject(key?: string): string +\`\`\` + +The S3 URL of an S3 object. For example:. + +\`s3://onlybucket\` +- \`s3://bucket/key\` + +###### \`key\`Optional + +- *Type:* string + +The S3 key of the object. + +If not specified, the S3 URL of the +bucket is returned. + +--- + +##### \`transferAccelerationUrlForObject\` + +\`\`\`typescript +public transferAccelerationUrlForObject(key?: string, options?: TransferAccelerationUrlOptions): string +\`\`\` + +The https Transfer Acceleration URL of an S3 object. + +Specify \`dualStack: true\` at the options +for dual-stack endpoint (connect to the bucket over IPv6). For example: + +- \`https://bucket.s3-accelerate.amazonaws.com\` +- \`https://bucket.s3-accelerate.amazonaws.com/key\` + +###### \`key\`Optional + +- *Type:* string + +The S3 key of the object. + +If not specified, the URL of the +bucket is returned. + +--- + +###### \`options\`Optional + +- *Type:* @aws-cdk/aws-s3.TransferAccelerationUrlOptions + +Options for generating URL. + +--- + +##### \`urlForObject\` + +\`\`\`typescript +public urlForObject(key?: string): string +\`\`\` + +The https URL of an S3 object. Specify \`regional: false\` at the options for non-regional URLs. For example:. + +\`https://s3.us-west-1.amazonaws.com/onlybucket\` +- \`https://s3.us-west-1.amazonaws.com/bucket/key\` +- \`https://s3.cn-north-1.amazonaws.com.cn/china-bucket/mykey\` + +###### \`key\`Optional + +- *Type:* string + +The S3 key of the object. + +If not specified, the URL of the +bucket is returned. + +--- + +##### \`virtualHostedUrlForObject\` + +\`\`\`typescript +public virtualHostedUrlForObject(key?: string, options?: VirtualHostedStyleUrlOptions): string +\`\`\` + +The virtual hosted-style URL of an S3 object. Specify \`regional: false\` at the options for non-regional URL. For example:. + +\`https://only-bucket.s3.us-west-1.amazonaws.com\` +- \`https://bucket.s3.us-west-1.amazonaws.com/key\` +- \`https://bucket.s3.amazonaws.com/key\` +- \`https://china-bucket.s3.cn-north-1.amazonaws.com.cn/mykey\` + +###### \`key\`Optional + +- *Type:* string + +The S3 key of the object. + +If not specified, the URL of the +bucket is returned. + +--- + +###### \`options\`Optional + +- *Type:* @aws-cdk/aws-s3.VirtualHostedStyleUrlOptions + +Options for generating URL. + +--- + +##### \`addCorsRule\` + +\`\`\`typescript +public addCorsRule(rule: CorsRule): void +\`\`\` + +Adds a cross-origin access configuration for objects in an Amazon S3 bucket. + +###### \`rule\`Required + +- *Type:* @aws-cdk/aws-s3.CorsRule + +The CORS configuration rule to add. + +--- + +##### \`addInventory\` + +\`\`\`typescript +public addInventory(inventory: Inventory): void +\`\`\` + +Add an inventory configuration. + +###### \`inventory\`Required + +- *Type:* @aws-cdk/aws-s3.Inventory + +configuration to add. + +--- + +##### \`addLifecycleRule\` + +\`\`\`typescript +public addLifecycleRule(rule: LifecycleRule): void +\`\`\` + +Add a lifecycle rule to the bucket. + +###### \`rule\`Required + +- *Type:* @aws-cdk/aws-s3.LifecycleRule + +The rule to add. + +--- + +##### \`addMetric\` + +\`\`\`typescript +public addMetric(metric: BucketMetrics): void +\`\`\` + +Adds a metrics configuration for the CloudWatch request metrics from the bucket. + +###### \`metric\`Required + +- *Type:* @aws-cdk/aws-s3.BucketMetrics + +The metric configuration to add. + +--- + +##### \`goodbye\` + +\`\`\`typescript +public goodbye(): void +\`\`\` + +##### \`goodbyeWithPhrase\` + +\`\`\`typescript +public goodbyeWithPhrase(phrase: string): void +\`\`\` + +###### \`phrase\`Required + +- *Type:* string + +--- + +#### Static Functions + +| **Name** | **Description** | +| --- | --- | +| isConstruct | Return whether the given object is a Construct. | +| isResource | Check whether the given construct is a Resource. | +| fromBucketArn | *No description.* | +| fromBucketAttributes | Creates a Bucket construct that represents an external bucket. | +| fromBucketName | *No description.* | +| validateBucketName | Thrown an exception if the given bucket name is not valid. | + +--- + +##### \`isConstruct\` + +\`\`\`typescript +import { submod1 } from 'construct-library' + +submod1.GoodbyeBucket.isConstruct(x: any) +\`\`\` + +Return whether the given object is a Construct. + +###### \`x\`Required + +- *Type:* any + +--- + +##### \`isResource\` + +\`\`\`typescript +import { submod1 } from 'construct-library' + +submod1.GoodbyeBucket.isResource(construct: IConstruct) +\`\`\` + +Check whether the given construct is a Resource. + +###### \`construct\`Required + +- *Type:* @aws-cdk/core.IConstruct + +--- + +##### \`fromBucketArn\` + +\`\`\`typescript +import { submod1 } from 'construct-library' + +submod1.GoodbyeBucket.fromBucketArn(scope: Construct, id: string, bucketArn: string) +\`\`\` + +###### \`scope\`Required + +- *Type:* constructs.Construct + +--- + +###### \`id\`Required + +- *Type:* string + +--- + +###### \`bucketArn\`Required + +- *Type:* string + +--- + +##### \`fromBucketAttributes\` + +\`\`\`typescript +import { submod1 } from 'construct-library' + +submod1.GoodbyeBucket.fromBucketAttributes(scope: Construct, id: string, attrs: BucketAttributes) +\`\`\` + +Creates a Bucket construct that represents an external bucket. + +###### \`scope\`Required + +- *Type:* constructs.Construct + +The parent creating construct (usually \`this\`). + +--- + +###### \`id\`Required + +- *Type:* string + +The construct's name. + +--- + +###### \`attrs\`Required + +- *Type:* @aws-cdk/aws-s3.BucketAttributes + +A \`BucketAttributes\` object. + +Can be obtained from a call to +\`bucket.export()\` or manually created. + +--- + +##### \`fromBucketName\` + +\`\`\`typescript +import { submod1 } from 'construct-library' + +submod1.GoodbyeBucket.fromBucketName(scope: Construct, id: string, bucketName: string) +\`\`\` + +###### \`scope\`Required + +- *Type:* constructs.Construct + +--- + +###### \`id\`Required + +- *Type:* string + +--- + +###### \`bucketName\`Required + +- *Type:* string + +--- + +##### \`validateBucketName\` + +\`\`\`typescript +import { submod1 } from 'construct-library' + +submod1.GoodbyeBucket.validateBucketName(physicalName: string) +\`\`\` + +Thrown an exception if the given bucket name is not valid. + +###### \`physicalName\`Required + +- *Type:* string + +name of the bucket. + +--- + +#### Properties + +| **Name** | **Type** | **Description** | +| --- | --- | --- | +| node | @aws-cdk/core.ConstructNode | The construct tree node associated with this construct. | +| env | @aws-cdk/core.ResourceEnvironment | The environment this resource belongs to. | +| stack | @aws-cdk/core.Stack | The stack in which this resource is defined. | +| bucketArn | string | The ARN of the bucket. | +| bucketDomainName | string | The IPv4 DNS name of the specified bucket. | +| bucketDualStackDomainName | string | The IPv6 DNS name of the specified bucket. | +| bucketName | string | The name of the bucket. | +| bucketRegionalDomainName | string | The regional domain name of the specified bucket. | +| bucketWebsiteDomainName | string | The Domain name of the static website. | +| bucketWebsiteUrl | string | The URL of the static website. | +| encryptionKey | @aws-cdk/aws-kms.IKey | Optional KMS encryption key associated with this bucket. | +| isWebsite | boolean | If this bucket has been configured for static website hosting. | +| policy | @aws-cdk/aws-s3.BucketPolicy | The resource policy associated with this bucket. | + +--- + +##### \`node\`Required + +\`\`\`typescript +public readonly node: ConstructNode; +\`\`\` + +- *Type:* @aws-cdk/core.ConstructNode + +The construct tree node associated with this construct. + +--- + +##### \`env\`Required + +\`\`\`typescript +public readonly env: ResourceEnvironment; +\`\`\` + +- *Type:* @aws-cdk/core.ResourceEnvironment + +The environment this resource belongs to. + +For resources that are created and managed by the CDK +(generally, those created by creating new class instances like Role, Bucket, etc.), +this is always the same as the environment of the stack they belong to; +however, for imported resources +(those obtained from static methods like fromRoleArn, fromBucketName, etc.), +that might be different than the stack they were imported into. + +--- + +##### \`stack\`Required + +\`\`\`typescript +public readonly stack: Stack; +\`\`\` + +- *Type:* @aws-cdk/core.Stack + +The stack in which this resource is defined. + +--- + +##### \`bucketArn\`Required + +\`\`\`typescript +public readonly bucketArn: string; +\`\`\` + +- *Type:* string + +The ARN of the bucket. + +--- + +##### \`bucketDomainName\`Required + +\`\`\`typescript +public readonly bucketDomainName: string; +\`\`\` + +- *Type:* string + +The IPv4 DNS name of the specified bucket. + +--- + +##### \`bucketDualStackDomainName\`Required + +\`\`\`typescript +public readonly bucketDualStackDomainName: string; +\`\`\` + +- *Type:* string + +The IPv6 DNS name of the specified bucket. + +--- + +##### \`bucketName\`Required + +\`\`\`typescript +public readonly bucketName: string; +\`\`\` + +- *Type:* string + +The name of the bucket. + +--- + +##### \`bucketRegionalDomainName\`Required + +\`\`\`typescript +public readonly bucketRegionalDomainName: string; +\`\`\` + +- *Type:* string + +The regional domain name of the specified bucket. + +--- + +##### \`bucketWebsiteDomainName\`Required + +\`\`\`typescript +public readonly bucketWebsiteDomainName: string; +\`\`\` + +- *Type:* string + +The Domain name of the static website. + +--- + +##### \`bucketWebsiteUrl\`Required + +\`\`\`typescript +public readonly bucketWebsiteUrl: string; +\`\`\` + +- *Type:* string + +The URL of the static website. + +--- + +##### \`encryptionKey\`Optional + +\`\`\`typescript +public readonly encryptionKey: IKey; +\`\`\` + +- *Type:* @aws-cdk/aws-kms.IKey + +Optional KMS encryption key associated with this bucket. + +--- + +##### \`isWebsite\`Optional + +\`\`\`typescript +public readonly isWebsite: boolean; +\`\`\` + +- *Type:* boolean + +If this bucket has been configured for static website hosting. + +--- + +##### \`policy\`Optional + +\`\`\`typescript +public readonly policy: BucketPolicy; +\`\`\` + +- *Type:* @aws-cdk/aws-s3.BucketPolicy + +The resource policy associated with this bucket. + +If \`autoCreatePolicy\` is true, a \`BucketPolicy\` will be created upon the +first call to addToResourcePolicy(s). + +--- + + + + + " `; diff --git a/test/cli.test.ts b/test/cli.test.ts index 2edd5000..b11ae36d 100644 --- a/test/cli.test.ts +++ b/test/cli.test.ts @@ -75,4 +75,30 @@ test('split-by-submodule creates submodule files next to output', () => { expect(rootMd).toContain('GreeterBucket'); expect(submoduleMd).toMatchSnapshot(); +}); + +test('specify languages and split-by-submodule creates submodule files next to output', () => { + + const libraryName = 'construct-library'; + const fixture = join(`${__dirname}/__fixtures__/libraries/${libraryName}`); + + // generate the documentation + execSync(`${process.execPath} ${cli} --output=docs/API.md --split-by-submodule -l typescript -l python`, { cwd: fixture }); + + // TypeScript + const rootTs = readFileSync(join(fixture, 'docs/API.typescript.md'), 'utf-8'); + const submoduleTs = readFileSync(join(fixture, 'docs/submod1.typescript.md'), 'utf-8'); + expect(rootTs).toMatchSnapshot('API.typescript.md'); + expect(rootTs).toContain('greetWithSalutation'); + expect(submoduleTs).toMatchSnapshot('submod1.typescript.md'); + expect(submoduleTs).toContain('goodbyeWithPhrase'); + + // Python + const rootPy = readFileSync(join(fixture, 'docs/API.python.md'), 'utf-8'); + const submodulePy = readFileSync(join(fixture, 'docs/submod1.python.md'), 'utf-8'); + expect(rootPy).toMatchSnapshot('API.python.md'); + expect(rootPy).toContain('greet_with_salutation'); + expect(submodulePy).toMatchSnapshot('submod1.python.md'); + expect(submodulePy).toContain('goodbye_with_phrase'); + }); \ No newline at end of file