gridfs – Tools for working with GridFS

GridFS is a specification for storing large objects in Mongo.

The gridfs package is an implementation of GridFS on top of pymongo, exposing a file-like interface.

See general MongoDB documentation

gridfs

class gridfs.GridFS(database, collection='fs')

Create a new instance of GridFS.

Raises TypeError if database is not an instance of Database.

Parameters :

• database: database to use
• collection (optional): root collection to use

New in version 1.6: The collection parameter.

See general MongoDB documentation

gridfs

delete(file_id)

Delete a file from GridFS by "_id".

Removes all data belonging to the file with "_id": file_id.

Warning

Any processes/threads reading from the file while this method is executing will likely see an invalid/corrupt file. Care should be taken to avoid concurrent reads to a file while it is being deleted.

Note

Deletes of non-existent files are considered successful since the end result is the same: no file with that _id remains.

Parameters :

• file_id: "_id" of the file to delete

New in version 1.6.

exists(document_or_id=None, **kwargs)

Check if a file exists in this instance of GridFS.

The file to check for can be specified by the value of it’s _id key, or by passing in a query document. A query document can be passed in as dictionary, or by using keyword arguments. Thus, the following three calls are equivalent:

>>> fs.exists(file_id)
>>> fs.exists({"_id": file_id})
>>> fs.exists(_id=file_id)

As are the following two calls:

>>> fs.exists({"filename": "mike.txt"})
>>> fs.exists(filename="mike.txt")

And the following two:

>>> fs.exists({"foo": {"$gt": 12}})
>>> fs.exists(foo={"$gt": 12})

Returns True if a matching file exists, False otherwise. Calls to exists() will not automatically create appropriate indexes; application developers should be sure to create indexes if needed and as appropriate.

Parameters :

• document_or_id (optional): query document, or _id of the document to check for
• **kwargs (optional): keyword arguments are used as a query document, if they’re present.

New in version 1.8.

get(file_id)

Get a file from GridFS by "_id".

Returns an instance of GridOut, which provides a file-like interface for reading.

Parameters :

• file_id: "_id" of the file to get

New in version 1.6.

get_last_version(filename=None, **kwargs)

Get the most recent version of a file in GridFS by "filename" or metadata fields.

Equivalent to calling get_version() with the default version (-1).

Parameters :

• filename: "filename" of the file to get, or None
• **kwargs (optional): find files by custom metadata.

Changed in version 1.11: filename defaults to None;

New in version 1.11: Accept keyword arguments to find files by custom metadata. See get_version().

New in version 1.6.

get_version(filename=None, version=-1, **kwargs)

Get a file from GridFS by "filename" or metadata fields.

Returns a version of the file in GridFS whose filename matches filename and whose metadata fields match the supplied keyword arguments, as an instance of GridOut.

Version numbering is a convenience atop the GridFS API provided by MongoDB. If more than one file matches the query (either by filename alone, by metadata fields, or by a combination of both), then version -1 will be the most recently uploaded matching file, -2 the second most recently uploaded, etc. Version 0 will be the first version uploaded, 1 the second version, etc. So if three versions have been uploaded, then version 0 is the same as version -3, version 1 is the same as version -2, and version 2 is the same as version -1.

Raises NoFile if no such version of that file exists.

An index on {filename: 1, uploadDate: -1} will automatically be created when this method is called the first time.

Parameters :

• filename: "filename" of the file to get, or None
• version (optional): version of the file to get (defualts to -1, the most recent version uploaded)
• **kwargs (optional): find files by custom metadata.

Changed in version 1.11: filename defaults to None;

New in version 1.11: Accept keyword arguments to find files by custom metadata.

New in version 1.9.

list()

List the names of all files stored in this instance of GridFS.

Changed in version 1.6: Removed the collection argument.

new_file(**kwargs)

Create a new file in GridFS.

Returns a new GridIn instance to which data can be written. Any keyword arguments will be passed through to GridIn().

If the "_id" of the file is manually specified, it must not already exist in GridFS. Otherwise FileExists is raised.

Parameters :

• **kwargs (optional): keyword arguments for file creation

New in version 1.6.

open(*args, **kwargs)

No longer supported.

Changed in version 1.6: The open method is no longer supported.

put(data, **kwargs)

Put data in GridFS as a new file.

Equivalent to doing:

try:
    f = new_file(**kwargs)
    f.write(data)
finally
    f.close()

data can be either an instance of str (bytes in python 3) or a file-like object providing a read() method. If an encoding keyword argument is passed, data can also be a unicode (str in python 3) instance, which will be encoded as encoding before being written. Any keyword arguments will be passed through to the created file - see GridIn() for possible arguments. Returns the "_id" of the created file.

If the "_id" of the file is manually specified, it must not already exist in GridFS. Otherwise FileExists is raised.

Parameters :

• data: data to be written as a file.
• **kwargs (optional): keyword arguments for file creation

New in version 1.9: The ability to write unicode, if an encoding has been specified as a keyword argument.

New in version 1.6.

remove(*args, **kwargs)

No longer supported.

Changed in version 1.6: The remove method is no longer supported.

Sub-modules:

• errors – Exceptions raised by the gridfs package
• grid_file – Tools for representing files stored in GridFS