grid_file – Tools for representing files stored in GridFS

File-like object used for reading from and writing to GridFS

class gridfs.grid_file.GridFile(file_spec, database, mode='r', collection='fs')

Open a “file” in GridFS.

Application developers should generally not need to instantiate this class directly - instead see the gridfs.GridFS.open method.

Only a single opened GridFile instance may exist for a file in gridfs at any time. Care must be taken to close GridFile instances when done using them. GridFiles support the context manager protocol (the “with” statement).

Raises TypeError if file_spec is not an instance of dict, database is not an instance of pymongo.database.Database, or collection is not an instance of (str, unicode).

The file_spec argument must be a SON query specifier for the file to open. The first file matching the specifier will be opened. If no such files exist, a new file is created using the metadata in file_spec. The valid fields in a file_spec are as follows:

  • “_id”: unique ID for this file * default: pymongo.objectid.ObjectId()
  • “filename”: human name for the file
  • “contentType”: valid mime-type for the file
  • “length”: size of the file, in bytes * only used for querying, automatically set for inserts
  • “chunkSize”: size of each of the chunks, in bytes * default: 256 kb
  • “uploadDate”: date when the object was first stored * only used for querying, automatically set for inserts
  • “aliases”: array of alias strings
  • “metadata”: a SON document containing arbitrary data
Parameters:
  • file_spec: query specifier as described above
  • database: the database to store/retrieve this file in
  • mode (optional): the mode to open this file with, one of (“r”, “w”)
  • collection (optional): the collection in which to store/retrieve this file
close()

Close the GridFile.

A closed GridFile cannot be read or written any more. Calling close() more than once is allowed.

flush()
Flush the GridFile to the database.
read(size=-1)

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

The bytes are returned as a string object. If size is negative or omitted all data is read. Raises ValueError if this GridFile is already closed.

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

Rename this GridFile.

Due to buffering, the rename might not actually occur until flush() or close() is called.

Parameters:
  • filename: the new name for this GridFile
seek(pos, whence=0)

Set the current position of the GridFile (read-mode files only).

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 GridFile’s current position (read-mode files only).
write(str)

Write a string to the GridFile. There is no return value.

Due to buffering, the string may not actually show up in the database until the flush() or close() method is called. Raises ValueError if this GridFile is already closed. Raises TypeErrer if str is not an instance of str.

Parameters:
  • str: string of bytes to be written to the file
writelines(sequence)

Write a sequence of strings to the file.

Does not add seperators.

Previous topic

errors – Exceptions raised by the gridfs package

Next topic

Tools

This Page