django-ninja-search

A lightweight decorator to add filtering, searching, and sorting support to Django Ninja view functions.

✨ Features

• Add full-text search and ordering with a decorator
• Optional schema-based filtering
• Works seamlessly with Django ORM and Django Ninja

📦 Installation

pip install django-ninja-search

Or with Poetry:

poetry add django-ninja-search

🚀 Usage

1. Define your model (example)

# models.py
class Item(models.Model):
    name = models.CharField(max_length=100)
    description = models.TextField()

2. Add the decorator to your view

# views.py
from ninja import Query
from ninja_schema import Schema
from ninja_search.searching import searching

class ItemFilterSchema(Schema):
    pass  # You can define extra filters here if needed

@searching(
    filterSchema=ItemFilterSchema,
    search_fields=["name", "description"],
    sort_fields=["name", "description"],
)
def list_items(request, filters: ItemFilterSchema = Query(...)):
    return Item.objects.all()

This enables:

• /?search=banana → filters by search text
• /?ordering=name → sorts results

🧪 Running Tests

poetry install
poetry run pytest --cov=ninja_search --cov-report=html

Open the coverage report in your browser:

open htmlcov/index.html  # macOS
xdg-open htmlcov/index.html  # Linux

📤 Publishing

✅ Publish to Test PyPI

poetry config repositories.testpypi https://test.pypi.org/legacy/
poetry publish --build -r testpypi

🚀 Publish to PyPI

poetry config repositories.pypi https://upload.pypi.org/legacy/
poetry config pypi-token.pypi <your-token-here>
poetry publish --build -r pypi

🔁 Versioning and Release

Before releasing a new version:

poetry version patch  # or minor / major
poetry build
# Publish using one of the methods above

# Tag and push
NEW_VERSION=$(poetry version -s)
git tag v$NEW_VERSION
git push origin v$NEW_VERSION
git push origin main

📚 Metadata & Compatibility

Python Versions: 3.10, 3.11, 3.12, 3.13 Django Versions: >=5.1.0 License: MIT Project URL: https://github.com/anandrnair547/django-ninja-search PyPI: https://pypi.org/project/django-ninja-search/

🤝 Contributing

We welcome contributions! See the Contributing Guide for setup instructions, test coverage tips, release workflow, and versioning guidance.

🧾 License

MIT © Anand R Nair

AI Development Setup (Optional)

This repo uses an agent-setup submodule — a shared AI agent framework with agents, workflows, and skills for Claude Code, Cursor, Copilot, and other AI tools.

After cloning, initialize it if you use AI-assisted development:

git submodule update --init --recursive

This is optional — the submodule is only needed for AI tooling. The app runs fine without it.

To pull the latest agent framework updates:

git submodule update --remote agent-setup