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.

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)

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

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

Parameters:
  • filename: "filename" of the file to get

New in version 1.6.

get_version(filename, version=-1)

Get a file from GridFS by "filename".

Returns a version of the file in GridFS with the name filename as an instance of GridOut. Version -1 will be the most recently uploaded, -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
  • version (optional): version of the file to get (defualts to -1, the most recent version uploaded)

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:

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

data can be either an instance of str or a file-like object providing a read() method. If an encoding keyword argument is passed, data can also be a unicode 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:

Previous topic

tz_util – MOVED

Next topic

errors – Exceptions raised by the gridfs package

This Page