motor.aiohttp - Integrate Motor with the aiohttp web framework

Warning

As of May 14th, 2025, Motor is deprecated in favor of the GA release of the PyMongo Async API. No new features will be added to Motor, and only bug fixes will be provided until it reaches end of life on May 14th, 2026. After that, only critical bug fixes will be made until final support ends on May 14th, 2027. We strongly recommend migrating to the PyMongo Async API while Motor is still supported. For help transitioning, see the Migrate to PyMongo Async 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: