Motor GridFS Classes

Store blobs of data in GridFS.

See also

Differences between PyMongo’s and Motor’s GridFS APIs.

See also

motor.web

class motor.MotorGridFS(database, collection='fs')

An instance of GridFS on top of a single Database. You must call open() before using the MotorGridFS object.

Parameters :

• database: a MotorDatabase
• collection (optional): A string, name of root collection to use, such as “fs” or “my_files”

See general MongoDB documentation

gridfs

delete(file_id, callback=None)

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
• callback (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

exists(document_or_id=None, callback=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 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
• callback (optional): function taking (result, error), executed when operation completes
• **kwargs (optional): keyword arguments are used as a query document, if they’re present.

If a callback is passed, returns None, else returns a Future.

get(file_id, callback=None)

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
• callback (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

get_last_version(filename=None, callback=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
• callback (optional): function taking (result, error), executed when operation completes
• **kwargs (optional): find files by custom metadata.

If a callback is passed, returns None, else returns a Future.

get_version(filename=None, version=-1, callback=None, **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 (defaults to -1, the most recent version uploaded)
• callback (optional): function taking (result, error), executed when operation completes
• **kwargs (optional): find files by custom metadata.

If a callback is passed, returns None, else returns a Future.

list(callback=None)

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

Parameters :

• callback (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

new_file(callback=None, **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 :

• callback (optional): function taking (result, error), executed when operation completes
• **kwargs (optional): keyword arguments for file creation

If a callback is passed, returns None, else returns a Future.

open(callback=None)

Actually initialize. Takes an optional callback, or returns a Future that resolves to self when opened.

Parameters :

• callback: Optional function taking parameters (self, error)

put(data, callback=None, **kwargs)

Put data into GridFS as a new file.

Equivalent to doing:

@gen.coroutine
def f(data, **kwargs):
    try:
        f = yield my_gridfs.new_file(**kwargs)
        yield f.write(data)
    finally:
        yield 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 MotorGridIn() 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.
• callback (optional): function taking (result, error), executed when operation completes
• **kwargs (optional): keyword arguments for file creation

If a callback is passed, returns None, else returns a Future.

class motor.MotorGridIn(root_collection, **kwargs)

Class to write data to GridFS. If instantiating directly, you must call open() before using the MotorGridIn object. However, application developers should not generally need to instantiate this class - see new_file().

Any of the file level options specified in the GridFS Spec may be passed as keyword arguments. Any additional keyword arguments will be set as additional fields on the file document. Valid keyword arguments include:

• "_id": unique ID for this file (default: ObjectId) - this "_id" must not have already been used for another file
• "filename": human name for the file
• "contentType" or "content_type": valid mime-type for the file
• "chunkSize" or "chunk_size": size of each of the chunks, in bytes (default: 256 kb)
• "encoding": encoding used for this file. In Python 2, any unicode that is written to the file will be converted to a str. In Python 3, any str that is written to the file will be converted to bytes.

Parameters :

• root_collection: A MotorCollection, the root collection

  to write to

• **kwargs (optional): file level options (see above)

_id

The '_id' value for this file.

This attribute is read-only.

set(name, value, callback=None)

Set an arbitrary metadata attribute on the file. Stores value on the server as a key-value pair within the file document once the file is closed. If the file is already closed, calling set will immediately update the file document on the server.

Metadata set on the file appears as attributes on a MotorGridOut object created from the file.

Parameters :

• name: Name of the attribute, will be stored as a key in the file document on the server
• value: Value of the attribute
• callback: Optional callback to execute once attribute is set.

If a callback is passed, returns None, else returns a Future.

close(callback=None)

Flush the file and close it.

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

Parameters :

• callback (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

open(callback=None)

Actually initialize. Takes an optional callback, or returns a Future that resolves to self when opened.

Parameters :

• callback: Optional function taking parameters (self, error)

set(name, value, callback=None)

Set an arbitrary metadata attribute on the file. Stores value on the server as a key-value pair within the file document once the file is closed. If the file is already closed, calling set will immediately update the file document on the server.

Metadata set on the file appears as attributes on a MotorGridOut object created from the file.

Parameters :

• name: Name of the attribute, will be stored as a key in the file document on the server
• value: Value of the attribute
• callback: Optional callback to execute once attribute is set.

If a callback is passed, returns None, else returns a Future.

write(data, callback=None)

Write data to the file. There is no return value.

data can be either a string of bytes or a file-like object (implementing read()). If the file has an encoding attribute, data can also be a unicode (str in python 3) instance, which will be encoded as encoding before being written.

Due to buffering, the data may not actually be written to the database until the close() method is called. Raises ValueError if this file is already closed. Raises TypeError if data is not an instance of str (bytes in python 3), a file-like object, or an instance of unicode (str in python 3). Unicode data is only allowed if the file has an encoding attribute.

Parameters :

• data: string of bytes or file-like object to be written to the file
• callback (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

writelines(sequence, callback=None)

Write a sequence of strings to the file.

Does not add seperators.

Parameters :

• callback (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

chunk_size

Chunk size for this file.

This attribute is read-only.

closed

Is this file closed?

content_type

Mime-type for this file.

filename

Name of this file.

length

Length (in bytes) of this file.

This attribute is read-only and can only be read after close() has been called.

md5

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

This attribute is read-only and can only be read after close() has been called.

name

Alias for filename.

upload_date

Date that this file was uploaded.

This attribute is read-only and can only be read after close() has been called.

class motor.MotorGridOut(root_collection, file_id=None, file_document=None, io_loop=None)

Class to read data out of GridFS.

Application developers should generally not need to instantiate this class directly - instead see the methods provided by MotorGridFS.

_id

The '_id' value for this file.

This attribute is read-only.

open(callback=None)

Actually initialize. Takes an optional callback, or returns a Future that resolves to self when opened.

Parameters :

• callback: Optional function taking parameters (self, error)

read(size=-1, callback=None)

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

The bytes are returned as an instance of str (bytes in python 3). If size is negative or omitted all data is read.

Parameters :

• size (optional): the number of bytes to read
• callback (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

readline(size=-1, callback=None)

Read one line or up to size bytes from the file.

Parameters :

• size (optional): the maximum number of bytes to read
• callback (optional): function taking (result, error), executed when operation completes

If a callback is passed, returns None, else returns a Future.

seek(pos, whence=0)

Set the current position of this file.

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.

stream_to_handler(*args, **kwargs)

Write the contents of this file to a tornado.web.RequestHandler. This method will call flush on the RequestHandler, so ensure all headers have already been set. For a more complete example see the implementation of GridFSHandler.

Returns a Future.

class FileHandler(tornado.web.RequestHandler):
    @tornado.web.asynchronous
    @gen.coroutine
    def get(self, filename):
        db = self.settings['db']
        fs = yield motor.MotorGridFS(db()).open()
        try:
            gridout = yield fs.get_last_version(filename)
        except gridfs.NoFile:
            raise tornado.web.HTTPError(404)

        self.set_header("Content-Type", gridout.content_type)
        self.set_header("Content-Length", gridout.length)
        yield gridout.stream_to_handler(self)
        self.finish()

See also

Tornado RequestHandler

tell()

Return the current position of this file.

aliases

List of aliases for this file.

This attribute is read-only.

chunk_size

Chunk size for this file.

This attribute is read-only.

content_type

Mime-type for this file.

This attribute is read-only.

filename

Name of this file.

This attribute is read-only.

length

Length (in bytes) of this file.

This attribute is read-only.

md5

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

This attribute is read-only.

metadata

Metadata attached to this file.

This attribute is read-only.

name

Alias for filename.

This attribute is read-only.

upload_date

Date that this file was first uploaded.

This attribute is read-only.