grid_file – Tools for representing files stored in GridFS

Tools for representing files stored in GridFS.

  • class gridfs.gridfile.GridIn(_root_collection, session=None, disable_md5=False, **kwargs)
  • Write a file to GridFS

Application developers should generally not need toinstantiate this class directly - instead see the methodsprovided by GridFS.

Raises TypeError if root_collection is not aninstance of Collection.

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

  • "_id": unique ID for this file (default:ObjectId) - this "_id" mustnot have already been used for another file
  • "filename": human name for the file
  • "contentType" or "content_type": valid mime-typefor the file
  • "chunkSize" or "chunk_size": size of each of thechunks, in bytes (default: 255 kb)
  • "encoding": encoding used for this file. In Python 2,any unicode that is written to the file will beconverted to a str. In Python 3, any strthat is written to the file will be converted tobytes.

Parameters:

  • root_collection: root collection to write to
  • session (optional): aClientSession to use for allcommands
  • disable_md5 (optional): When True, an MD5 checksum will not becomputed for the uploaded file. Useful in environments whereMD5 cannot be used for regulatory or other reasons. Defaults toFalse.
  • **kwargs (optional): file level options (see above)

Changed in version 3.6: Added session parameter.

Changed in version 3.0: root_collection must use an acknowledgedwrite_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. Callingclose() more than once is allowed.

  • closed

  • Is this file closed?

  • content_type

  • Mime-type for this file.

  • filename

  • Name of this file.

  • length

  • Length (in bytes) of this file.

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

  • md5
  • 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 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 anencoding attribute, data can also be aunicode (str in python 3) instance, whichwill be encoded as encoding before being written.

Due to buffering, the data may not actually be written to thedatabase until the close() method is called. RaisesValueError if this file is already closed. RaisesTypeError if data is not an instance ofstr (bytes in python 3), a file-like object,or an instance of unicode (str in python 3).Unicode data is only allowed if the file has an encodingattribute.

Parameters:

  1. - _data_: string of bytes or file-like object to be writtento the file
  • writelines(sequence)
  • Write a sequence of strings to the file.

Does not add seperators.

  • class gridfs.gridfile.GridOut(_root_collection, file_id=None, file_document=None, session=None)
  • Read a file from GridFS

Application developers should generally not need toinstantiate this class directly - instead see the methodsprovided by GridFS.

Either file_id or file_document must be specified,file_document will be given priority if present. RaisesTypeError if root_collection is not an instance ofCollection.

Parameters:

  • root_collection: root collection to read from
  • file_id (optional): value of "_id" for the file to read
  • file_document (optional): file document fromroot_collection.files
  • session (optional): aClientSession to use for allcommands

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 inthe file.

Changed in version 3.6: Added session parameter.

Changed in version 3.0: Creating a GridOut does not immediately retrieve the file metadatafrom 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 ofstr (bytes in python 3). This can beuseful when serving files using a webserver that handlessuch an iterator efficiently.

Note

This is different from io.IOBase which iterates overlines in the file. Use GridOut.readline() to read line byline instead of chunk by chunk.

Changed in version 3.8: The iterator now raises CorruptGridFile when encounteringany truncated, missing, or extra chunk in a file. The previousbehavior was to only raise CorruptGridFile on a missingchunk.

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

  • content_type

  • Mime-type for this file.

This attribute is read-only.

  • filename
  • Name of this file.

This attribute is read-only.

  • length
  • Length (in bytes) of this file.

This attribute is read-only.

  • md5
  • 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 thereisn’t enough data).

The bytes are returned as an instance of str (bytesin python 3). If size is negative or omitted all data is read.

Parameters:

  1. - _size_ (optional): the number of bytes to read

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

  • readchunk()

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

  • readline(size=-1)

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

Parameters:

  1. - _size_ (optional): the maximum number of bytes to read
  • seek(pos, whence=0)
  • Set the current position of this file.

Parameters:

  1. - _pos_: the position (or offset if using relativepositioning) to seek to
  2. - _whence_ (optional): where to seekfrom. <code>os.SEEK_SET</code> (<code>0</code>) for absolute filepositioning, <code>os.SEEK_CUR</code> (<code>1</code>) to seek relativeto the current position, <code>os.SEEK_END</code> (<code>2</code>) toseek 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.gridfile.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 normalCursor.

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

See also

The MongoDB documentation on

cursors

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

  • removeoption(args, *kwargs_)

  • Unset arbitrary query flags using a bitmask.

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