motor.aiohttp - Integrate Motor with the aiohttp web framework

Warning

Motor will be deprecated on May 14th, 2026, one year after the production release of the PyMongo Async driver. Critical bug fixes will be made until May 14th, 2027. We strongly recommend that Motor users migrate to the PyMongo Async driver while Motor is still supported. To learn more, see the migration guide.

Serve GridFS files with Motor and aiohttp.

Requires Python 3.5 or later and aiohttp 3.0 or later.

See the AIOHTTPGridFS Example.

class motor.aiohttp.AIOHTTPGridFS(database, root_collection='fs', get_gridfs_file=<function get_gridfs_file>, get_cache_time=<function get_cache_time>, set_extra_headers=<function set_extra_headers>)

Serve files from GridFS.

This class is a request handler that serves GridFS files, similar to aiohttp’s built-in static file server.

client = AsyncIOMotorClient()
gridfs_handler = AIOHTTPGridFS(client.my_database)

app = aiohttp.web.Application()

# The GridFS URL pattern must have a "{filename}" variable.
resource = app.router.add_resource("/fs/{filename}")
resource.add_route("GET", gridfs_handler)
resource.add_route("HEAD", gridfs_handler)

app_handler = app.make_handler()
server = loop.create_server(app_handler, port=80)

By default, requests’ If-Modified-Since headers are honored, but no specific cache-control timeout is sent to clients. Thus each request for a GridFS file requires a quick check of the file’s uploadDate in MongoDB. Pass a custom get_cache_time() to customize this.

Parameters:
motor.aiohttp.get_cache_time(filename, modified, mime_type)

Override to customize cache control behavior.

Return a positive number of seconds to trigger aggressive caching or 0 to mark resource as cacheable, only. 0 is the default.

For example, to allow image caching:

def image_cache_time(filename, modified, mime_type):
    if mime_type.startswith('image/'):
        return 3600

    return 0

client = AsyncIOMotorClient()
gridfs_handler = AIOHTTPGridFS(client.my_database,
                               get_cache_time=image_cache_time)
Parameters:

  • filename: A string, the URL portion matching {filename} in the URL pattern

  • modified: A datetime, when the matching GridFS file was created

  • mime_type: The file’s type, a string like “application/octet-stream”

motor.aiohttp.get_gridfs_file(bucket, filename, request)

Override to choose a GridFS file to serve at a URL.

By default, if a URL pattern like /fs/{filename} is mapped to this AIOHTTPGridFS, then the filename portion of the URL is used as the filename, so a request for “/fs/image.png” results in a call to AsyncIOMotorGridFSBucket.open_download_stream_by_name() with “image.png” as the filename argument. To customize the mapping of path to GridFS file, override get_gridfs_file and return a asyncio.Future that resolves to a AsyncIOMotorGridOut.

For example, to retrieve the file by _id instead of filename:

def get_gridfile_by_id(bucket, filename, request):
    # "filename" is interpreted as _id instead of name.
    # Return a Future AsyncIOMotorGridOut.
    return bucket.open_download_stream(file_id=filename)

client = AsyncIOMotorClient()
gridfs_handler = AIOHTTPGridFS(client.my_database,
                               get_gridfs_file=get_gridfile_by_id)
Parameters:
motor.aiohttp.set_extra_headers(response, gridout)

Override to modify the response before sending to client.

For example, to allow image caching:

def gzip_header(response, gridout):
    response.headers['Content-Encoding'] = 'gzip'

client = AsyncIOMotorClient()
gridfs_handler = AIOHTTPGridFS(client.my_database,
                               set_extra_headers=gzip_header)
Parameters: