Motor-Stubs

1.7.1 verified Sat May 09 auth: no python

Type stubs for Motor (async MongoDB driver) providing type hints for Motor classes. This package enables static type checking of Motor-based code in projects using mypy or pyright. It is maintained separately from Motor and has a version 1.7.1 as of last update, targeting Python >=3.9. Release cadence is irregular.

pip install motor-stubs

Common errors

error Module 'motor.motor_asyncio' has no attribute 'AsyncIOMotorClient' ↓

cause motor-stubs not installed or not recognized by type checker

fix

Install motor-stubs: pip install motor-stubs. If using mypy, ensure stubs are automatically discovered or explicitly configured.

error Cannot find implementation or library stub for module 'motor' ↓

cause motor-stubs missing or mypy can't locate stubs

fix

pip install motor-stubs; if using mypy check MYPYPATH or stub configuration.

error Argument 1 to 'find_one' of 'Collection' has incompatible type 'Dict[str, int]'; expected 'Mapping[str, Any] | None' ↓

cause motor-stubs type annotations are stricter than pymongo; dict literal not accepted directly

fix

Cast or use a variable: filter = {'_id': 1}; await collection.find_one(filter)

Warnings

breaking Breaking change in v1.0.0: AsyncIOMotorCursor type annotations changed; methods like .to_list() now expect Optional arguments ↓

fix Update code to match stubs; ensure None is handled explicitly for optional parameters

gotcha Stubs may not cover all Motor internals; mypy may report missing imports for certain attributes ↓

fix Use # type: ignore[attr-defined] or contribute to stubs

deprecated Some pymongo stubs (pymongo-stubs) are deprecated in favor of motor-stubs; motor-stubs now includes pymongo types ↓

fix Replace 'from pymongo_stubs import ...' with motor-stubs; ensure only motor-stubs is installed

Imports

AsyncIOMotorClient
```
from motor.motor_asyncio import AsyncIOMotorClient
```
No alternative import; motor stubs mirror actual motor imports

Quickstart

Basic Motor async usage; stubs provide type checking.

import asyncio
from motor.motor_asyncio import AsyncIOMotorClient

async def main():
    client = AsyncIOMotorClient('mongodb://localhost:27017')
    db = client.test_database
    collection = db.test_collection
    doc = await collection.find_one({'_id': 1})
    print(doc)

asyncio.run(main())