grid_file – Tools for representing files stored in GridFS

Tools for representing files stored in 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 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. GridFile instances 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 Database, or collection is not an instance of basestring.

The file_spec argument must be a query specifying the file to open. The first file matching the query 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: ObjectId)

• "filename": human name for the file

• "contentType": valid mime-type for the file

• "length": size of the file, in bytes

  Note

  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

  Note

  only used for querying, automatically set for inserts

• "aliases": array of alias strings

• "metadata": document containing arbitrary metadata

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

aliases

List of aliases for this GridFile.

chunk_size

Chunk size for this GridFile.

close()

Close the GridFile.

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

closed

Is this GridFile closed?

content_type

Mime-type for this GridFile.

flush()

Flush the GridFile to the database.

length

Length (in bytes) of this GridFile.

md5

MD5 of the contents of this GridFile (generated on the server).

metadata

Metadata attached to this GridFile.

mode

Mode this GridFile was opened with.

name

Name of this GridFile.

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. 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 this 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 current position of this GridFile (read-mode files only).

upload_date

Date that this GridFile was first uploaded.

write(data)

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 data is not an instance of str.

Parameters:

• data: string of bytes to be written to the file

writelines(sequence)

Write a sequence of strings to the file.

Does not add seperators.