Add .GetRevisions() option (#297)

* Add .GetRevisions() option

* Reformat GetRevisions() comments

---------

Co-authored-by: Ivan Shcheklein <shcheklein@gmail.com>

docs/filemanagement.rst

@@ -192,6 +192,23 @@ a list of `GoogleDriveFile`_ instances.
     # Get list of files that match against the query
     files = drive.ListFile(query).GetList()
 
+List revisions
+________________
+
+Revisions can be fetched using the ``GetRevisions()`` function of a
+``GoogleDriveFile``, and can be used like so:
+
+.. code-block:: python
+
+    # Create a new file
+    file1 = drive.CreateFile()
+    # Fetch revisions.
+    revisions = file1.GetRevisions()
+    print(revisions)
+
+Not all files objects have revisions. If GetRevisions is called on a
+file object that does not have revisions, an exception will be raised.
+
 Upload and update file content
 ------------------------------
 

pydrive2/files.py

@@ -650,6 +650,35 @@ def DeletePermission(self, permission_id):
         """
         return self._DeletePermission(permission_id)
 
+    @LoadAuth
+    def GetRevisions(self):
+        """Get file's or shared drive's revisions.
+
+        For files in a shared drive, at most 100 results will be returned.
+        It doesn't paginate and collect all results.
+
+        :return: A list of the revision objects.
+        :rtype: object[]
+        """
+        file_id = self.metadata.get("id") or self.get("id")
+
+        # We can't do FetchMetada call (which would nicely update
+        # local metada cache, etc) here since it  doesn't return
+        # revisions for the team drive use case.
+        revisions = (
+            self.auth.service.revisions()
+            .list(
+                fileId=file_id,
+            )
+            .execute(http=self.http)
+        ).get("items")
+
+        if revisions:
+            self["revisions"] = revisions
+            self.metadata["revisions"] = revisions
+
+        return revisions
+
     def _WrapRequest(self, request):
         """Replaces request.http with self.http.
 

pydrive2/test/test_file.py

@@ -598,6 +598,19 @@ def test_Files_Delete_Permission_Invalid(self):
 
         pydrive_retry(file1.Delete)
 
+    def test_Files_Get_Revisions(self):
+        drive = GoogleDrive(self.ga)
+        file1 = drive.CreateFile()
+        pydrive_retry(file1.Upload)
+
+        self.assertFalse("revisions" in file1)
+
+        revisions = pydrive_retry(file1.GetRevisions)
+        self.assertTrue(revisions is not None)
+        self.assertTrue("revisions" in file1)
+
+        pydrive_retry(file1.Delete)
+
     def test_ApiRequestError_HttpError_Propagation(self):
         file = GoogleDrive(self.ga).CreateFile()
         pydrive_retry(file.Upload)