Class GridFSBucket

gridfs/synchronous/grid_file.py:459–1072

An instance of GridFS on top of a single Database.

class GridFSBucket:
    """An instance of GridFS on top of a single Database."""

    def __init__(
        self,
        db: Database[Any],
        bucket_name: str = "fs",
        chunk_size_bytes: int = DEFAULT_CHUNK_SIZE,
        write_concern: Optional[WriteConcern] = None,
        read_preference: Optional[_ServerMode] = None,
    ) -> None:
        """Create a new instance of :class:`GridFSBucket`.

        Raises :exc:`TypeError` if `database` is not an instance of
        :class:`~pymongo.database.Database`.

        Raises :exc:`~pymongo.errors.ConfigurationError` if `write_concern`
        is not acknowledged.

        :param database: database to use.
        :param bucket_name: The name of the bucket. Defaults to 'fs'.
        :param chunk_size_bytes: The chunk size in bytes. Defaults
            to 255KB.
        :param write_concern: The
            :class:`~pymongo.write_concern.WriteConcern` to use. If ``None``
            (the default) db.write_concern is used.
        :param read_preference: The read preference to use. If
            ``None`` (the default) db.read_preference is used.

        .. versionchanged:: 4.0
           Removed the `disable_md5` parameter. See
           :ref:`removed-gridfs-checksum` for details.

        .. versionchanged:: 3.11
           Running a GridFSBucket operation in a transaction now always raises
           an error. GridFSBucket does not support multi-document transactions.

        .. versionchanged:: 3.7
           Added the `disable_md5` parameter.

        .. versionadded:: 3.1

        .. seealso:: The MongoDB documentation on `gridfs <https://dochub.mongodb.org/core/gridfs>`_.
        """
        if not isinstance(db, Database):
            raise TypeError(f"database must be an instance of Database, not {type(db)}")

        db = _clear_entity_type_registry(db)

        wtc = write_concern if write_concern is not None else db.write_concern
        if not wtc.acknowledged:
            raise ConfigurationError("write concern must be acknowledged")

        self._bucket_name = bucket_name
        self._collection = db[bucket_name]
        self._chunks: Collection[Any] = self._collection.chunks.with_options(
            write_concern=write_concern, read_preference=read_preference
        )