grid_file – Tools for representing files stored in GridFS

    class gridfs.grid_file.GridIn(root_collection, session=None, disable_md5=False, \*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 if root_collection is not an instance of Collection.

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

    Changed in version 3.6: Added session parameter.

    Changed in version 3.0: root_collection must use an acknowledged write_concern

    • _id

      The '_id' value for this file.

      This attribute is read-only.

    • abort()

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

    • chunk_size

      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 more than once is allowed.

    • closed

      Is this file closed?

    • content_type

      Mime-type for this file.

    • filename

      Name of this file.

    • 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.

    • name

      Alias for filename.

    • upload_date

      Date that this file was uploaded.

      This attribute is read-only and can only be read after has been called.

    • write(data)

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

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

      Parameters:
      • data: string of bytes or file-like object to be written to the file

    • writelines(sequence)

      Write a sequence of strings to the file.

      Does not add seperators.

    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 if root_collection is not an instance of Collection.

    Changed in version 3.8: For better performance and to better follow the GridFS spec, 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

      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 chunk-sized instances of str ( in python 3). This can be useful when serving files using a webserver that handles such an iterator efficiently.

      Note

      This is different from io.IOBase which iterates over lines in the file. Use to read line by line instead of chunk by chunk.

      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.

    • aliases

      List of aliases for this file.

      This attribute is read-only.

    • chunk_size

      Chunk size for this file.

      This attribute is read-only.

    • close()

      Make GridOut more generically file-like.

    • Mime-type for this file.

      This attribute is read-only.

    • length

      Length (in bytes) of this file.

      This attribute is read-only.

    • MD5 of the contents of this file if an md5 sum was created.

      This attribute is read-only.

    • metadata

      Metadata attached to this file.

      This attribute is read-only.

    • name

      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 str ( in python 3). If size is negative or omitted all data is read.

      Parameters:
      • size (optional): the number of bytes to read

      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.

    • readchunk()

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

    • readline(size=-1)

      Read one line or up to size bytes from the file.

    • seek(pos, whence=0)

      Set the current position of this file.

      Parameters:
      • pos: the position (or offset if using relative positioning) to seek to
      • whence (optional): 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.

    • tell()

      Return the current position of this file.

    • upload_date

      Date that this file was first uploaded.

      This attribute is read-only.

    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 method find() instead.

    See also

    The MongoDB documentation on

    • add_option(\args, **kwargs*)

      Set arbitrary query flags using a bitmask.

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

    • next()

      Get next GridOut object from cursor.