Moved to new folder

Author: meyertst-aws

.doc_gen/metadata/s3-directory-buckets_metadata.yaml

@@ -413,6 +413,17 @@ s3-directory-buckets_Scenario_ExpressBasics:
               snippet_tags:
                 - php.example_code.s3.ExpressBasics
                 - php.example_code.s3.service.S3Service
+    Python:
+      versions:
+        - sdk_version: 3
+          github: python/example_code/s3-directory-buckets/
+          sdkguide:
+          excerpts:
+            - description: >
+               Run a scenario demonstrating the basics of &S3; directory buckets
+               and S3 Express One Zone.
+              snippet_tags:
+                - python.example_code.s3.s3_express_basics
   services:
     s3-directory-buckets: {CreateBucket, CopyObject, GetObject, PutObject, ListObjects, DeleteObject, DeleteBucket}
 

python/example_code/s3-directory-buckets/README.md

@@ -0,0 +1,109 @@
+# S3 Directory Buckets code examples for the SDK for Python
+
+## Overview
+
+Shows how to use the AWS SDK for Python (Boto3) to work with Amazon S3 Directory Buckets.
+
+<!--custom.overview.start-->
+<!--custom.overview.end-->
+
+_S3 Directory Buckets are designed to store data within a single AWS Zone. Directory buckets organize data hierarchically into directories, providing a structure similar to a file system._
+
+## ⚠ Important
+
+* Running this code might result in charges to your AWS account. For more details, see [AWS Pricing](https://aws.amazon.com/pricing/) and [Free Tier](https://aws.amazon.com/free/).
+* Running the tests might result in charges to your AWS account.
+* We recommend that you grant your code least privilege. At most, grant only the minimum permissions required to perform the task. For more information, see [Grant least privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege).
+* This code is not tested in every AWS Region. For more information, see [AWS Regional Services](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services).
+
+<!--custom.important.start-->
+<!--custom.important.end-->
+
+## Code examples
+
+### Prerequisites
+
+For prerequisites, see the [README](../../README.md#Prerequisites) in the `python` folder.
+
+Install the packages required by these examples by running the following in a virtual environment:
+
+```
+python -m pip install -r requirements.txt
+```
+
+<!--custom.prerequisites.start-->
+<!--custom.prerequisites.end-->
+
+### Basics
+
+Code examples that show you how to perform the essential operations within a service.
+
+- [Learn the basics](s3_express_getting_started.py)
+
+
+<!--custom.examples.start-->
+<!--custom.examples.end-->
+
+## Run the examples
+
+### Instructions
+
+
+<!--custom.instructions.start-->
+<!--custom.instructions.end-->
+
+
+#### Learn the basics
+
+This example shows you how to do the following:
+
+- Set up a VPC and VPC Endpoint.
+- Set up the Policies, Roles, and User to work with S3 directory buckets and the S3 Express One Zone storage class.
+- Create two S3 Clients.
+- Create two buckets.
+- Create an object and copy it over.
+- Demonstrate performance difference.
+- Populate the buckets to show the lexicographical difference.
+- Prompt the user to see if they want to clean up the resources.
+
+<!--custom.basic_prereqs.s3-directory-buckets_Scenario_ExpressBasics.start-->
+<!--custom.basic_prereqs.s3-directory-buckets_Scenario_ExpressBasics.end-->
+
+Start the example by running the following at a command prompt:
+
+```
+python s3_express_getting_started.py
+```
+
+
+<!--custom.basics.s3-directory-buckets_Scenario_ExpressBasics.start-->
+<!--custom.basics.s3-directory-buckets_Scenario_ExpressBasics.end-->
+
+
+### Tests
+
+⚠ Running tests might result in charges to your AWS account.
+
+
+To find instructions for running these tests, see the [README](../../README.md#Tests)
+in the `python` folder.
+
+
+
+<!--custom.tests.start-->
+<!--custom.tests.end-->
+
+## Additional resources
+
+- [S3 Directory Buckets User Guide](https://docs.aws.amazon.com/AmazonS3/latest/userguide/directory-buckets-overview.html)
+- [S3 Directory Buckets API Reference](https://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html)
+- [SDK for Python S3 Directory Buckets reference](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3-directory-buckets.html)
+
+<!--custom.resources.start-->
+<!--custom.resources.end-->
+
+---
+
+Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+SPDX-License-Identifier: Apache-2.0

python/example_code/s3-directory-buckets/requirements.txt

@@ -0,0 +1,3 @@
+boto3>=1.35.49
+pytest>=7.2.1
+requests>=2.28.2

python/example_code/s3/s3_basics/s3_express_getting_started.py renamed to python/example_code/s3-directory-buckets/s3_express_getting_started.py

@@ -6,6 +6,7 @@
 import os
 import uuid
 import time
+import argparse
 from boto3.resources.base import ServiceResource
 from boto3 import resource
 from boto3 import client
@@ -16,10 +17,9 @@
 script_dir = os.path.dirname(os.path.abspath(__file__))
 
 # Add relative path to include demo_tools in this code example without need for setup.
-sys.path.append(os.path.join(script_dir, "../../.."))
+sys.path.append(os.path.join(script_dir, "../.."))
 import demo_tools.question as q
 
-no_art = False  # 'no_art' suppresses 'art' to improve accessibility.
 logger = logging.getLogger(__name__)
 
 
@@ -48,12 +48,11 @@ def __init__(
         cloud_formation_resource: ServiceResource,
         ec2_client: client,
         iam_client: client,
-        region: str = None,
     ):
         self.cloud_formation_resource = cloud_formation_resource
         self.ec2_client = ec2_client
         self.iam_client = iam_client
-        self.region = region if region else ec2_client.meta.region_name
+        self.region = ec2_client.meta.region_name
         self.stack = None
         self.vpc_id = None
         self.vpc_endpoint_id = None
@@ -93,7 +92,7 @@ def s3_express_scenario(self):
         self.demonstrate_performance(bucket_object)
 
         # Populate the buckets to show the lexicographical difference between regular and express buckets.
-        self.show_lexigraphical_differences(bucket_object)
+        self.show_lexicographical_differences(bucket_object)
 
         print("")
         print("That's it for our tour of the basic operations for S3 Express One Zone.")
@@ -104,7 +103,11 @@ def s3_express_scenario(self):
         ):
             self.cleanup()
 
-    def create_vpc_and_users(self):
+    def create_vpc_and_users(self) -> None:
+        """
+        Optionally create a VPC.
+        Create two IAM users, one with S3 Express One Zone permissions and one without.
+        """
         # Configure a gateway VPC endpoint. This is the recommended method to allow S3 Express One Zone traffic without
         # the need to pass through an internet gateway or NAT device.
         print("")
@@ -148,7 +151,14 @@ def create_vpc_and_users(self):
             raise ValueError(error_string)
         return express_user_name, regular_user_name
 
-    def setup_clients_and_buckets(self, express_user_name, regular_user_name):
+    def setup_clients_and_buckets(
+        self, express_user_name: str, regular_user_name: str
+    ) -> None:
+        """
+        Set up two S3 clients, one regular and one express, and two buckets, one regular and one express.
+        :param express_user_name: The name of the user with S3 Express permissions.
+        :param regular_user_name: The name of the user with regular S3 permissions.
+        """
         regular_credentials = self.create_access_key(regular_user_name)
         express_credentials = self.create_access_key(express_user_name)
         # 3. Create an additional client using the credentials with S3 Express permissions.
@@ -220,7 +230,10 @@ def setup_clients_and_buckets(self, express_user_name, regular_user_name):
         print("Great! Both buckets were created.")
         press_enter_to_continue()
 
-    def create_session_and_add_objects(self):
+    def create_session_and_add_objects(self) -> None:
+        """
+        Create a session for the express S3 client and add objects to the buckets.
+        """
         print("")
         print("5. Create an object and copy it over.")
         print(
@@ -260,7 +273,11 @@ def create_session_and_add_objects(self):
         press_enter_to_continue()
         return bucket_object
 
-    def demonstrate_performance(self, bucket_object):
+    def demonstrate_performance(self, bucket_object: str) -> None:
+        """
+        Demonstrate performance differences between regular and Directory buckets.
+        :param bucket_object: The name of the object to download from each bucket.
+        """
         print("")
         print("6. Demonstrate performance difference.")
         print(
@@ -308,7 +325,12 @@ def demonstrate_performance(self, bucket_object):
             )
         press_enter_to_continue()
 
-    def show_lexigraphical_differences(self, bucket_object):
+    def show_lexicographical_differences(self, bucket_object: str) -> None:
+        """
+        Show the lexicographical difference between Directory buckets and regular buckets.
+        This is done by creating a few objects in each bucket and listing them to show the difference.
+        :param bucket_object: The object to use for the listing operations.
+        """
         print("")
         print("7. Populate the buckets to show the lexicographical difference.")
         print(
@@ -376,7 +398,7 @@ def show_lexigraphical_differences(self, bucket_object):
         )
         press_enter_to_continue()
 
-    def cleanup(self):
+    def cleanup(self) -> None:
         """
         Delete resources created by this scenario.
         """
@@ -728,7 +750,7 @@ def setup_vpc(self):
             )
             raise
 
-    def tear_done_vpc(self):
+    def tear_done_vpc(self) -> None:
         if self.vpc_endpoint_id is not None:
             try:
                 self.ec2_client.delete_vpc_endpoints(
@@ -753,16 +775,22 @@ def tear_done_vpc(self):
                     self.vpc_id,
                     client_error.response["Error"]["Message"],
                 )
-
+# snippet-end:[python.example_code.s3.s3_express_basics]
 
 if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Run S3 Express getting started scenario."
+    )
+    parser.add_argument(
+        "--no-art",
+        action="store_true",
+        help="accessibility setting that suppresses art in the console output.",
+    )
+    args = parser.parse_args()
+    no_art = args.no_art
+
     s3_express_scenario = None
-    my_s3_client = client("s3")
-    # delete all directory buckets
-    bucket_list = my_s3_client.list_directory_buckets()
-    for bucket in bucket_list["Buckets"]:
-        print(f"Deleting bucket {bucket['Name']}")
-        S3ExpressScenario.delete_bucket_and_objects(my_s3_client, bucket["Name"])
+
     try:
         a_cloud_formation_resource = resource("cloudformation")
         an_ec2_client = client("ec2")
@@ -784,4 +812,4 @@ def tear_done_vpc(self):
         if s3_express_scenario is not None:
             s3_express_scenario.cleanup()
 
-# snippet-end:[python.example_code.s3.s3_express_basics]
+

python/example_code/s3/s3_basics/s3_express_template.yaml renamed to python/example_code/s3-directory-buckets/s3_express_template.yaml

@@ -0,0 +1,82 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Contains common test fixtures used to run unit tests.
+"""
+
+import sys
+
+import boto3
+import pytest
+import os
+
+
+script_dir = os.path.dirname(os.path.abspath(__file__))
+
+# Add relative path to include SchedulerWrapper.
+sys.path.append(script_dir)
+sys.path.append(os.path.dirname(script_dir))
+import s3_express_getting_started
+
+# Add relative path to include demo_tools in this code example without need for setup.
+sys.path.append(os.path.join(script_dir, "../.."))
+
+from test_tools.fixtures.common import *
+
+
+class ScenarioData:
+    def __init__(
+        self,
+        ec2_client,
+            s3_client,
+            iam_client,
+        cloud_formation_resource,
+            ec2_stubber,
+            s3_stubber,
+            iam_stubber,
+
+        cloud_formation_stubber,
+            region,
+    ):
+        self.ec2_client = ec2_client
+        self.s3_client = s3_client
+        self.iam_client = iam_client
+        self.cloud_formation_resource = cloud_formation_resource
+        self.ec2_stubber = ec2_stubber
+        self.s3_stubber = s3_stubber
+        self.iam_stubber = iam_stubber
+        self.cloud_formation_stubber = cloud_formation_stubber
+        self.region = region
+        self.scenario = s3_express_getting_started.S3ExpressScenario(
+            cloud_formation_resource=self.cloud_formation_resource,
+            ec2_client = self.ec2_client,
+            iam_client = self.iam_client,
+        )
+        s3_express_getting_started.use_press_enter_to_continue = False
+
+
+@pytest.fixture
+def scenario_data(make_stubber):
+    cloud_formation_resource = boto3.resource("cloudformation")
+    cloud_formation_stubber = make_stubber(cloud_formation_resource.meta.client)
+    region = "us-east-1"
+    ec2_client = boto3.client("ec2", region_name=region)
+    ec2_stubber = make_stubber(ec2_client)
+
+    iam_client = boto3.client("iam")
+    iam_stubber = make_stubber(iam_client)
+
+    s3_client = boto3.client("s3")
+    s3_stubber = make_stubber(s3_client)
+    return ScenarioData(
+        ec2_client = ec2_client,
+        s3_client = s3_client,
+        iam_client = iam_client,
+        cloud_formation_resource = cloud_formation_resource,
+        ec2_stubber = ec2_stubber,
+        s3_stubber = s3_stubber,
+        iam_stubber = iam_stubber,
+        cloud_formation_stubber = cloud_formation_stubber,
+        region = region
+    )