The Criteria Pattern is a Python 🐍 package that simplifies and standardizes criteria based filtering 🤏🏻, validation and selection. This package provides a set of prebuilt 👷🏻 objects and utilities that you can drop into your existing projects and not have to implement yourself.
These utilities 🛠️ are useful when you need complex filtering logic. It also enforces 👮🏻 best practices so all your filtering processes follow a uniform standard.
Easy to install and integrate, this is a must have for any Python developer looking to simplify their workflow, enforce design patterns and use the full power of modern ORMs and SQL 🗄️ in their projects 🚀.
You can install Criteria Pattern using pip:
pip install criteria-patternThis project's documentation is powered by DeepWiki, which provides a comprehensive overview of the Criteria Pattern and its usage.
from criteria_pattern import Criteria, Filter, Operator
from criteria_pattern.converters import CriteriaToPostgresqlConverter
is_adult = Criteria(filters=[Filter(field='age', operator=Operator.GREATER_OR_EQUAL, value=18)])
email_is_gmail = Criteria(filters=[Filter(field='email', operator=Operator.ENDS_WITH, value='@gmail.com')])
email_is_yahoo = Criteria(filters=[Filter(field='email', operator=Operator.ENDS_WITH, value='@yahoo.com')])
query, parameters = CriteriaToPostgresqlConverter.convert(criteria=is_adult & (email_is_gmail | email_is_yahoo), table='user')
print(query)
print(parameters)
# >>> SELECT * FROM user WHERE (age >= %(parameter_0)s AND (email LIKE '%%' || %(parameter_1)s OR email LIKE '%%' || %(parameter_2)s));
# >>> {'parameter_0': 18, 'parameter_1': '@gmail.com', 'parameter_2': '@yahoo.com'}The package includes converters for SQL generation and request parsing:
criteria_pattern.converters.CriteriaToPostgresqlConverter: Converts aCriteriaobject into PostgreSQL SQL + parameters.criteria_pattern.converters.CriteriaToMysqlConverter: Converts aCriteriaobject into MySQL SQL + parameters.criteria_pattern.converters.CriteriaToMariadbConverter: Converts aCriteriaobject into MariaDB SQL + parameters.criteria_pattern.converters.CriteriaToSqliteConverter: Converts aCriteriaobject into SQLite SQL + parameters.criteria_pattern.converters.UrlToCriteriaConverter: Parses URL query parameters into aCriteriaobject.
Imagine an admin dashboard where each request must:
- Always restrict results to the current tenant.
- Optionally filter active users.
- Search only users with company emails.
- Sort by newest users first.
With Criteria Pattern, each concern is a small reusable criteria object. You combine them using & and |, then convert once to SQL:
from criteria_pattern import Criteria, Direction, Filter, Operator, Order
from criteria_pattern.converters import CriteriaToPostgresqlConverter
class UserSearchService:
def __init__(self, tenant_id: str) -> None:
self.tenant_id = tenant_id
def build_query(self, *, only_active: bool, corporate_domain: str) -> tuple[str, dict[str, object]]:
tenant_scope = Criteria(filters=[Filter(field='tenant_id', operator=Operator.EQUAL, value=self.tenant_id)])
active_scope = Criteria(filters=[Filter(field='is_active', operator=Operator.EQUAL, value=True)])
email_scope = Criteria(filters=[Filter(field='email', operator=Operator.ENDS_WITH, value=corporate_domain)])
sort_scope = Criteria(orders=[Order(field='created_at', direction=Direction.DESC)])
criteria = tenant_scope & email_scope & sort_scope
if only_active:
criteria = criteria & active_scope
return CriteriaToPostgresqlConverter.convert(criteria=criteria, table='users')
service = UserSearchService(tenant_id='tenant_123')
query, parameters = service.build_query(only_active=True, corporate_domain='@acme.com')
print(query)
print(parameters)We love community help! Before you open an issue or pull request, please read:
Thank you for helping make 🤏🏻 Criteria Pattern package awesome! 🌟
This project is licensed under the terms of the MIT license.