lcdp-boto3-utils 1.6.0__tar.gz

lcdp_boto3_utils-1.6.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: lcdp-boto3-utils
+Version: 1.6.0
+Summary: Boto3 Utils
+Author: Le Comptoir Des Pharmacies
+Author-email: webmaster@lecomptoirdespharmacies.fr
+Requires-Python: >=3.8
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: boto3 (>=1.26.83,<2.0.0)

lcdp_boto3_utils-1.6.0/lcdp_boto3_utils/exceptions/S3TransferException.py

@@ -0,0 +1,3 @@
+# Raise this when upload/download failed on AWS S3
+class S3TransferException(Exception):
+    pass

lcdp_boto3_utils-1.6.0/lcdp_boto3_utils/s3_manager.py

@@ -0,0 +1,129 @@
+import json
+from typing import Any
+
+import boto3
+from botocore.exceptions import ClientError
+
+from .exceptions.S3TransferException import S3TransferException
+
+
+class S3Manager:
+    """Service for uploading, downloading and deleting payloads in an S3 bucket."""
+
+    def __init__(self, bucket_name: str, region: str):
+        """
+        Initialize an S3Manager for a specific bucket and region.
+
+        Args:
+            bucket_name: Name of the S3 bucket where payloads are stored.
+            region: AWS region used to configure the underlying S3 client.
+        """
+        self.bucket_name = bucket_name
+        self.s3_client = boto3.client("s3", region_name=region)
+
+    def _ensure_json_bytes(self, payload: Any) -> bytes:
+        """
+        Normalize a payload to JSON-encoded bytes.
+
+        If the payload is already bytes, it is returned as-is.
+        If it is a string, it is encoded as UTF-8.
+        Otherwise, it is serialized to JSON then encoded as UTF-8.
+
+        Args:
+            payload: Arbitrary payload (dict, list, str, bytes, etc.) to serialize.
+
+        Returns:
+            UTF-8 encoded JSON representation of the payload.
+        """
+        if isinstance(payload, bytes):
+            return payload
+        if isinstance(payload, str):
+            return payload.encode("utf-8")
+        return json.dumps(payload, ensure_ascii=False, default=str).encode("utf-8")
+
+    def upload_payload(self, payload: Any, key: str) -> bool:
+        """
+        Upload a payload to S3 and compute its checksum.
+
+        The payload is first converted to JSON bytes, then stored in the
+        configured bucket under the given key and `application/json` content type.[web:51][web:54]
+
+        Args:
+            payload: Content to upload (dict, list, str, bytes, etc.).
+            key: Object key to use when storing the payload in S3.
+
+        Raises:
+            S3TransferException: If serialization or S3 upload fails.
+
+        Returns:
+            S3Result containing the S3 object key and the computed checksum.
+        """
+        try:
+            body = self._ensure_json_bytes(payload)
+        except Exception as e:
+            raise S3TransferException(f"Failed to serialize {key}", e)
+
+        try:
+            self.s3_client.put_object(
+                Bucket=self.bucket_name,
+                Key=key,
+                Body=body,
+                ContentType="application/json",
+            )
+        except ClientError as e:
+            raise S3TransferException(f"S3 upload failed for {key}", e)
+        except Exception as e:
+            raise S3TransferException(f"Unexpected error uploading {key}", e)
+
+        return True
+
+    def download_payload(self, bucket_name: str, s3_key: str) -> str:
+        """
+        Download a payload from S3 and return it as a UTF-8 string.
+
+        Args:
+            bucket_name: Name of the S3 bucket where payload is stored.
+            s3_key: Object key of the payload to download.
+
+        Raises:
+            S3TransferException: If the key is missing, the object does not exist,
+                or the download/parsing process fails.
+
+        Returns:
+            The payload content decoded as a UTF-8 string.
+        """
+        if not s3_key:
+            raise S3TransferException("s3_key is mandatory")
+
+        try:
+            response = self.s3_client.get_object(Bucket=bucket_name, Key=s3_key)
+            body = response["Body"].read()
+            return body.decode("utf-8")
+        except ClientError as e:
+            raise S3TransferException(f"Failed to download {s3_key} from S3", e)
+        except UnicodeDecodeError as e:
+            raise S3TransferException(f"Failed to decode {s3_key} body as utf-8", e)
+        except Exception as e:
+            raise S3TransferException(f"Unexpected error downloading {s3_key}", e)
+
+    def delete_payload(self, bucket_name: str, s3_key: str) -> bool:
+        """
+        Delete a payload from S3.
+
+        Args:
+            bucket_name: Name of the S3 bucket where payload is stored.
+            s3_key: Object key of the payload to delete. If empty or None,
+                the method performs no action.
+        """
+
+        if not s3_key:
+            raise S3TransferException("s3_key is mandatory")
+
+        try:
+            self.s3_client.delete_object(
+                Bucket=bucket_name,
+                Key=s3_key
+            )
+            return True
+        except ClientError:
+            return False

lcdp_boto3_utils-1.6.0/pyproject.toml

@@ -0,0 +1,23 @@
+[tool.poetry]
+name = "lcdp-boto3-utils"
+# https://github.com/python-poetry/poetry/issues/1208
+version = "1.6.0"
+description = "Boto3 Utils"
+authors = ["Le Comptoir Des Pharmacies <webmaster@lecomptoirdespharmacies.fr>"]
+
+[tool.poetry-dynamic-versioning]
+enable = false
+vcs = "git"
+
+[tool.poetry.requires-plugins]
+poetry-dynamic-versioning = { version = ">=1.0.0,<2.0.0", extras = ["plugin"] }
+
+[tool.poetry.dependencies]
+python = ">=3.8"
+boto3 = "^1.26.83"
+
+[tool.poetry.dev-dependencies]
+
+[build-system]
+requires = ["poetry-core>=1.0.0", "poetry-dynamic-versioning>=1.0.0,<2.0.0"]
+build-backend = "poetry_dynamic_versioning.backend"