2.0.0 Release 🚀😄 adding new filters and capabilities to create your own filters

Author: elchicodepython

.gitignore

@@ -1 +1,6 @@
 __pycache__
+build/
+dist/
+*.egg-info
+*.swp
+*.pyc

README.md

@@ -14,7 +14,7 @@ pip install nocodb
 ### Client configuration
 ```python
 from nocodb.nocodb import NocoDBProject, APIToken, JWTAuthToken
-from nocodb.filters import InFilter, EqFilter
+from nocodb.filters import LikeFilter, EqFilter
 from nocodb.infra.requests_client import NocoDBRequestsClient
 
 
@@ -98,7 +98,7 @@ table_rows = client.table_row_list(project, table_name, params={'offset': 100})
 # Filter the query
 # Currently only one filter at a time is allowed. I don't know how to join
 # multiple conditions in nocodb dsl. If you know how please let me know :).
-table_rows = client.table_row_list(project, table_name, InFilter("name", "sam"))
+table_rows = client.table_row_list(project, table_name, LikeFilter("name", "%sam%"))
 table_rows = client.table_row_list(project, table_name, filter_obj=EqFilter("Id", 100))
 
 # Filter and count rows
@@ -114,22 +114,101 @@ row = client.table_row_detail(project, table_name, row_id)
 # Create a new row
 row_info = {
     "name": "my thoughts",
-    "content": "i'm going to buy samuel a beer because i love this module",
+    "content": "i'm going to buy samuel a beer 🍻 because I 💚 this module",
     "mood": ":)"
 }
 client.table_row_create(project, table_name, row_info)
 
 # Update a row
 row_id = 2
 row_info = {
-    "content": "i'm going to buy samuel a new car because i love this module",
+    "content": "i'm going to buy samuel a new car 🚙 because I 💚 this module",
 }
 client.table_row_update(project, table_name, row_id, row_info)
 
 # Delete a row (only if you've already bought me a beer)
 client.table_row_delete(project, table_name, row_id)
 ```
 
+### Available filters
+
+- EqFilter
+- EqualFilter (Alias of EqFilter)
+- NotEqualFilter
+- GreaterThanFilter
+- GreaterOrEqualFilter
+- LessThanFilter
+- LessOrEqualFilter
+- LikeFilter
+
+### Using custom filters
+
+Nocodb is evolving and new operators are coming with each release.
+
+Most of the basic operations are inside this package but you could need some new
+feature that could not be added yet.
+For those filters you can build your own.
+
+Example for basic filters:
+
+```python
+from nocodb.filters.factory import basic_filter_class_factory
+
+BasicFilter = basic_filter_class_factory('=')
+table_rows = client.table_row_list(project, table_name, BasicFilter('age', '16'))
+
+```
+
+You can find the updated list of all the available nocodb operators [here](https://docs.nocodb.com/developer-resources/rest-apis/#comparison-operators).
+
+In some cases you might want to write your own filter string as described in the previous link.
+For that cases you can use the less-semmantic RawFilter.
+
+```python
+from nocodb.filters.raw_filter import RawFilter
+
+table_rows = client.table_row_list(project, table_name, RawFilter('(birthday,eq,exactDate,2023-06-01)'))
+```
+
+In some cases we might want to have a file with some custom raw filters already defined by us.
+We can easily create custom raw filter classes using `raw_template_filter_class_factory`.
+
+```python
+from nocodb.filters.factory import raw_template_filter_class_factory
+
+BirthdayDateFilter = raw_template_filter_class_factory('(birthday,eq,exactDate,{})')
+ExactDateEqFilter = raw_template_filter_class_factory('({},eq,exactDate,{})')
+ExactDateOpFilter = raw_template_filter_class_factory('({},{op},exactDate,{})')
+
+table_rows = client.table_row_list(project, table_name, BirthdayDateFilter('2023-06-01'))
+table_rows = client.table_row_list(project, table_name, ExactDateEqFilter('column', '2023-06-01'))
+table_rows = client.table_row_list(project, table_name, ExactDateOpFilter('column', '2023-06-01', op='eq'))
+```
+
+```python
+from nocodb import filters
+
+# Basic filters...
+nick_filter = filters.EqFilter("nickname", "elchicodepython")
+country_filter = filters.EqFilter("country", "es")
+girlfriend_code = filters.EqFilter("gfcode", "404")
+current_mood_code = filters.EqFilter("moodcode", "418")
+
+# Combining filters using logical filters
+or_filter = filters.Or(nick_filter, country_filter)
+and_filter = filters.And(girlfriend_code, current_mood_code)
+
+# Negating filters with a Not filter
+not_me = filters.Not(filters.EqFilter("nickname", "elchicodepython"))
+
+# You can also combine combinations
+or_combined_filter = filters.Or(or_filter, and_filter)
+and_combined_filter = filters.And(or_filter, and_filter)
+
+```
+
+Credits to @MitPitt for asking this feature.
+
 ## Author notes
 
 I created this package to bootstrap some personal projects and I hope it

nocodb/__init__.py

@@ -1 +1 @@
-__version__ = "0.0.1"
+__version__ = "2.0.0"

nocodb/filters.py

@@ -0,0 +1,25 @@
+from .factory import basic_filter_class_factory
+from .logical import And, Not, Or
+
+EqFilter = basic_filter_class_factory("eq")
+EqualFilter = EqFilter
+NotEqualFilter = basic_filter_class_factory("neq")
+GreaterThanFilter = basic_filter_class_factory("gt")
+GreaterOrEqualFilter = basic_filter_class_factory("ge")
+LessThanFilter = basic_filter_class_factory("lt")
+LessOrEqualFilter = basic_filter_class_factory("le")
+LikeFilter = basic_filter_class_factory("like")
+
+__all__ = [
+    "And",
+    "Not",
+    "Or",
+    "EqFilter",
+    "EqualFilter",
+    "NotEqualFilter",
+    "GreaterThanFilter",
+    "GreaterOrEqualFilter",
+    "LessThanFilter",
+    "LessOrEqualFilter",
+    "LikeFilter",
+]

nocodb/filters/__init__.py

@@ -0,0 +1,15 @@
+from ..nocodb import WhereFilter
+
+from .raw_filter import RawTemplateFilter
+
+
+def basic_filter_class_factory(filter_name: str):
+    return raw_template_filter_class_factory('({},' + filter_name + ',{})')
+
+def raw_template_filter_class_factory(template: str):
+    class WrappedFilter(WhereFilter):
+        def __init__(self, *args, **kwargs):
+            self.__filter = RawTemplateFilter(template, *args, **kwargs)
+        def get_where(self) -> str:
+            return self.__filter.get_where()
+    return WrappedFilter

nocodb/filters/factory.py

@@ -0,0 +1,15 @@
+from .factory import basic_filter_class_factory, raw_template_filter_class_factory
+
+
+def test_basic_filter_class_factory():
+    FilterClass = basic_filter_class_factory('eq')
+    assert FilterClass('column', 'value').get_where() == '(column,eq,value)'
+
+
+def test_raw_template_filter_class_factory():
+    FilterClassWithoutParams = raw_template_filter_class_factory('()')
+    FilterClassWithParams = raw_template_filter_class_factory('({},{},{})')
+    FilterClassWithKwargs = raw_template_filter_class_factory('({},{op},{})')
+    assert FilterClassWithoutParams().get_where() == '()'
+    assert FilterClassWithParams('1', '2','3').get_where() == '(1,2,3)'
+    assert FilterClassWithKwargs('1', '2', op='eq').get_where() == '(1,eq,2)'

nocodb/filters/factory_test.py

@@ -0,0 +1,71 @@
+import pytest
+
+from .. import filters
+
+from ..nocodb import WhereFilter
+
+
+@pytest.mark.parametrize(
+    "filter_class, expected_operator",
+    [
+        (filters.EqFilter, "eq"),
+        (filters.EqualFilter, "eq"),
+        (filters.NotEqualFilter, "neq"),
+        (filters.GreaterOrEqualFilter, "ge"),
+        (filters.GreaterThanFilter, "gt"),
+        (filters.LessThanFilter, "lt"),
+        (filters.LessOrEqualFilter, "le"),
+        (filters.LikeFilter, "like"),
+    ],
+)
+def test_basic_filters_are_correctly_created(
+    filter_class: WhereFilter, expected_operator: str
+):
+    test_filter = filter_class("column", "value")
+    assert test_filter.get_where() == f"(column,{expected_operator},value)"
+
+
+def test_or_filter():
+    nick_filter = filters.EqFilter("nickname", "elchicodepython")
+    country_filter = filters.EqFilter("country", "es")
+    nick_or_country_filter = filters.Or(nick_filter, country_filter)
+    assert (
+        nick_or_country_filter.get_where()
+        == "((nickname,eq,elchicodepython)~or(country,eq,es))"
+    )
+
+
+def test_and_filter():
+    nick_filter = filters.EqFilter("nickname", "elchicodepython")
+    country_filter = filters.EqFilter("country", "es")
+    nick_or_country_filter = filters.And(nick_filter, country_filter)
+    assert (
+        nick_or_country_filter.get_where()
+        == "((nickname,eq,elchicodepython)~and(country,eq,es))"
+    )
+
+
+def test_combined_filter():
+    nick_filter = filters.EqFilter("nickname", "elchicodepython")
+    country_filter = filters.EqFilter("country", "es")
+    girlfriend_code = filters.EqFilter("gfcode", "404")
+    current_mood_code = filters.EqFilter("moodcode", "418")
+    or_filter = filters.Or(nick_filter, country_filter)
+    and_filter = filters.And(girlfriend_code, current_mood_code)
+    or_combined_filter = filters.Or(or_filter, and_filter)
+    and_combined_filter = filters.And(or_filter, and_filter)
+
+    assert (
+        or_combined_filter.get_where()
+        == "(((nickname,eq,elchicodepython)~or(country,eq,es))~or((gfcode,eq,404)~and(moodcode,eq,418)))"
+    )
+    assert (
+        and_combined_filter.get_where()
+        == "(((nickname,eq,elchicodepython)~or(country,eq,es))~and((gfcode,eq,404)~and(moodcode,eq,418)))"
+    )
+
+
+def test_not_filter():
+    me = filters.EqFilter("nickname", "elchicodepython")
+    not_me = filters.Not(me)
+    assert not_me.get_where() == "~not(nickname,eq,elchicodepython)"

nocodb/filters/filters_test.py

@@ -0,0 +1,34 @@
+from typing import List
+from ..nocodb import WhereFilter
+
+
+class Or(WhereFilter):
+    def __init__(self, *filters: List[WhereFilter]):
+        self.__filters = filters
+
+    def get_where(self) -> str:
+        return (
+            "("
+            + "~or".join([filter.get_where() for filter in self.__filters])
+            + ")"
+        )
+
+
+class And(WhereFilter):
+    def __init__(self, *filters: List[WhereFilter]):
+        self.__filters = filters
+
+    def get_where(self) -> str:
+        return (
+            "("
+            + "~and".join([filter.get_where() for filter in self.__filters])
+            + ")"
+        )
+
+
+class Not(WhereFilter):
+    def __init__(self, filter: WhereFilter):
+        self.__filter = filter
+
+    def get_where(self) -> str:
+        return "~not" + self.__filter.get_where()

nocodb/filters/logical.py

@@ -0,0 +1,19 @@
+from ..nocodb import WhereFilter
+
+
+class RawFilter(WhereFilter):
+    def __init__(self, raw: str):
+        self.__raw = raw
+
+    def get_where(self) -> str:
+        return self.__raw
+
+
+class RawTemplateFilter(WhereFilter):
+    def __init__(self, template: str, *args, **kwargs):
+        self.__template = template
+        self.__template_values = args
+        self.__template_kvalues = kwargs
+
+    def get_where(self) -> str:
+        return self.__template.format(*self.__template_values, **self.__template_kvalues)