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.
-
class
gridfs.
GridFS
(database, collection='fs')¶ Create a new instance of
GridFS
.Raises
TypeError
if database is not an instance ofDatabase
.Parameters: - database: database to use
- collection (optional): root collection to use
Changed in version 3.0: database must use an acknowledged
write_concern
-
delete
(file_id)¶ Delete a file from GridFS by
"_id"
.Deletes 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
- file_id:
-
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 its
_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 toexists()
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.
-
find
(*args, **kwargs)¶ Query GridFS for files.
Returns a cursor that iterates across files matching arbitrary queries on the files collection. Can be combined with other modifiers for additional control. For example:
for grid_out in fs.find({"filename": "lisa.txt"}, no_cursor_timeout=True): data = grid_out.read()
would iterate through all versions of “lisa.txt” stored in GridFS. Note that setting no_cursor_timeout to True may be important to prevent the cursor from timing out during long multi-file processing work.
As another example, the call:
most_recent_three = fs.find().sort("uploadDate", -1).limit(3)
would return a cursor to the three most recently uploaded files in GridFS.
Follows a similar interface to
find()
inCollection
.Parameters: - filter (optional): a SON object specifying elements which must be present for a document to be included in the result set
- skip (optional): the number of files to omit (from the start of the result set) when returning the results
- limit (optional): the maximum number of results to return
- no_cursor_timeout (optional): if False (the default), any returned cursor is closed by the server after 10 minutes of inactivity. If set to True, the returned cursor will never time out on the server. Care should be taken to ensure that cursors with no_cursor_timeout turned on are properly closed.
- sort (optional): a list of (key, direction) pairs
specifying the sort order for this query. See
sort()
for details.
Raises
TypeError
if any of the arguments are of improper type. Returns an instance ofGridOutCursor
corresponding to this query.Changed in version 3.0: Removed the read_preference, tag_sets, and secondary_acceptable_latency_ms options.
New in version 2.7.
-
find_one
(filter=None, *args, **kwargs)¶ Get a single file from gridfs.
All arguments to
find()
are also valid arguments forfind_one()
, although any limit argument will be ignored. Returns a singleGridOut
, orNone
if no matching file is found. For example:file = fs.find_one({"filename": "lisa.txt"})
Parameters: - filter (optional): a dictionary specifying
the query to be performing OR any other type to be used as
the value for a query for
"_id"
in the file collection. - *args (optional): any additional positional arguments are
the same as the arguments to
find()
. - **kwargs (optional): any additional keyword arguments
are the same as the arguments to
find()
.
- filter (optional): a dictionary specifying
the query to be performing OR any other type to be used as
the value for a query for
-
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
- file_id:
-
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.
- filename:
-
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. Version0
will be the first version uploaded,1
the second version, etc. So if three versions have been uploaded, then version0
is the same as version-3
, version1
is the same as version-2
, and version2
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 (defaults to -1, the most recent version uploaded)
- **kwargs (optional): find files by custom metadata.
- filename:
-
list
()¶ List the names of all files stored in this instance of
GridFS
.An index on
{filename: 1, uploadDate: -1}
will automatically be created when this method is called the first time.Changed in version 2.7:
list
ensures an index, the same asget_version
.
-
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 toGridIn()
.If the
"_id"
of the file is manually specified, it must not already exist in GridFS. OtherwiseFileExists
is raised.Parameters: - **kwargs (optional): keyword arguments for file creation
-
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 aread()
method. If an encoding keyword argument is passed, data can also be aunicode
(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 - seeGridIn()
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. OtherwiseFileExists
is raised.Parameters: - data: data to be written as a file.
- **kwargs (optional): keyword arguments for file creation
Changed in version 3.0: w=0 writes to GridFS are now prohibited.
Sub-modules: