refactor: legal_hold implementation of objects

fixes various method calls for legal_hold and ensures that the state of the object
is updated based on if the legal hold succeeds

Author: devraj

src/labs/models/s3.py

@@ -4,12 +4,14 @@
 """
 from uuid import uuid4
 from datetime import timedelta
-from typing import TYPE_CHECKING, Union
+from typing import Union
 
 from sqlalchemy import event
-from sqlalchemy.orm import relationship, mapped_column, Mapped
+from sqlalchemy.orm import relationship,\
+    mapped_column, Mapped
 
-from .utils import DateTimeMixin, IdentifierMixin, ModelCRUDMixin, fk_user_uuid
+from .utils import DateTimeMixin, IdentifierMixin,\
+    ModelCRUDMixin, fk_user_uuid
 
 from ..db import Base
 from ..utils import minio_client
@@ -60,14 +62,19 @@ class S3FileMetadata(
 
     mime_type: Mapped[str]
 
+    # Is set to True if the object is deemed to be logically deleted
+    # see other part of the documentation for logical and physical deletion policy
     deleted: Mapped[bool] = mapped_column(
         default=False
     )
 
+    # Is set to True if the object is currently in held in a legal hold
     legal_hold: Mapped[bool] = mapped_column(
         default=False
     )
 
+    # Is set of True once the application is able to validate
+    # the presence of the object on the store
     is_valid: Mapped[bool] = mapped_column(
         default=False
     )
@@ -81,7 +88,10 @@ class S3FileMetadata(
 
     @property
     def presigned_download_url(self) -> Union[str, None]:
-        """
+        """ Provides a presigned download url for the object in the store
+
+        If there is an issue then you will receive None, the application should not proceed
+        with the download if this is the case.
         """
         try:
             return minio_client.presigned_get_object(
@@ -100,8 +110,16 @@ def presigned_download_url(self) -> Union[str, None]:
 
     @property
     def presigned_upload_url(self) -> Union[str, None]:
-        """
-        
+        """ Use this property to get a URL to create or update the object
+
+        Note that if versioning is not turned on for the object store then this will
+        replace the contents of the object on the store.
+
+        Once created you should send this to the browser to action the upload, the
+        URL is signed for particular amount of time and will expire post that.
+
+        If you receive None then there is an issue with the object store and you
+        should not proceed with the upload.
         """
         try:
             url = minio_client.presigned_put_object(
@@ -116,30 +134,46 @@ def presigned_upload_url(self) -> Union[str, None]:
             return None
 
     def enable_legal_hold(self) -> bool:
+        """ The Object Lock legal hold operation enables you to place a legal hold 
+        on an object version. Like setting a retention period, a legal hold prevents an 
+        object version from being overwritten or deleted. 
+
+        This is a method which is used to enable a legal hold on the object, the
+        object must exists in the store and must not already have a legal hold.
+        """
         try:
-            minio_client.put_object_legal_hold(
+            minio_client.enable_object_legal_hold(
                 config.S3_BUCKET_NAME,
                 self.s3_key,
-                True
             )
+            self.legal_hold = True
             return True
         except Exception:
+            self.legal_hold = False
             return False
 
     def disable_legal_hold(self) -> bool:
+        """ Disables the legal hold if one is placed on the object.
+
+        Note that this method will return a boolean to state the success of the
+        operation. This is not the legal hold status of the object.        
+        """
         try:
-            minio_client.put_object_legal_hold(
+            minio_client.disable_object_legal_hold(
                 config.S3_BUCKET_NAME,
                 self.s3_key,
-                False
             )
+
+            self.legal_hold = False
+
             return True
         except Exception:
+            self.legal_hold = True
             return False
 
 
 @event.listens_for(S3FileMetadata, 'init')
-def receive_init(target, args, kwargs):
+def assigned_s3_key(target, args, kwargs):
     """ Assigns a UUID based on the UUID4 standard as the key for the file upload
 
     When the application assigns a new S3FileMetadata object, it will be 
@@ -149,3 +183,4 @@ def receive_init(target, args, kwargs):
     """
     target.s3_key = uuid4().hex
     target.prefix = uuid4().hex
+