nplusone Documentation

The easiest way to install nplusone is using pip from the Python Package Index (PyPI).

$ pip install -U nplusone

If you need to install from source, you can clone the repository from GitHub or download the source distribution (tarball or zipball). Once you have the source files locally, run the setup script to install it into your site-packages.

# Clone the repository
$ git clone https://github.com/jmcarp/nplusone.git

# Install from the cloned directory
$ python setup.py install

To use nplusone with Flask-SQLAlchemy, wrap your application instance with the NPlusOne class. You can configure logging settings using the standard Flask app.config dictionary.

from flask import Flask
from nplusone.ext.flask_sqlalchemy import NPlusOne

app = Flask(__name__)

# Optional configuration
app.config['NPLUSONE_LOGGER'] = logging.getLogger('app.nplusone')
app.config['NPLUSONE_LOG_LEVEL'] = logging.ERROR

NPlusOne(app)

To use nplusone with Django (supports Django >= 1.8), add the extension to your INSTALLED_APPS and add the NPlusOneMiddleware to your MIDDLEWARE setting. You can optionally configure logging via NPLUSONE_LOGGER and NPLUSONE_LOG_LEVEL.

INSTALLED_APPS = (
    ...
    'nplusone.ext.django',
)

MIDDLEWARE = (
    'nplusone.ext.django.NPlusOneMiddleware',
    ...
)

# Optional logging configuration
import logging
NPLUSONE_LOGGER = logging.getLogger('nplusone')
NPLUSONE_LOG_LEVEL = logging.WARN

For other WSGI-compliant frameworks (like Bottle), wrap the application with NPlusOneMiddleware. You must also explicitly import the relevant ORM extension (e.g., nplusone.ext.sqlalchemy) to ensure the profiler is active.

import bottle
from nplusone.ext.wsgi import NPlusOneMiddleware
import nplusone.ext.sqlalchemy

app = NPlusOneMiddleware(bottle.app())

Install the library using pip to detect n+1 queries in SQLAlchemy, Peewee, and Django ORM.

Note: nplusone should only be used for development and should not be deployed to production environments. It supports Python >= 2.7 or >= 3.3.

pip install -U nplusone

To globally ignore specific models or fields, use the NPLUSONE_WHITELIST option. You can use exact names or fnmatch patterns.

Django format:

NPLUSONE_WHITELIST = [
    {'label': 'n_plus_one', 'model': 'myapp.MyModel'},
    {'model': 'myapp.*'}
]

Flask configuration format:

app.config['NPLUSONE_WHITELIST'] = [
    {'label': 'unused_eager_load', 'model': 'MyModel', 'field': 'my_field'}
]

By default, nplusone logs warnings. To force automated tests to fail when an n+1 query or unnecessary eager load is detected, set NPLUSONE_RAISE to True. You can also customize the exception type using NPLUSONE_ERROR.

# Django config
NPLUSONE_RAISE = True

# Flask config
app.config['NPLUSONE_RAISE'] = True

To suppress specific types of notifications within a specific block of code, use the signals.ignore context manager.

from nplusone.core import signals

with signals.ignore(signals.lazy_load):
    # code that performs lazy-loaded rows
    ...

If you need to use nplusone outside of a request-response cycle (e.g., in a script or background task), use the profiler.Profiler context manager. You must import the relevant ORM extension for the profiler to work.

from nplusone.core import profiler
import nplusone.ext.sqlalchemy

with profiler.Profiler():
    # Your code that performs ORM operations
    ...