Add unhide_file method to Bucket (#505)

* add bucket unhide_file

* add changelog.d item

* fix unhide_file docs/type hint and rename unexpected file version action

* add details to UnexpectedFileVersionAction

* fix typo

* add fullstop to changelog entry

---------

Co-authored-by: didil <1284255+didil@users.noreply.github.com>

b2sdk/_internal/bucket.py

@@ -22,9 +22,12 @@
 from .exception import (
     BucketIdNotFound,
     CopySourceTooBig,
+    FileDeleted,
+    FileNotHidden,
     FileNotPresent,
     FileOrBucketNotFound,
     UnexpectedCloudBehaviour,
+    UnexpectedFileVersionAction,
     UnrecognizedBucketType,
 )
 from .file_lock import (
@@ -34,7 +37,7 @@
     FileRetentionSetting,
     LegalHold,
 )
-from .file_version import DownloadVersion, FileVersion
+from .file_version import DownloadVersion, FileIdAndName, FileVersion
 from .filter import Filter, FilterMatcher
 from .http_constants import LIST_FILE_NAMES_MAX_LIMIT
 from .progress import AbstractProgressListener, DoNothingProgressListener
@@ -1351,6 +1354,27 @@ def hide_file(self, file_name):
         response = self.api.session.hide_file(self.id_, file_name)
         return self.api.file_version_factory.from_api_response(response)
 
+    def unhide_file(self, file_name: str, bypass_governance: bool = False) -> FileIdAndName:
+        """
+        Unhide a file by deleting the "hide marker".
+        """
+
+        # get the latest file version
+        file_versions = self.list_file_versions(file_name=file_name, fetch_count=1)
+        latest_file_version = next(file_versions, None)
+        if latest_file_version is None:
+            raise FileNotPresent(bucket_name=self.name, file_id_or_name=file_name)
+
+        action = latest_file_version.action
+        if action == "upload":
+            raise FileNotHidden(file_name)
+        elif action == "delete":
+            raise FileDeleted(file_name)
+        elif action != "hide":
+            raise UnexpectedFileVersionAction(action)
+
+        return self.delete_file_version(latest_file_version.id_, file_name, bypass_governance)
+
     def copy(
         self,
         file_id,

b2sdk/_internal/exception.py

@@ -263,6 +263,18 @@ class FileAlreadyHidden(B2SimpleError):
     pass
 
 
+class FileNotHidden(B2SimpleError):
+    prefix = 'File not hidden'
+
+
+class FileDeleted(B2SimpleError):
+    prefix = 'File deleted'
+
+
+class UnexpectedFileVersionAction(B2SimpleError):
+    prefix = 'Unexpected file version action returned by the server'
+
+
 class FileNameNotAllowed(NotAllowedByAppKeyError):
     pass
 

changelog.d/+bucket_unhide_file.added.md

@@ -0,0 +1 @@
+Add unhide_file method to Bucket.

test/unit/bucket/test_bucket.py

@@ -624,6 +624,14 @@ def test_hidden_file(self):
         expected = [('hello.txt', 0, 'hide', None), ('hello.txt', 11, 'upload', None)]
         self.assertBucketContents(expected, '', show_versions=True)
 
+    def test_unhidden_file(self):
+        data = b'hello world'
+        self.bucket.upload_bytes(data, 'hello.txt')
+        self.bucket.hide_file('hello.txt')
+        self.bucket.unhide_file('hello.txt')
+        expected = [('hello.txt', 11, 'upload', None)]
+        self.assertBucketContents(expected, '', show_versions=True)
+
     def test_delete_file_version(self):
         data = b'hello world'