Adding the ability to add filters to model views (#906)

Author: lorg

.gitignore

@@ -13,4 +13,5 @@ examples/
 .vscode/
 .uploads
 test.db
-coverage.xml
+coverage.xml
+dist/

docs/configurations.md

@@ -6,7 +6,7 @@ you can visit [API Reference](./api_reference/model_view.md).
 Let's say you've defined your SQLAlchemy models like this:
 
 ```python
-from sqlalchemy import Column, Integer, String, create_engine
+from sqlalchemy import Column, Integer, String, Boolean, create_engine
 from sqlalchemy.orm import declarative_base
 
 
@@ -23,6 +23,7 @@ class User(Base):
     id = Column(Integer, primary_key=True)
     name = Column(String)
     email = Column(String)
+    is_admin = Column(Boolean, default=False)
 
 
 Base.metadata.create_all(engine)  # Create tables
@@ -107,6 +108,7 @@ or list of the tuple for multiple columns.
 * `list_query`: A method with the signature of `(request) -> stmt` which can customize the list query.
 * `count_query`: A method with the signature of `(request) -> stmt` which can customize the count query.
 * `search_query`: A method with the signature of `(stmt, term) -> stmt` which can customize the search query.
+* `column_filters`: A list of objects that implement the `ColumnFilter` protocol to be displayed in the list page. See example below.
 
 !!! example
 
@@ -117,6 +119,7 @@ or list of the tuple for multiple columns.
         column_sortable_list = [User.id]
         column_formatters = {User.name: lambda m, a: m.name[:10]}
         column_default_sort = [(User.email, True), (User.name, False)]
+        column_filterable_list = [User.is_admin]
     ```
 
 
@@ -125,6 +128,92 @@ or list of the tuple for multiple columns.
     You can use the special keyword `"__all__"` in `column_list` or `column_details_list`
     if you don't want to specify all the columns manually. For example: `column_list = "__all__"`
 
+### ColumnFilter
+ 
+A ColumnFilter is a class that defines a filter for a column. A few standard filters are implemented in `sqladmin.filters` module. Here is an example of a generic ColumnFilter. Note that the fields `title`, `parameter_name`, `lookups` and `get_filtered_query` are required.
+
+```python
+class IsAdminFilter:
+    # Human-readable title which will be displayed in the
+    # right admin sidebar just above the filter options.
+    title = "Is Admin"
+
+    # Parameter for the filter that will be used in the URL query.
+    parameter_name = "is_admin"
+
+    def lookups(self, request, model) -> list[tuple[str, str]]:
+        """
+        Returns a list of tuples with the filter key and the human-readable label.
+        """
+        return [
+            ("all", "All"),
+            ("true", "Yes"),
+            ("false", "No"),
+        ]
+
+    def get_filtered_query(self, query, value):
+        """
+        Returns a filtered query based on the filter value.
+        """
+        if value == "true":
+            return query.filter(model.is_admin == True)
+        elif value == "false":
+            return query.filter(model.is_admin == False)
+        else:
+            return query
+```
+
+### Built in Column Filters
+
+The following built in column filters are available. All filters have a default value of "all" which allows the user to not filter the column
+
+* BooleanFilter - A filter for boolean columns, with the values of Yes (true) and No (false)
+* AllUniqueStringValuesFilter - A filter for string columns, with the values of all unique values in the column
+* StaticValuesFilter - A filter for string columns, with the values of a static list of values. This is similar to AllUniqueStringValuesFilter, but instead of getting the list of possible values from the database, you can provide a static list of values.
+* ForeignKeyFilter - A filter for foreign key columns, with the values of all unique values in the foreign key column. To make this filter readable, you need to provide the field name from the foreign model that you want to display as the name of the filter.
+  
+Here is an example of how to use BooleanFilter, AllUniqueStringValuesFilter and ForeignKeyFilter:
+
+```python
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    name: Mapped[str] = mapped_column(String, nullable=False)
+    email: Mapped[str] = mapped_column(String, nullable=False, index=True, unique=True)
+    is_admin: Mapped[bool] = mapped_column(Boolean, default=False)
+    site_id: Mapped[Optional[int]] = mapped_column(Integer, ForeignKey("sites.id"), nullable=True, default=None)
+    site: Mapped[Optional["Site"]] = relationship(back_populates="users")
+
+class Site(Base):
+    __tablename__ = "sites"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+    name: Mapped[str] = mapped_column(String, nullable=False)
+    users: Mapped[list["User"]] = relationship(back_populates="site")
+
+
+# Define User Admin View
+class UserAdmin(ModelView, model=User):
+    column_list = ["id", "name", "email", "is_admin"]
+    column_filters = [
+        BooleanFilter(User.is_admin), 
+        AllUniqueStringValuesFilter(User.name),
+        ForeignKeyFilter(User.site_id, Site.name, title="Site")
+    ]
+    can_create = True
+    can_edit = True
+    can_delete = True
+    can_view_details = True
+    name = "User"
+    name_plural = "Users"
+    icon = "fa-solid fa-user"
+    identity = "user"
+
+```
+
+
 ## Details page
 
 These options allow configurations in the details page, in the case of this example
@@ -260,6 +349,12 @@ The pages available are:
 
 For more information about working with template see [Working with Templates](./working_with_templates.md).
 
+## Template configurations
+
+The following options are available to configure the templates:
+
+* `show_compact_lists`: If `False`, the list of objects will be displayed in a separate line for each object. Default is `True`.
+
 ## Events
 
 There might be some cases which you want to do some actions

sqladmin/_types.py

@@ -1,9 +1,25 @@
-from typing import Union
+from typing import Any, Callable, List, Protocol, Tuple, Union, runtime_checkable
 
 from sqlalchemy.engine import Engine
 from sqlalchemy.ext.asyncio import AsyncEngine
 from sqlalchemy.orm import ColumnProperty, InstrumentedAttribute, RelationshipProperty
+from sqlalchemy.sql.expression import Select
+from starlette.requests import Request
 
 MODEL_PROPERTY = Union[ColumnProperty, RelationshipProperty]
 ENGINE_TYPE = Union[Engine, AsyncEngine]
 MODEL_ATTR = Union[str, InstrumentedAttribute]
+
+
+@runtime_checkable
+class ColumnFilter(Protocol):
+    title: str
+    parameter_name: str
+
+    async def lookups(
+        self, request: Request, model: Any, run_query: Callable[[Select], Any]
+    ) -> List[Tuple[str, str]]:
+        ...
+
+    async def get_filtered_query(self, query: Select, value: Any, model: Any) -> Select:
+        ...

sqladmin/filters.py

@@ -0,0 +1,174 @@
+import re
+from typing import Any, Callable, List, Optional, Tuple
+
+from sqlalchemy import Integer
+from sqlalchemy.sql.expression import Select, select
+from starlette.requests import Request
+
+from sqladmin._types import MODEL_ATTR
+
+
+def get_parameter_name(column: MODEL_ATTR) -> str:
+    if isinstance(column, str):
+        return column
+    else:
+        return column.key
+
+
+def prettify_attribute_name(name: str) -> str:
+    return re.sub(r"_([A-Za-z])", r" \1", name).title()
+
+
+def get_title(column: MODEL_ATTR) -> str:
+    name = get_parameter_name(column)
+    return prettify_attribute_name(name)
+
+
+def get_column_obj(column: MODEL_ATTR, model: Any = None) -> Any:
+    if isinstance(column, str):
+        if model is None:
+            raise ValueError("model is required for string column filters")
+        return getattr(model, column)
+    return column
+
+
+def get_foreign_column_name(column_obj: Any) -> str:
+    fk = next(iter(column_obj.foreign_keys))
+    return fk.column.name
+
+
+def get_model_from_column(column: Any) -> Any:
+    return column.parent.class_
+
+
+class BooleanFilter:
+    def __init__(
+        self,
+        column: MODEL_ATTR,
+        title: Optional[str] = None,
+        parameter_name: Optional[str] = None,
+    ):
+        self.column = column
+        self.title = title or get_title(column)
+        self.parameter_name = parameter_name or get_parameter_name(column)
+
+    async def lookups(
+        self, request: Request, model: Any, run_query: Callable[[Select], Any]
+    ) -> List[Tuple[str, str]]:
+        return [
+            ("all", "All"),
+            ("true", "Yes"),
+            ("false", "No"),
+        ]
+
+    async def get_filtered_query(self, query: Select, value: Any, model: Any) -> Select:
+        column_obj = get_column_obj(self.column, model)
+        if value == "true":
+            return query.filter(column_obj.is_(True))
+        elif value == "false":
+            return query.filter(column_obj.is_(False))
+        else:
+            return query
+
+
+class AllUniqueStringValuesFilter:
+    def __init__(
+        self,
+        column: MODEL_ATTR,
+        title: Optional[str] = None,
+        parameter_name: Optional[str] = None,
+    ):
+        self.column = column
+        self.title = title or get_title(column)
+        self.parameter_name = parameter_name or get_parameter_name(column)
+
+    async def lookups(
+        self, request: Request, model: Any, run_query: Callable[[Select], Any]
+    ) -> List[Tuple[str, str]]:
+        column_obj = get_column_obj(self.column, model)
+
+        return [("", "All")] + [
+            (value[0], value[0])
+            for value in await run_query(select(column_obj).distinct())
+        ]
+
+    async def get_filtered_query(self, query: Select, value: Any, model: Any) -> Select:
+        if value == "":
+            return query
+
+        column_obj = get_column_obj(self.column, model)
+        return query.filter(column_obj == value)
+
+
+class StaticValuesFilter:
+    def __init__(
+        self,
+        column: MODEL_ATTR,
+        values: List[Tuple[str, str]],
+        title: Optional[str] = None,
+        parameter_name: Optional[str] = None,
+    ):
+        self.column = column
+        self.title = title or get_title(column)
+        self.parameter_name = parameter_name or get_parameter_name(column)
+        self.values = values
+
+    async def lookups(
+        self, request: Request, model: Any, run_query: Callable[[Select], Any]
+    ) -> List[Tuple[str, str]]:
+        return [("", "All")] + self.values
+
+    async def get_filtered_query(self, query: Select, value: Any, model: Any) -> Select:
+        column_obj = get_column_obj(self.column, model)
+        if value == "":
+            return query
+        return query.filter(column_obj == value)
+
+
+class ForeignKeyFilter:
+    def __init__(
+        self,
+        foreign_key: MODEL_ATTR,
+        foreign_display_field: MODEL_ATTR,
+        foreign_model: Any = None,
+        title: Optional[str] = None,
+        parameter_name: Optional[str] = None,
+    ):
+        self.foreign_key = foreign_key
+        self.foreign_display_field = foreign_display_field
+        self.foreign_model = foreign_model
+        self.title = title or get_title(foreign_key)
+        self.parameter_name = parameter_name or get_parameter_name(foreign_key)
+
+    async def lookups(
+        self, request: Request, model: Any, run_query: Callable[[Select], Any]
+    ) -> List[Tuple[str, str]]:
+        foreign_key_obj = get_column_obj(self.foreign_key, model)
+        if self.foreign_model is None and isinstance(self.foreign_display_field, str):
+            raise ValueError("foreign_model is required for string foreign key filters")
+        if self.foreign_model is None:
+            assert not isinstance(self.foreign_display_field, str)
+            foreign_display_field_obj = self.foreign_display_field
+        else:
+            foreign_display_field_obj = get_column_obj(
+                self.foreign_display_field, self.foreign_model
+            )
+        if not self.foreign_model:
+            self.foreign_model = get_model_from_column(foreign_display_field_obj)
+        foreign_model_key_name = get_foreign_column_name(foreign_key_obj)
+        foreign_model_key_obj = getattr(self.foreign_model, foreign_model_key_name)
+
+        return [("", "All")] + [
+            (str(key), str(value))
+            for key, value in await run_query(
+                select(foreign_model_key_obj, foreign_display_field_obj).distinct()
+            )
+        ]
+
+    async def get_filtered_query(self, query: Select, value: Any, model: Any) -> Select:
+        foreign_key_obj = get_column_obj(self.foreign_key, model)
+        column_type = foreign_key_obj.type
+        if isinstance(column_type, Integer):
+            value = int(value)
+
+        return query.filter(foreign_key_obj == value)