Nplusone

Warnings

• gotcha Nplusone is intended for development and testing environments only. It should NOT be deployed to production environments as it can introduce performance overhead.
  Fix: Ensure nplusone is only included in your development or test dependencies and configurations (e.g., `requirements-dev.txt`, `DEBUG=True` blocks in Django settings).
• gotcha By default, nplusone logs warnings. To make it raise an `NPlusOneError` (useful for failing tests), you need to set the `NPLUSONE_RAISE` configuration option (e.g., via an environment variable or Django settings).
  Fix: Set `NPLUSONE_RAISE = True` in your application's configuration or as an environment variable (e.g., `os.environ['NPLUSONE_RAISE'] = 'True'`). You can also specify the exception type using `NPLUSONE_ERROR`.
• gotcha When integrating with specific frameworks like Django or Flask-SQLAlchemy, remember to add the relevant middleware (`NPlusOneMiddleware`) and configure `INSTALLED_APPS` (for Django) to enable automatic detection within the request-response cycle.
  Fix: For Django, add `'nplusone.ext.django'` to `INSTALLED_APPS` and `'nplusone.ext.django.NPlusOneMiddleware'` to `MIDDLEWARE`. For generic WSGI apps or outside HTTP requests, use the `Profiler` context manager and import the relevant ORM extension (e.g., `import nplusone.ext.sqlalchemy`).

Install

• pip install nplusone Install nplusone

Imports

• Profiler

  from nplusone.core.profiler import Profiler

  Used for generic profiling outside of framework integrations.
• NPlusOneMiddleware

  from nplusone.ext.django import NPlusOneMiddleware

  Used for Django framework integration.
• ext.sqlalchemy

  import nplusone.ext.sqlalchemy

  Initializes SQLAlchemy integration within the profiler.

Quickstart

This quickstart demonstrates how to use `nplusone` with SQLAlchemy. It sets up a simple ORM model, adds some data, and then uses the `Profiler` context manager to detect N+1 queries when accessing related `Artist` objects within a loop without eager loading. Warnings will be logged to the console.

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

# Configure a logger to capture nplusone warnings
logger = logging.getLogger('nplusone')
logger.setLevel(logging.WARN)
handler = logging.StreamHandler()
logger.addHandler(handler)

# --- Simulate an SQLAlchemy setup ---
from sqlalchemy import create_engine, Column, Integer, String, ForeignKey
from sqlalchemy.orm import sessionmaker, relationship
from sqlalchemy.ext.declarative import declarative_base

Base = declarative_base()

class Artist(Base):
    __tablename__ = 'artists'
    id = Column(Integer, primary_key=True)
    name = Column(String)
    songs = relationship('Song', back_populates='artist')

class Song(Base):
    __tablename__ = 'songs'
    id = Column(Integer, primary_key=True)
    title = Column(String)
    artist_id = Column(Integer, ForeignKey('artists.id'))
    artist = relationship('Artist', back_populates='songs')

engine = create_engine('sqlite:///:memory:')
Base.metadata.create_all(engine)
Session = sessionmaker(bind=engine)
session = Session()

# Add some data
artist1 = Artist(name='Artist One')
artist2 = Artist(name='Artist Two')
session.add_all([artist1, artist2])
session.commit()

song1 = Song(title='Song A', artist=artist1)
song2 = Song(title='Song B', artist=artist1)
song3 = Song(title='Song C', artist=artist2)
session.add_all([song1, song2, song3])
session.commit()

# --- Nplusone profiling ---
print('--- Starting nplusone profiling ---')
with Profiler():
    songs = session.query(Song).all()
    print(f'Fetched {len(songs)} songs.')
    # This will trigger N+1 queries if artists are not eagerly loaded
    for song in songs:
        print(f'  Song: {song.title}, Artist: {song.artist.name}')

print('--- Profiling complete ---')

# Example of how to raise an NPlusOneError for tests (optional)
# from nplusone.core.exceptions import NPlusOneError
# import os
# os.environ['NPLUSONE_RAISE'] = 'True' # Set this environment variable or config option
# try:
#     with Profiler():
#         songs = session.query(Song).all()
#         for song in songs:
#             _ = song.artist.name
# except NPlusOneError as e:
#     print(f'Caught expected NPlusOneError: {e}')
# os.environ['NPLUSONE_RAISE'] = '' # Reset for other tests