django-find 1.0.1__tar.gz

django_find-1.0.1/.gitignore

@@ -0,0 +1,6 @@
+*.py[co]
+*.egg-info
+*.swp
+dist
+build/
+_build/

django_find-1.0.1/LICENSE

@@ -0,0 +1,17 @@
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_find-1.0.1/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: django-find
+Version: 1.0.1
+Summary: Simple but powerful search/filter functionality for Django projects
+Project-URL: Homepage, https://github.com/knipknap/django-find
+Project-URL: Repository, https://github.com/knipknap/django-find
+Project-URL: Issues, https://github.com/knipknap/django-find/issues
+Author-email: Samuel Abels <knipknap@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: django,filter,find,json,query,search,sql
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.1
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Text Processing :: Filters
+Requires-Python: >=3.10
+Requires-Dist: dateparser
+Requires-Dist: django>=4.2
+Description-Content-Type: text/markdown
+
+# django-find
+
+[![Build Status](https://travis-ci.org/knipknap/django-find.svg?branch=master)](https://travis-ci.org/knipknap/django-find)
+[![Coverage Status](https://coveralls.io/repos/github/knipknap/django-find/badge.svg?branch=master)](https://coveralls.io/github/knipknap/django-find?branch=master)
+[![Code Climate](https://lima.codeclimate.com/github/knipknap/django-find/badges/gpa.svg)](https://lima.codeclimate.com/github/knipknap/django-find)
+[![Documentation Status](https://readthedocs.org/projects/django-find/badge/?version=latest)](http://django-find.readthedocs.io/en/latest/?badge=latest)
+
+## Summary
+
+**django-find** is a Django app that makes it easy to add complex
+search/filter functionality for the models in your project.
+It supports two different ways to search your Django models:
+Query-based, or JSON-based.
+
+**django-find** is not a full text search engine, it searches the fields
+of your models. In other words, it filters on your models and provides
+tabular data as a result.
+
+## Features
+
+### Query-based search
+
+By query-based, we mean that you can use statements like these
+to search your models:
+
+```
+author:"robert frost" and (title:road or chapter:2)
+```
+
+### Add a search field to your template using a single tag
+
+```
+{% load find_tags %}
+{% find object_list %}
+{% for obj in object_list %}
+  {{ obj.name }}
+{% endfor %}
+```
+
+(object\_list is a queryset that is passed to the template)
+
+### Query in your code
+
+Just add the Searchable mixin:
+
+```python
+from django_find import Searchable
+
+class Author(models.Model, Searchable):
+    name = models.CharField("Author Name", max_length=10)
+    ...
+```
+
+And you are good to go:
+
+```python
+# Query-based search returns a standard Django QuerySet that you
+# can .filter() and work with as usual.
+query = Book.by_query('author:"robert frost" and title:"the road"')
+
+# You can also get a Django Q object for the statements.
+q_obj = Book.q_from_query('author:"robert frost" and title:"the road"')
+```
+
+### Query using JSON
+
+To make it easy to do complex searches spanning multiple models, JSON-based
+query method is provided. It allows your to make custom searches like these:
+
+![Custom Search](https://raw.githubusercontent.com/knipknap/django-find/master/docs/_static/custom.png)
+
+For this, a JSON-based search functionality is provided:
+
+```
+{
+    "Author":{"name":[[["equals","test"]]]},
+    "Book": {"title":[[["notcontains","c"]]]},
+    "Chapter": {"content":[[["startswith","The "]]]}
+}
+```
+
+django-find is smart in figuring out how to join those models
+together and return a useful result.
+In your code, you can load the JSON and get back the search
+result:
+
+```python
+# JSON-based search exhausts what Django's ORM can do, so it does
+# not return a Django QuerySet, but a row-based PaginatedRawQuerySet:
+query, field_list = Book.by_json_raw('''{
+    "Chapter": {"title":[[["contains","foo"]]]}
+}''')
+print('|'.join(field_list))
+for row in query:
+    print('|'.join(row))
+```
+
+## Documentation
+
+Full documentation, including installation instructions, is here:
+
+http://django-find.readthedocs.io

django_find-1.0.1/README.md

@@ -0,0 +1,102 @@
+# django-find
+
+[![Build Status](https://travis-ci.org/knipknap/django-find.svg?branch=master)](https://travis-ci.org/knipknap/django-find)
+[![Coverage Status](https://coveralls.io/repos/github/knipknap/django-find/badge.svg?branch=master)](https://coveralls.io/github/knipknap/django-find?branch=master)
+[![Code Climate](https://lima.codeclimate.com/github/knipknap/django-find/badges/gpa.svg)](https://lima.codeclimate.com/github/knipknap/django-find)
+[![Documentation Status](https://readthedocs.org/projects/django-find/badge/?version=latest)](http://django-find.readthedocs.io/en/latest/?badge=latest)
+
+## Summary
+
+**django-find** is a Django app that makes it easy to add complex
+search/filter functionality for the models in your project.
+It supports two different ways to search your Django models:
+Query-based, or JSON-based.
+
+**django-find** is not a full text search engine, it searches the fields
+of your models. In other words, it filters on your models and provides
+tabular data as a result.
+
+## Features
+
+### Query-based search
+
+By query-based, we mean that you can use statements like these
+to search your models:
+
+```
+author:"robert frost" and (title:road or chapter:2)
+```
+
+### Add a search field to your template using a single tag
+
+```
+{% load find_tags %}
+{% find object_list %}
+{% for obj in object_list %}
+  {{ obj.name }}
+{% endfor %}
+```
+
+(object\_list is a queryset that is passed to the template)
+
+### Query in your code
+
+Just add the Searchable mixin:
+
+```python
+from django_find import Searchable
+
+class Author(models.Model, Searchable):
+    name = models.CharField("Author Name", max_length=10)
+    ...
+```
+
+And you are good to go:
+
+```python
+# Query-based search returns a standard Django QuerySet that you
+# can .filter() and work with as usual.
+query = Book.by_query('author:"robert frost" and title:"the road"')
+
+# You can also get a Django Q object for the statements.
+q_obj = Book.q_from_query('author:"robert frost" and title:"the road"')
+```
+
+### Query using JSON
+
+To make it easy to do complex searches spanning multiple models, JSON-based
+query method is provided. It allows your to make custom searches like these:
+
+![Custom Search](https://raw.githubusercontent.com/knipknap/django-find/master/docs/_static/custom.png)
+
+For this, a JSON-based search functionality is provided:
+
+```
+{
+    "Author":{"name":[[["equals","test"]]]},
+    "Book": {"title":[[["notcontains","c"]]]},
+    "Chapter": {"content":[[["startswith","The "]]]}
+}
+```
+
+django-find is smart in figuring out how to join those models
+together and return a useful result.
+In your code, you can load the JSON and get back the search
+result:
+
+```python
+# JSON-based search exhausts what Django's ORM can do, so it does
+# not return a Django QuerySet, but a row-based PaginatedRawQuerySet:
+query, field_list = Book.by_json_raw('''{
+    "Chapter": {"title":[[["contains","foo"]]]}
+}''')
+print('|'.join(field_list))
+for row in query:
+    print('|'.join(row))
+```
+
+## Documentation
+
+Full documentation, including installation instructions, is here:
+
+http://django-find.readthedocs.io

django_find-1.0.1/django_find/__init__.py

@@ -0,0 +1,4 @@
+from .models import Searchable
+from .version import __version__
+
+__all__ = ["Searchable", "__version__"]

django_find-1.0.1/django_find/apps.py

@@ -0,0 +1,5 @@
+from django.apps import AppConfig
+
+class DjangoFindConfig(AppConfig):
+    name = 'django_find'
+    verbose_name = "Django Find"

django_find-1.0.1/django_find/dom.py

@@ -0,0 +1,127 @@
+from builtins import str
+from .tree import Node
+
+operators = [
+    'contains',
+    'equals',
+    'startswith',
+    'endswith',
+    'regex',
+    'gt',
+    'gte',
+    'lt',
+    'lte',
+    'any'
+]
+
+class Group(Node):
+    def translate_term_names(self, name_map):
+        def translate(dom_obj):
+            dom_obj.name = name_map.get(dom_obj.name, dom_obj.name)
+        self.each(translate, Term)
+
+    def get_term_names(self):
+        """
+        Returns a flat list of the names of all Terms in the query, in
+        the order in which they appear. Filters duplicates.
+        """
+        field_names = []
+        def collect_field_names(dom_obj):
+            if not dom_obj.name in field_names:
+                field_names.append(dom_obj.name)
+        self.each(collect_field_names, Term)
+        return field_names
+
+    def auto_leave_scope(self):
+        return False
+
+    def optimize(self):
+        children = [c.optimize() for c in self.children]
+        self.children = [c for c in children if c is not None]
+        children = []
+        for child in self.children:
+            if type(child) == type(self):
+                for grandchild in child.children:
+                    children.append(grandchild)
+            else:
+                children.append(child)
+        self.children = children
+        if not self.children and not self.is_root:
+            return None
+        if len(self.children) == 1 and not self.is_root:
+            return self.children[0]
+        return self
+
+    def serialize(self, strategy):
+        results = [c.serialize(strategy) for c in self.children]
+        if self.is_root:
+            return strategy.logical_root_group(self, results)
+        return strategy.logical_group(results)
+
+class And(Group):
+    @classmethod
+    def is_logical(self):
+        return True
+
+    @classmethod
+    def precedence(self):
+        return 2
+
+    def serialize(self, strategy):
+        return strategy.logical_and(c.serialize(strategy)
+                                    for c in self.children)
+
+class Or(Group):
+    @classmethod
+    def is_logical(self):
+        return True
+
+    @classmethod
+    def precedence(self):
+        return 1
+
+    def serialize(self, strategy):
+        return strategy.logical_or(c.serialize(strategy)
+                                   for c in self.children)
+
+class Not(Group):
+    @classmethod
+    def precedence(self):
+        return 3
+
+    def auto_leave_scope(self):
+        return True
+
+    def optimize(self):
+        children = [c.optimize() for c in self.children]
+        self.children = [c for c in children if c is not None]
+        if not self.children and not self.is_root:
+            return None
+        return self
+
+    def serialize(self, strategy):
+        children = [c.serialize(strategy) for c in self.children]
+        return strategy.logical_not(children)
+
+class Term(Node):
+    def __init__(self, name, operator, data):
+        assert operator in operators, "unsupported operator {}".format(operator)
+        Node.__init__(self)
+        self.name = name
+        self.operator = str(operator)
+        self.data = str(data)
+
+    def optimize(self):
+        return self
+
+    def each(self, func, node_type):
+        if node_type is None or isinstance(self, node_type):
+            func(self)
+
+    def dump(self, indent=0):
+        return [(indent * '  ')
+                + self.__class__.__name__ + ': '
+                + self.name + ' ' + self.operator + ' ' + repr(self.data)]
+
+    def serialize(self, strategy):
+        return strategy.term(self.name, self.operator, self.data)

django_find-1.0.1/django_find/handlers.py

@@ -0,0 +1,75 @@
+from django.db import models
+
+class FieldHandler(object):
+    """
+    Abstract base type for all field handlers.
+
+    A field handler is an object that you can use to define custom
+    behavior when searching a field of a model.
+
+    You might want to use a field handler if you are using a custom
+    model field, or if your query contains information that
+    requires client-side processing before being passed to
+    the database.
+    """
+    db_type = None
+
+    @classmethod
+    def handles(cls, model, field):
+        raise NotImplemented
+
+    @classmethod
+    def prepare(cls, value):
+        return value
+
+class StrFieldHandler(FieldHandler):
+    db_type = 'STR'
+
+    @classmethod
+    def handles(cls, model, field):
+        return isinstance(field, (models.CharField, models.TextField))
+
+class LowerCaseStrFieldHandler(StrFieldHandler):
+    db_type = 'LCSTR'
+
+class IPAddressFieldHandler(LowerCaseStrFieldHandler):
+    @classmethod
+    def handles(cls, model, field):
+        return isinstance(field, models.GenericIPAddressField)
+
+class BooleanFieldHandler(FieldHandler):
+    db_type = 'BOOL'
+
+    @classmethod
+    def handles(cls, model, field):
+        return isinstance(field, models.BooleanField)
+
+class IntegerFieldHandler(FieldHandler):
+    db_type = 'INT'
+
+    @classmethod
+    def handles(cls, model, field):
+        return isinstance(field, (models.IntegerField, models.AutoField))
+
+class DateFieldHandler(FieldHandler):
+    db_type = 'DATE'
+
+    @classmethod
+    def handles(cls, model, field):
+        return isinstance(field, models.DateField)
+
+class DateTimeFieldHandler(FieldHandler):
+    db_type = 'DATETIME'
+
+    @classmethod
+    def handles(cls, model, field):
+        return isinstance(field, models.DateTimeField)
+
+type_registry = [
+        LowerCaseStrFieldHandler,
+        IPAddressFieldHandler,
+        BooleanFieldHandler,
+        IntegerFieldHandler,
+        DateTimeFieldHandler,
+        DateFieldHandler,
+]

django_find-1.0.1/django_find/model_helpers.py

@@ -0,0 +1,14 @@
+from .serializers.sql import SQLSerializer
+
+def sql_from_dom(cls, dom, mode='SELECT', fullnames=None, extra_model=None):
+    if not fullnames:
+        fullnames = dom.get_term_names()
+    if not fullnames:
+        return 'SELECT * FROM (SELECT NULL) tbl WHERE 0', [], [] # Empty set
+    primary_cls = cls.get_primary_class_from_fullnames(fullnames)
+    serializer = SQLSerializer(primary_cls,
+                               mode=mode,
+                               fullnames=fullnames,
+                               extra_model=extra_model)
+    sql, args = dom.serialize(serializer)
+    return sql, args, fullnames