Mongo Ninja Python

1.11.1.7 verified Fri May 01 auth: no python

A Python client for MongoDB that provides a simplified query builder and ORM-like interface. Current version 1.11.1.7, actively maintained with frequent updates.

pip install mongo-ninja-python

Common errors

error ImportError: No module named 'mongo_ninja' ↓

cause Package is installed as 'mongo-ninja-python' but imported with underscores.

fix

Ensure the package is installed: pip install mongo-ninja-python. Then import with from mongo_ninja import NinjaClient.

error TypeError: __init__() got an unexpected keyword argument 'db' ↓

cause Breaking change in v1.11.0: parameter renamed from 'db' to 'database'.

fix

Update your code to use database='your_db_name' instead of db='your_db_name'.

Warnings

breaking In v1.11.0, the 'db' parameter was renamed to 'database' in NinjaClient constructor. Old code passing 'db=...' will raise TypeError. ↓

fix Use `database='...'` instead of `db='...'`.

deprecated The `find_one()` method with positional arguments is deprecated. Use keyword arguments for query filters. ↓

fix Replace `collection.find_one({'name': 'Alice'})` with `collection.find_one(filter={'name': 'Alice'})`.

gotcha Automatic connection pooling may cause stale connections after network interruptions. Configure `maxPoolSize` and `serverSelectionTimeoutMS` explicitly in production. ↓

fix Pass `options={'maxPoolSize': 10, 'serverSelectionTimeoutMS': 5000}` to NinjaClient.

Imports

NinjaClient

wrong

from mongo_ninja_python import NinjaClient

correct

from mongo_ninja import NinjaClient

Package name uses underscores, not hyphens

QueryBuilder

wrong

from mongo_ninja import QueryBuilder

correct

from mongo_ninja.query import QueryBuilder

QueryBuilder is in the query submodule

Quickstart

Connect to a local MongoDB instance and insert a document into the users collection.

from mongo_ninja import NinjaClient

client = NinjaClient(uri='mongodb://localhost:27017', db='test')
collection = client.collection('users')
result = collection.insert_one({'name': 'Alice', 'age': 30})
print(result.inserted_id)