features.rst

Motor Features

Non-Blocking

Motor is an asynchronous driver for MongoDB and Tornado. Motor never blocks Tornado's IOLoop while connecting to MongoDB or performing I/O.

Featureful

Motor wraps almost all of PyMongo's API and makes it non-blocking. For the few PyMongo features not implemented in Motor, see differences.

Convenient With tornado.gen

The tornado.gen module lets you use coroutines to simplify asynchronous code. Motor methods return Futures that are convenient to use with coroutines. See coroutine-example.

Timeouts

Unlike most non-blocking libraries for Tornado, Motor provides a convenient timeout interface:

@gen.coroutine
def f():
    try:
        document = yield db.collection.find_one(my_complex_query, network_timeout=5)
    except pymongo.errors.ConnectionFailure:
        # find_one took more than 5 seconds
        pass

Bounded Connection Growth

Motor has a default cap of 100 connections per host per ~motor.MotorClient or ~motor.MotorReplicaSetClient, configurable with the max_concurrent and max_wait_time options. Operations yield to the event loop while waiting for a spare connection to use.

Configurable IOLoops

Motor supports Tornado applications with multiple IOLoops. Pass the io_loop argument to ~motor.MotorClient or ~motor.MotorReplicaSetClient to configure the loop for a client instance.

Opens Connections Synchronously or Asynchronously

A ~motor.MotorClient or ~motor.MotorReplicaSetClient can be opened synchronously with ~motor.MotorClient.open_sync before your application begins serving requests, or can be opened asynchronously with ~motor.MotorClient.open to make the connection to MongoDB without blocking the Tornado IOLoop.

Streams Static Files from GridFS

Motor can stream data from GridFS to a Tornado RequestHandler using ~motor.MotorGridOut.stream_to_handler or the ~motor.web.GridFSHandler class.