Motor

Motor is MongoDB’s full-featured, non-blocking Python driver, presenting a coroutine-based API for asyncio and Tornado applications built on top of PyMongo. It handles connection pooling, replica set discovery, and GridFS streaming without blocking the event loop, so high-concurrency services can issue MongoDB operations alongside other async I/O.

As of May 2025, Motor is deprecated by MongoDB in favor of the GA PyMongo Async API: it receives bug fixes only until May 2026 and critical fixes only until May 2027. It remains widely deployed in existing asyncio/Tornado codebases, but MongoDB recommends new projects use PyMongo’s native async support instead.

What You Get

• Coroutine-based clients (AsyncIOMotorClient) for asyncio, plus a Tornado-specific client
• Non-blocking cursors, transactions, and change-stream support built on PyMongo’s core driver
• GridFS support (motor.motor_gridfs) for streaming large files without blocking the event loop
• Full static typing with .pyi stubs and a py.typed marker for type-checked codebases
• Optional AWS authentication extras for MongoDB Atlas IAM-based connections

Common Use Cases

• Building async REST/GraphQL APIs (FastAPI, aiohttp) that read and write MongoDB without blocking the event loop
• High-throughput services processing tens of thousands of MongoDB requests per second on asyncio
• Streaming large file uploads/downloads to and from MongoDB via GridFS in async web apps
• Existing Tornado applications that need non-blocking MongoDB access

Under The Hood

Architecture: Motor is a thin async wrapper generated over PyMongo’s synchronous core — metaprogramming.py and core.py dynamically wrap PyMongo’s blocking methods into coroutines that delegate actual socket I/O to a thread pool (or, for newer versions, native async transport), while motor_asyncio.py and motor_tornado.py provide framework-specific client classes. Tech Stack: pure Python (requires-python >= 3.10), built with hatchling, depending directly on pymongo with optional aws extras for IAM auth; ships full type stubs (.pyi files) and a py.typed marker. Code Quality: the repo has a substantial test/ suite split into asyncio_tests and tornado_tests, plus test_mypy_fails.py and test_typing.py for type-checking regressions — indicating disciplined test coverage across both supported frameworks. API Design: the API deliberately mirrors PyMongo’s synchronous method names and signatures so developers already familiar with PyMongo can adopt Motor with minimal relearning, though the project itself is now deprecated in favor of PyMongo’s native async API, which offers the same familiarity without a separate wrapper package.