Class GridOut

gridfs/synchronous/grid_file.py:1441–1807

Class to read data out of GridFS.

class GridOut(GRIDOUT_BASE_CLASS):  # type: ignore

    """Class to read data out of GridFS."""

    def __init__(
        self,
        root_collection: Collection[Any],
        file_id: Optional[int] = None,
        file_document: Optional[Any] = None,
        session: Optional[ClientSession] = None,
    ) -> None:
        """Read a file from GridFS

        Application developers should generally not need to
        instantiate this class directly - instead see the methods
        provided by :class:`~gridfs.GridFS`.

        Either `file_id` or `file_document` must be specified,
        `file_document` will be given priority if present. Raises
        :class:`TypeError` if `root_collection` is not an instance of
        :class:`~pymongo.collection.Collection`.

        :param root_collection: root collection to read from
        :param file_id: value of ``"_id"`` for the file to read
        :param file_document: file document from
            `root_collection.files`
        :param session: a
            :class:`~pymongo.client_session.ClientSession` to use for all
            commands

        .. versionchanged:: 3.8
           For better performance and to better follow the GridFS spec,
           :class:`GridOut` now uses a single cursor to read all the chunks in
           the file.

        .. versionchanged:: 3.6
           Added ``session`` parameter.

        .. versionchanged:: 3.0
           Creating a GridOut does not immediately retrieve the file metadata
           from the server. Metadata is fetched when first needed.
        """
        if not isinstance(root_collection, Collection):
            raise TypeError(
                f"root_collection must be an instance of Collection, not {type(root_collection)}"
            )
        _disallow_transactions(session)

        root_collection = _clear_entity_type_registry(root_collection)

        super().__init__()

        self._chunks = root_collection.chunks
        self._files = root_collection.files
        self._file_id = file_id
        self._buffer = EMPTY
        # Start position within the current buffered chunk.
        self._buffer_pos = 0