django-simple-search 1.0.2
Recurring event tools for django
License: BSD License

Django simple search provides the same functionality and convenience
that ``search_fields`` does in the django admin.

See http://gregbrown.co.nz/code/django-simple-search/ for more details.

|Circle CI| |codecov| |Latest Version|

Installation
------------

Download the source from
https://pypi.python.org/pypi/django-simple-search/ and run
``python setup.py install``, or:

::

    > pip install django-simple-search

Django 1.8 or higher is required.

Quick start
-----------

::

    from simple_search import search_filter
    from .models import MyModel

    query = 'test'
    search_fields = ['^title', 'description', '=id']
    f = search_filter(search_fields, query)
    filtered = MyModel.objects.filter(f)

For convenience you can create a search form class via the provided
factory:

::

    from .models import MyModel
    from simple_search import search_form_factory

    SearchForm = search_form_factory(MyModel.objects.all(),
                                     ['^title', 'description'])

Reference
---------

``simple_search.search_filter(search_fields, query)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Given a list of ``search_fields`` to search on and a query, return a
``models.Q`` object which can be used to filter a queryset.

``search_fields`` behaves exactly like the django admin
`search\_fields <https://docs.djangoproject.com/en/1.10/ref/contrib/admin/#django.contrib.admin.ModelAdmin.search_fields>`__
option. Example:

::

    search_fields = [
        # match from the start of the title field
        '^title',

        # match anywhere within the description field
        'description',

        # match from the start of the related category's title field
        '^category__title',

        # exact match on object id
        '=id'
    ]

``simple_search.search_form_factory(queryset, search_fields)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Create a search form class which will filter ``queryset`` according to
``search_fields`` and the form field ``q``. Example:

::

    # forms.py
    from .models import MyModel
    from simple_search import search_form_factory

    SearchForm = search_form_factory(MyModel.objects.all(),
                                     ['^title', 'description'])

    # views.py
    from django.shortcuts import render
    from .forms import SearchForm

    @render('search.html')
    def search(request):
        form = SearchForm(request.GET or {})
        if form.is_valid():
            results = form.get_queryset()
        else:
            results = MyModel.objects.none()

        return {
            'form': form,
            'results': results,
        }

Running tests
-------------

Use tox (https://pypi.python.org/pypi/tox):

::

    > pip install tox
    > cd path-to/django-simple-search
    > tox

.. |Circle CI| image:: https://circleci.com/gh/gregplaysguitar/django-simple-search.svg?style=svg
   :target: https://circleci.com/gh/gregplaysguitar/django-simple-search
.. |codecov| image:: https://codecov.io/gh/gregplaysguitar/django-simple-search/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/gregplaysguitar/django-simple-search
.. |Latest Version| image:: https://img.shields.io/pypi/v/django-simple-search.svg?style=flat
   :target: https://pypi.python.org/pypi/django-simple-search/