From d2701cc18da9911f5f776abb3b470251f08c9bba Mon Sep 17 00:00:00 2001 From: zandercymatics <141044360+zandercymatics@users.noreply.github.com> Date: Fri, 1 Dec 2023 15:15:12 -0700 Subject: [PATCH] Add better comments --- .../generate_current_federal_report.py | 5 +- .../commands/generate_current_full_report.py | 5 +- src/registrar/utility/s3_bucket.py | 70 +++++++++++++++++-- 3 files changed, 73 insertions(+), 7 deletions(-) diff --git a/src/registrar/management/commands/generate_current_federal_report.py b/src/registrar/management/commands/generate_current_federal_report.py index 478265ca0..1a123bf5b 100644 --- a/src/registrar/management/commands/generate_current_federal_report.py +++ b/src/registrar/management/commands/generate_current_federal_report.py @@ -11,7 +11,10 @@ logger = logging.getLogger(__name__) class Command(BaseCommand): - help = "" + help = ( + "Generates and uploads a current-federal.csv file to our S3 bucket " + "which is based off of all existing federal Domains." + ) def add_arguments(self, parser): """Add our two filename arguments.""" diff --git a/src/registrar/management/commands/generate_current_full_report.py b/src/registrar/management/commands/generate_current_full_report.py index c41c697a1..7cf6fbb5a 100644 --- a/src/registrar/management/commands/generate_current_full_report.py +++ b/src/registrar/management/commands/generate_current_full_report.py @@ -11,7 +11,10 @@ logger = logging.getLogger(__name__) class Command(BaseCommand): - help = "" + help = ( + "Generates and uploads a current-full.csv file to our S3 bucket " + "which is based off of all existing Domains." + ) def add_arguments(self, parser): """Add our two filename arguments.""" diff --git a/src/registrar/utility/s3_bucket.py b/src/registrar/utility/s3_bucket.py index 162be37c9..f4e44b0b9 100644 --- a/src/registrar/utility/s3_bucket.py +++ b/src/registrar/utility/s3_bucket.py @@ -22,7 +22,17 @@ class S3ClientErrorCodes(IntEnum): class S3ClientError(RuntimeError): - """Local error for handling all failures with boto3.client""" + """ + Custom exception class for handling errors related to interactions with the S3 storage service via boto3.client. + + This class maps error codes to human-readable error messages. When an instance of S3ClientError is created, + an error code can be passed in to set the error message for that instance. + + Attributes: + _error_mapping: A dictionary mapping error codes to error messages. + code: The error code for a specific instance of S3ClientError. + message: The error message for a specific instance of S3ClientError, determined by the error code. + """ _error_mapping = { S3ClientErrorCodes.ACCESS_S3_CLIENT_ERROR: "Failed to establish a connection with the storage service.", @@ -44,7 +54,15 @@ class S3ClientError(RuntimeError): class S3ClientHelper: - """Helper class that simplifies S3 intialization""" + """ + A helper class for interacting with Amazon S3 via the boto3 client. + + This class simplifies the process of initializing the boto3 client, + uploading files to S3, and retrieving files from S3. + + Attributes: + boto_client: The boto3 client used to interact with S3. + """ def __init__(self): try: @@ -59,11 +77,35 @@ class S3ClientHelper: raise S3ClientError(code=S3ClientErrorCodes.ACCESS_S3_CLIENT_ERROR) from exc def get_bucket_name(self): - """Gets the name of our S3 Bucket""" + """ + Retrieves the name of the S3 bucket. + + This method returns the name of the S3 bucket as defined in the application's settings. + + Returns: + str: The name of the S3 bucket. + """ + return settings.AWS_S3_BUCKET_NAME def upload_file(self, file_path, file_name): - """Uploads a file to our S3 instance""" + """ + Uploads a file to the S3 bucket. + + This method attempts to upload a file to the S3 bucket using the boto3 client. + If an exception occurs during the upload process, it raises an S3ClientError with an UPLOAD_FILE_ERROR code. + + Args: + file_path (str): The path of the file to upload. + file_name (str): The name to give to the file in the S3 bucket. + + Returns: + dict: The response from the boto3 client's upload_file method. + + Raises: + S3ClientError: If the file cannot be uploaded to the S3 bucket. + """ + try: response = self.boto_client.upload_file(file_path, self.get_bucket_name(), file_name) except Exception as exc: @@ -71,7 +113,25 @@ class S3ClientHelper: return response def get_file(self, file_name, decode_to_utf=False): - """Gets a file to our S3 instance and returns the file content""" + """ + Retrieves a file from the S3 bucket and returns its content. + + This method attempts to retrieve a file from the S3 bucket using the boto3 client. + If the file is not found, it raises an S3ClientError with a FILE_NOT_FOUND_ERROR code. + For any other exceptions during the retrieval process, it raises an S3ClientError with a GET_FILE_ERROR code. + + Args: + file_name (str): The name of the file to retrieve from the S3 bucket. + decode_to_utf (bool, optional): If True, the file content is decoded from bytes to a UTF-8 string. + Defaults to False. + + Returns: + bytes or str: The content of the file. If decode_to_utf is True, this is a string. Otherwise, its bytes. + + Raises: + S3ClientError: If the file cannot be retrieved from the S3 bucket. + """ + try: response = self.boto_client.get_object(Bucket=self.get_bucket_name(), Key=file_name) except ClientError as exc: