PYTHON-4946 - GridFS spec: Add performant 'rename all revisions by filename' feature - rename_by_name

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 file revisions.
 
 Issues Resolved
 ...............

gridfs/asynchronous/grid_file.py

@@ -1021,6 +1021,36 @@ 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 file_id 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} because none matched filename {filename}"
+            )
+
 
 class AsyncGridIn:
     """Class to write data to GridFS."""

gridfs/synchronous/grid_file.py

@@ -1015,6 +1015,36 @@ 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 file_id 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} because none matched filename {filename}"
+            )
+
 
 class GridIn:
     """Class to write data to GridFS."""

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
@@ -630,6 +630,9 @@ def process_error(self, exception, spec):
                 self.assertNotIsInstance(error, NotPrimaryError)
             elif isinstance(error, (InvalidOperation, ConfigurationError, EncryptionError)):
                 pass
+            # gridfs NoFile errors are considered client errors.
+            elif isinstance(error, NoFile):
+                pass
             else:
                 self.assertNotIsInstance(error, PyMongoError)