fix: allow recover to check the status of upload regardless of state (#…

…343)

* fix: allow recover to check the status of upload regardless of state

* fix docs lint

* more lint

Co-authored-by: Anthonios Partheniou <partheniou@google.com>

google/resumable_media/_upload.py

@@ -794,14 +794,8 @@ def _prepare_recover_request(self):
             The headers **do not** incorporate the ``_headers`` on the
             current instance.
 
-        Raises:
-            ValueError: If the current upload is not in an invalid state.
-
         .. _sans-I/O: https://sans-io.readthedocs.io/
         """
-        if not self.invalid:
-            raise ValueError("Upload is not in invalid state, no need to recover.")
-
         headers = {_helpers.CONTENT_RANGE_HEADER: "bytes */*"}
         return _PUT, self.resumable_url, None, headers
 

google/resumable_media/requests/upload.py

@@ -517,14 +517,15 @@ def retriable_request():
         )
 
     def recover(self, transport):
-        """Recover from a failure.
-
-        This method should be used when a :class:`ResumableUpload` is in an
-        :attr:`~ResumableUpload.invalid` state due to a request failure.
+        """Recover from a failure and check the status of the current upload.
 
         This will verify the progress with the server and make sure the
         current upload is in a valid state before :meth:`transmit_next_chunk`
-        can be used again.
+        can be used again. See https://cloud.google.com/storage/docs/performing-resumable-uploads#status-check
+        for more information.
+
+        This method can be used when a :class:`ResumableUpload` is in an
+        :attr:`~ResumableUpload.invalid` state due to a request failure.
 
         Args:
             transport (~requests.Session): A ``requests`` object which can

tests/unit/test__upload.py

@@ -951,8 +951,13 @@ def test__prepare_recover_request_not_invalid(self):
         upload = _upload.ResumableUpload(RESUMABLE_URL, ONE_MB)
         assert not upload.invalid
 
-        with pytest.raises(ValueError):
-            upload._prepare_recover_request()
+        method, url, payload, headers = upload._prepare_recover_request()
+        assert method == "PUT"
+        assert url == upload.resumable_url
+        assert payload is None
+        assert headers == {"content-range": "bytes */*"}
+        # Make sure headers are untouched.
+        assert upload._headers == {}
 
     def test__prepare_recover_request(self):
         upload = _upload.ResumableUpload(RESUMABLE_URL, ONE_MB)