PYTHON-4946 - Add GridFSBucket.rename_by_name

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 file revisions.
 - AsyncMongoClient no longer performs DNS resolution for "mongodb+srv://" connection strings on creation.
   To avoid blocking the asyncio loop, the resolution is now deferred until the client is first connected.
 - Added index hinting support to the

gridfs/asynchronous/grid_file.py

@@ -1021,6 +1021,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

@@ -1015,6 +1015,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

@@ -439,6 +439,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/unified_format.py

@@ -66,7 +66,7 @@
 from bson import SON, json_util
 from bson.codec_options import DEFAULT_CODEC_OPTIONS
 from bson.objectid import ObjectId
-from gridfs import AsyncGridFSBucket, GridOut
+from gridfs import AsyncGridFSBucket, GridOut, NoFile
 from pymongo import ASCENDING, AsyncMongoClient, CursorType, _csot
 from pymongo.asynchronous.change_stream import AsyncChangeStream
 from pymongo.asynchronous.client_session import AsyncClientSession, TransactionOptions, _TxnState
@@ -632,7 +632,7 @@ def process_error(self, exception, spec):
             # Connection errors are considered client errors.
             if isinstance(error, ConnectionFailure):
                 self.assertNotIsInstance(error, NotPrimaryError)
-            elif isinstance(error, (InvalidOperation, ConfigurationError, EncryptionError)):
+            elif isinstance(error, (InvalidOperation, ConfigurationError, EncryptionError, NoFile)):
                 pass
             else:
                 self.assertNotIsInstance(error, PyMongoError)