PYTHON-4946 - Add GridFSBucket.rename_by_name (#2219)

Author: NoahStapp

doc/changelog.rst

@@ -9,6 +9,8 @@ PyMongo 4.12 brings a number of changes including:
 - Support for configuring DEK cache lifetime via the ``key_expiration_ms`` argument to
   :class:`~pymongo.encryption_options.AutoEncryptionOpts`.
 - Support for $lookup in CSFLE and QE supported on MongoDB 8.1+.
+- Added :meth:`gridfs.asynchronous.grid_file.AsyncGridFSBucket.rename_by_name` and :meth:`gridfs.grid_file.GridFSBucket.rename_by_name`
+  for more performant renaming of a file with multiple revisions.
 - Added :meth:`gridfs.asynchronous.grid_file.AsyncGridFSBucket.delete_by_name` and :meth:`gridfs.grid_file.GridFSBucket.delete_by_name`
   for more performant deletion of a file with multiple revisions.
 - AsyncMongoClient no longer performs DNS resolution for "mongodb+srv://" connection strings on creation.

gridfs/asynchronous/grid_file.py

@@ -1050,6 +1050,35 @@ async def rename(
                 "matched file_id %i" % (new_filename, file_id)
             )
 
+    async def rename_by_name(
+        self, filename: str, new_filename: str, session: Optional[AsyncClientSession] = None
+    ) -> None:
+        """Renames the stored file with the specified filename.
+
+        For example::
+
+          my_db = AsyncMongoClient().test
+          fs = AsyncGridFSBucket(my_db)
+          await fs.upload_from_stream("test_file", "data I want to store!")
+          await fs.rename_by_name("test_file", "new_test_name")
+
+        Raises :exc:`~gridfs.errors.NoFile` if no file with the given filename exists.
+
+        :param filename: The filename of the file to be renamed.
+        :param new_filename: The new name of the file.
+        :param session: a :class:`~pymongo.client_session.AsyncClientSession`
+
+        .. versionadded:: 4.12
+        """
+        _disallow_transactions(session)
+        result = await self._files.update_many(
+            {"filename": filename}, {"$set": {"filename": new_filename}}, session=session
+        )
+        if not result.matched_count:
+            raise NoFile(
+                f"no files could be renamed {new_filename!r} because none matched filename {filename!r}"
+            )
+
 
 class AsyncGridIn:
     """Class to write data to GridFS."""

gridfs/synchronous/grid_file.py

@@ -1042,6 +1042,35 @@ def rename(
                 "matched file_id %i" % (new_filename, file_id)
             )
 
+    def rename_by_name(
+        self, filename: str, new_filename: str, session: Optional[ClientSession] = None
+    ) -> None:
+        """Renames the stored file with the specified filename.
+
+        For example::
+
+          my_db = MongoClient().test
+          fs = GridFSBucket(my_db)
+          fs.upload_from_stream("test_file", "data I want to store!")
+          fs.rename_by_name("test_file", "new_test_name")
+
+        Raises :exc:`~gridfs.errors.NoFile` if no file with the given filename exists.
+
+        :param filename: The filename of the file to be renamed.
+        :param new_filename: The new name of the file.
+        :param session: a :class:`~pymongo.client_session.ClientSession`
+
+        .. versionadded:: 4.12
+        """
+        _disallow_transactions(session)
+        result = self._files.update_many(
+            {"filename": filename}, {"$set": {"filename": new_filename}}, session=session
+        )
+        if not result.matched_count:
+            raise NoFile(
+                f"no files could be renamed {new_filename!r} because none matched filename {filename!r}"
+            )
+
 
 class GridIn:
     """Class to write data to GridFS."""

test/asynchronous/test_gridfs_bucket.py

@@ -450,6 +450,19 @@ async def test_rename(self):
             b"testing", await (await self.fs.open_download_stream_by_name("second_name")).read()
         )
 
+    async def test_rename_by_name(self):
+        _id = await self.fs.upload_from_stream("first_name", b"testing")
+        self.assertEqual(
+            b"testing", await (await self.fs.open_download_stream_by_name("first_name")).read()
+        )
+
+        await self.fs.rename_by_name("first_name", "second_name")
+        with self.assertRaises(NoFile):
+            await self.fs.open_download_stream_by_name("first_name")
+        self.assertEqual(
+            b"testing", await (await self.fs.open_download_stream_by_name("second_name")).read()
+        )
+
     @patch("gridfs.asynchronous.grid_file._UPLOAD_BUFFER_SIZE", 5)
     async def test_abort(self):
         gin = self.fs.open_upload_stream("test_filename", chunk_size_bytes=5)

test/asynchronous/test_session.py

@@ -541,6 +541,7 @@ async def find(session=None):
             (bucket.download_to_stream_by_name, ["f", sio], {}),
             (find, [], {}),
             (bucket.rename, [1, "f2"], {}),
+            (bucket.rename_by_name, ["f2", "f3"], {}),
             # Delete both files so _test_ops can run these operations twice.
             (bucket.delete, [1], {}),
             (bucket.delete_by_name, ["f"], {}),

test/asynchronous/test_transactions.py

@@ -295,7 +295,14 @@ async def gridfs_open_upload_stream(*args, **kwargs):
                     "new-name",
                 ),
             ),
-            (bucket.delete_by_name, ("new-name",)),
+            (
+                bucket.rename_by_name,
+                (
+                    "new-name",
+                    "new-name2",
+                ),
+            ),
+            (bucket.delete_by_name, ("new-name2",)),
         ]
 
         async with client.start_session() as s, await s.start_transaction():