gridfs.rst

Motor GridFS Classes

motor.motor_tornado

Store blobs of data in GridFS.

Differences between PyMongo's and Motor's GridFS APIs <gridfs-differences>.

web

Create a new instance of MotorGridFSBucket.

Raises TypeError if database is not an instance of MotorDatabase.

Raises ~pymongo.errors.ConfigurationError if write_concern is not acknowledged.

Parameters

• `database`: database to use.
• bucket_name (optional): The name of the bucket. Defaults to 'fs'.
• chunk_size_bytes (optional): The chunk size in bytes. Defaults to 255KB.
• write_concern (optional): The ~pymongo.write_concern.WriteConcern to use. If None (the default) db.write_concern is used.
• read_preference (optional): The read preference to use. If None (the default) db.read_preference is used.

gridfs

delete(self, file_id))

Delete a file's metadata and data chunks from a GridFS bucket:

async def delete():
    my_db = MotorClient().test
    fs = MotorGridFSBucket(my_db)
    # Get _id of file to delete
    file_id = await fs.upload_from_stream("test_file",
                                          b"data I want to store!")
    await fs.delete(file_id)

Raises ~gridfs.errors.NoFile if no file with file_id exists.

Parameters

• `file_id`: The _id of the file to be deleted.

Returns a Future.

download_to_stream(self, file_id, destination))

Downloads the contents of the stored file specified by file_id and writes the contents to `destination`:

async def download():
    my_db = MotorClient().test
    fs = MotorGridFSBucket(my_db)
    # Get _id of file to read
    file_id = await fs.upload_from_stream("test_file",
                                          b"data I want to store!")
    # Get file to write to
    file = open('myfile','wb+')
    await fs.download_to_stream(file_id, file)
    file.seek(0)
    contents = file.read()

Raises ~gridfs.errors.NoFile if no file with file_id exists.

Parameters

• `file_id`: The _id of the file to be downloaded.
• `destination`: a file-like object implementing write.

Returns a Future.

download_to_stream_by_name(self, filename, destination, revision=-1)

Write the contents of filename (with optional revision) to destination.

For example:

async def download_by_name():
    my_db = MotorClient().test
    fs = MotorGridFSBucket(my_db)
    # Get file to write to
    file = open('myfile','wb')
    await fs.download_to_stream_by_name("test_file", file)

Raises ~gridfs.errors.NoFile if no such version of that file exists.

Raises ~ValueError if filename is not a string.

Parameters

• `filename`: The name of the file to read from.
• `destination`: A file-like object that implements write.
• revision (optional): Which revision (documents with the same filename and different uploadDate) of the file to retrieve. Defaults to -1 (the most recent revision).

Note

Revision numbers are defined as follows:

• 0 = the original stored file
• 1 = the first revision
• 2 = the second revision
• etc...
• -2 = the second most recent revision
• -1 = the most recent revision

find(self, args,*kwargs)

Find and return the files collection documents that match filter.

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:

async def find():
    cursor = fs.find({"filename": "lisa.txt"},
                     no_cursor_timeout=True)

    async for grid_data in cursor:
        data = grid_data.read()

iterates through all versions of "lisa.txt" stored in GridFS. Setting no_cursor_timeout 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)

returns a cursor to the three most recently uploaded files in GridFS.

Follows a similar interface to ~MotorCollection.find in MotorCollection.

Parameters

• `filter`: Search query.
• batch_size (optional): The number of documents to return per batch.
• limit (optional): The maximum number of documents to return.
• no_cursor_timeout (optional): The server normally times out idle cursors after an inactivity period (10 minutes) to prevent excess memory use. Set this option to True prevent that.
• skip (optional): The number of documents to skip before returning.
• sort (optional): The order by which to sort results. Defaults to None.

Returns a Future.

open_download_stream(self, file_id)

Opens a stream to read the contents of the stored file specified by file_id:

async def download_stream():
    my_db = MotorClient().test
    fs = MotorGridFSBucket(my_db)
    # get _id of file to read.
    file_id = await fs.upload_from_stream("test_file",
                                          b"data I want to store!")
    grid_out = await fs.open_download_stream(file_id)
    contents = await grid_out.read()

Raises ~gridfs.errors.NoFile if no file with file_id exists.

Parameters

• `file_id`: The _id of the file to be downloaded.

Returns a Future that resolves to a MotorGridOut.

open_download_stream_by_name(self, filename, revision=-1)

Opens a stream to read the contents of filename and optional `revision`:

async def download_by_name():
    my_db = MotorClient().test
    fs = MotorGridFSBucket(my_db)
    # get _id of file to read.
    file_id = await fs.upload_from_stream("test_file",
                                          b"data I want to store!")
    grid_out = await fs.open_download_stream_by_name(file_id)
    contents = await grid_out.read()

Raises ~gridfs.errors.NoFile if no such version of that file exists.

Raises ~ValueError filename is not a string.

Parameters

• `filename`: The name of the file to read from.
• revision (optional): Which revision (documents with the same filename and different uploadDate) of the file to retrieve. Defaults to -1 (the most recent revision).

Returns a Future that resolves to a MotorGridOut.

Note

Revision numbers are defined as follows:

• 0 = the original stored file
• 1 = the first revision
• 2 = the second revision
• etc...
• -2 = the second most recent revision
• -1 = the most recent revision

open_upload_stream(self, filename, chunk_size_bytes=None, metadata=None)

Opens a stream for writing.

Specify the filename, and add any additional information in the metadata field of the file document or modify the chunk size:

async def upload():
    my_db = MotorClient().test
    fs = MotorGridFSBucket(my_db)
    grid_in, file_id = fs.open_upload_stream(
        "test_file", chunk_size_bytes=4,
        metadata={"contentType": "text/plain"})

    await grid_in.write(b"data I want to store!")
    await grid_in.close()  # uploaded on close

Returns an instance of MotorGridIn.

Raises ~gridfs.errors.NoFile if no such version of that file exists. Raises ~ValueError if filename is not a string.

Using the "async with" statement calls ~MotorGridIn.close automatically:

async def upload():
    my_db = MotorClient().test
    fs = MotorGridFSBucket(my_db)
    async with await fs.new_file() as gridin:
        await gridin.write(b'First part\n')
        await gridin.write(b'Second part')

    # gridin is now closed automatically.

Parameters

• `filename`: The name of the file to upload.
• chunk_size_bytes (options): The number of bytes per chunk of this file. Defaults to the chunk_size_bytes in MotorGridFSBucket.
• metadata (optional): User data for the 'metadata' field of the files collection document. If not provided the metadata field will be omitted from the files collection document.

open_upload_stream_with_id(self, file_id, filename, chunk_size_bytes=None, metadata=None)

Opens a stream for writing.

Specify the filed_id and filename, and add any additional information in the metadata field of the file document, or modify the chunk size:

async def upload():
    my_db = MotorClient().test
    fs = MotorGridFSBucket(my_db)
    grid_in, file_id = fs.open_upload_stream_with_id(
        ObjectId(),
        "test_file",
        chunk_size_bytes=4,
        metadata={"contentType": "text/plain"})

    await grid_in.write(b"data I want to store!")
    await grid_in.close()  # uploaded on close

Returns an instance of MotorGridIn.

Raises ~gridfs.errors.NoFile if no such version of that file exists. Raises ~ValueError if filename is not a string.

Parameters

• `file_id`: The id to use for this file. The id must not have already been used for another file.
• `filename`: The name of the file to upload.
• chunk_size_bytes (options): The number of bytes per chunk of this file. Defaults to the chunk_size_bytes in MotorGridFSBucket.
• metadata (optional): User data for the 'metadata' field of the files collection document. If not provided the metadata field will be omitted from the files collection document.

rename(self, file_id, new_filename))

Renames the stored file with the specified file_id.

For example:

async def rename():
    my_db = MotorClient().test
    fs = MotorGridFSBucket(my_db)
    # get _id of file to read.
    file_id = await fs.upload_from_stream("test_file",
                                          b"data I want to store!")

    await fs.rename(file_id, "new_test_name")

Raises ~gridfs.errors.NoFile if no file with file_id exists.

Parameters

• `file_id`: The _id of the file to be renamed.
• `new_filename`: The new name of the file.

Returns a Future.

upload_from_stream(self, filename, source, chunk_size_bytes=None, metadata=None))

Uploads a user file to a GridFS bucket.

Reads the contents of the user file from source and uploads it to the file filename. Source can be a string or file-like object. For example:

async def upload_from_stream():
    my_db = MotorClient().test
    fs = MotorGridFSBucket(my_db)
    file_id = await fs.upload_from_stream(
        "test_file",
        b"data I want to store!",
        chunk_size_bytes=4,
        metadata={"contentType": "text/plain"})

Raises ~gridfs.errors.NoFile if no such version of that file exists. Raises ~ValueError if filename is not a string.

Parameters

• `filename`: The name of the file to upload.
• `source`: The source stream of the content to be uploaded. Must be a file-like object that implements read or a string.
• chunk_size_bytes (options): The number of bytes per chunk of this file. Defaults to the chunk_size_bytes of MotorGridFSBucket.
• metadata (optional): User data for the 'metadata' field of the files collection document. If not provided the metadata field will be omitted from the files collection document.

Returns a Future that resolves to the _id of the uploaded file.

upload_from_stream_with_id(self, file_id, filename, source, chunk_size_bytes=None, metadata=None))

Uploads a user file to a GridFS bucket with a custom file id.

Reads the contents of the user file from source and uploads it to the file filename. Source can be a string or file-like object. For example:

async def upload_from_stream_with_id():
    my_db = MotorClient().test
    fs = MotorGridFSBucket(my_db)
    file_id = await fs.upload_from_stream_with_id(
        ObjectId(),
        "test_file",
        b"data I want to store!",
        chunk_size_bytes=4,
        metadata={"contentType": "text/plain"})

Raises ~gridfs.errors.NoFile if no such version of that file exists. Raises ~ValueError if filename is not a string.

Parameters

• `file_id`: The id to use for this file. The id must not have already been used for another file.
• `filename`: The name of the file to upload.
• `source`: The source stream of the content to be uploaded. Must be a file-like object that implements read or a string.
• chunk_size_bytes (options): The number of bytes per chunk of this file. Defaults to the chunk_size_bytes of MotorGridFSBucket.
• metadata (optional): User data for the 'metadata' field of the files collection document. If not provided the metadata field will be omitted from the files collection document.

Returns a Future.

MotorGridIn

MotorGridOut

MotorGridOutCursor