# `grid_file` – Tools for representing files stored in GridFS

Re-import of synchronous gridfs API for compatibility.

class gridfs.grid_file.GridIn(root_collection, session=None, **kwargs)

  Write a file to GridFS

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

  Raises `TypeError` if root_collection is not an instance of `Collection`.

  Any of the file level options specified in the GridFS Spec may be passed as keyword arguments. Any additional keyword arguments will be set as additional fields on the file document. Valid keyword arguments include:

  > - `"_id"`: unique ID for this file (default: `ObjectId`) - this `"_id"` must not have already been used for another file

  > - `"filename"`: human name for the file

  > - `"contentType"` or `"content_type"`: valid mime-type for the file

  > - `"chunkSize"` or `"chunk_size"`: size of each of the chunks, in bytes (default: 255 kb)

  > - `"encoding"`: encoding used for this file. Any `str` that is written to the file will be converted to `bytes`.

  Parameters:

    - root_collection (Collection[Any]) – root collection to write to

    - session (Optional[ClientSession]) – a `ClientSession` to use for all commands

    - kwargs (Any) – Any: file level options (see above)

  Changed in version 4.0: Removed the disable_md5 parameter. See disable_md5 parameter is removed for details.

  Changed in version 3.7: Added the disable_md5 parameter.

  Changed in version 3.6: Added `session` parameter.

  Changed in version 3.0: root_collection must use an acknowledged `write_concern`

  _id: Any

    The `'_id'` value for this file.

    This attribute is read-only.

  abort()

    Remove all chunks/files that may have been uploaded and close.

    Return type:

      None

  property chunk_size: Any

    Chunk size for this file.

    This attribute is read-only.

  close()

    Flush the file and close it.

    A closed file cannot be written any more. Calling `close()` more than once is allowed.

    Return type:

      None

  property closed: bool

    Is this file closed?

  property content_type: Any

    DEPRECATED, will be removed in PyMongo 5.0. Mime-type for this file.

  property filename: Any

    Name of this file.

  property length: Any

    Length (in bytes) of this file.

    This attribute is read-only and can only be read after `close()` has been called.

  property md5: Any

    DEPRECATED, will be removed in PyMongo 5.0. MD5 of the contents of this file if an md5 sum was created.

    This attribute is read-only and can only be read after `close()` has been called.

  property name: Any

    Alias for filename.

  property upload_date: Any

    Date that this file was uploaded.

    This attribute is read-only and can only be read after `close()` has been called.

  write(data)

    Write data to the file. There is no return value.

    data can be either a string of bytes or a file-like object (implementing `read()`). If the file has an `encoding` attribute, data can also be a `str` instance, which will be encoded as `encoding` before being written.

    Due to buffering, the data may not actually be written to the database until the `close()` method is called. Raises `ValueError` if this file is already closed. Raises `TypeError` if data is not an instance of `bytes`, a file-like object, or an instance of `str`. Unicode data is only allowed if the file has an `encoding` attribute.

    Parameters:

      data (Any) – string of bytes or file-like object to be written to the file

    Return type:

      None

  writelines(sequence)

    Write a sequence of strings to the file.

    Does not add separators.

    Parameters:

      sequence (Iterable[Any])

    Return type:

      None

class gridfs.grid_file.GridOut(root_collection, file_id=None, file_document=None, session=None)

  Read a file from GridFS

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

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

  Parameters:

    - root_collection (Collection[Any]) – root collection to read from

    - file_id (Optional[int]) – value of `"_id"` for the file to read

    - file_document (Optional[Any]) – file document from root_collection.files

    - session (Optional[ClientSession]) – a `ClientSession` to use for all commands

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

  Changed in version 3.6: Added `session` parameter.

  Changed in version 3.0: Creating a GridOut does not immediately retrieve the file metadata from the server. Metadata is fetched when first needed.

  _id: Any

    The `'_id'` value for this file.

    This attribute is read-only.

  __iter__()

    Return an iterator over all of this file’s data.

    The iterator will return lines (delimited by `b'\n'`) of `bytes`. This can be useful when serving files using a webserver that handles such an iterator efficiently.

    Changed in version 3.8: The iterator now raises `CorruptGridFile` when encountering any truncated, missing, or extra chunk in a file. The previous behavior was to only raise `CorruptGridFile` on a missing chunk.

    Changed in version 4.0: The iterator now iterates over lines in the file, instead of chunks, to conform to the base class `io.IOBase`. Use `GridOut.readchunk()` to read chunk by chunk instead of line by line.

    Return type:

      GridOut

  property aliases: Any

    DEPRECATED, will be removed in PyMongo 5.0. List of aliases for this file.

    This attribute is read-only.

  property chunk_size: Any

    Chunk size for this file.

    This attribute is read-only.

  close()

    Make GridOut more generically file-like.

    Return type:

      None

  property content_type: Any

    DEPRECATED, will be removed in PyMongo 5.0. Mime-type for this file.

    This attribute is read-only.

  property filename: Any

    Name of this file.

    This attribute is read-only.

  fileno()

    Return underlying file descriptor if one exists.

    Raise OSError if the IO object does not use a file descriptor.

    Return type:

      NoReturn

  flush()

    Flush write buffers, if applicable.

    This is not implemented for read-only and non-blocking streams.

    Return type:

      None

  isatty()

    Return whether this is an ‘interactive’ stream.

    Return False if it can’t be determined.

    Return type:

      bool

  property length: Any

    Length (in bytes) of this file.

    This attribute is read-only.

  property md5: Any

    DEPRECATED, will be removed in PyMongo 5.0. MD5 of the contents of this file if an md5 sum was created.

    This attribute is read-only.

  property metadata: Any

    Metadata attached to this file.

    This attribute is read-only.

  property name: Any

    Alias for filename.

    This attribute is read-only.

  read(size=-1)

    Read at most size bytes from the file (less if there isn’t enough data).

    The bytes are returned as an instance of `bytes` If size is negative or omitted all data is read.

    Parameters:

      size (int) – the number of bytes to read

    Return type:

      bytes

    Changed in version 3.8: This method now only checks for extra chunks after reading the entire file. Previously, this method would check for extra chunks on every call.

  readable()

    Return whether object was opened for reading.

    If False, read() will raise OSError.

    Return type:

      bool

  readchunk()

    Reads a chunk at a time. If the current position is within a chunk the remainder of the chunk is returned.

    Return type:

      bytes

  seek(pos, whence=0)

    Set the current position of this file.

    Parameters:

      - pos (int) – the position (or offset if using relative positioning) to seek to

      - whence (int) – where to seek from. `os.SEEK_SET` (`0`) for absolute file positioning, `os.SEEK_CUR` (`1`) to seek relative to the current position, `os.SEEK_END` (`2`) to seek relative to the file’s end.

    Return type:

      int

    Changed in version 4.1: The method now returns the new position in the file, to conform to the behavior of `io.IOBase.seek()`.

  seekable()

    Return whether object supports random access.

    If False, seek(), tell() and truncate() will raise OSError. This method may need to do a test seek().

    Return type:

      bool

  tell()

    Return the current position of this file.

    Return type:

      int

  truncate(size=None)

    Truncate file to size bytes.

    File pointer is left unchanged. Size defaults to the current IO position as reported by tell(). Return the new size.

    Parameters:

      size (int | None)

    Return type:

      NoReturn

  property upload_date: Any

    Date that this file was first uploaded.

    This attribute is read-only.

  writable()

    Return whether object was opened for writing.

    If False, write() will raise OSError.

    Return type:

      bool

  writelines(lines)

    Write a list of lines to stream.

    Line separators are not added, so it is usual for each of the lines provided to have a line separator at the end.

    Parameters:

      lines (Any)

    Return type:

      NoReturn

class gridfs.grid_file.GridOutCursor(collection, filter=None, skip=0, limit=0, no_cursor_timeout=False, sort=None, batch_size=0, session=None)

  Create a new cursor, similar to the normal `Cursor`.

  Should not be called directly by application developers - see the `GridFS` method `find()` instead.

  See also

  The MongoDB documentation on cursors.

  Parameters:

    - collection (Collection[Any])

    - filter (Optional[Mapping[str, Any]])

    - skip (int)

    - limit (int)

    - no_cursor_timeout (bool)

    - sort (Optional[Any])

    - batch_size (int)

    - session (Optional[ClientSession])

  add_option(*args, **kwargs)

    Set arbitrary query flags using a bitmask.

    To set the tailable flag: cursor.add_option(2)

    Parameters:

      - args (Any)

      - kwargs (Any)

    Return type:

      NoReturn

  next()

    Get next GridOut object from cursor.

    Return type:

      GridOut

  remove_option(*args, **kwargs)

    Unset arbitrary query flags using a bitmask.

    To unset the tailable flag: cursor.remove_option(2)

    Parameters:

      - args (Any)

      - kwargs (Any)

    Return type:

      NoReturn

  to_list(length=None)

    Convert the cursor to a list.

    Parameters:

      length (int | None)

    Return type:

      list[GridOut]