How to Build a Simple Filter Helper in Python for API Design

from dataclasses import dataclass, field
from typing import List, Optional, Dict, Any


@dataclass
class FilterRequest:
    """A simple filter request mirroring a gRPC message structure."""
    field_name: str
    operator: str  # eq, ne, gt, lt, contains
    value: Any
    page_size: int = 10
    page_token: Optional[str] = None


@dataclass
class FilterResponse:
    results: List[Dict[str, Any]] = field(default_factory=list)
    next_page_token: Optional[str] = None


class DataFilterService:
    """A stateless filter service (like a gRPC service handler)."""

    def __init__(self, dataset: List[Dict[str, Any]]):
        self.dataset = dataset

    def filter(self, request: FilterRequest) -> FilterResponse:
        filtered = []
        for item in self.dataset:
            if field_name not in item:
                continue
            value = item[field_name]
            if request.operator == "eq" and value == request.value:
                filtered.append(item)
            elif request.operator == "ne" and value != request.value:
                filtered.append(item)
            elif request.operator == "gt" and value > request.value:
                filtered.append(item)
            elif request.operator == "lt" and value < request.value:
                filtered.append(item)
            elif request.operator == "contains" and request.value in value:
                filtered.append(item)
            if len(filtered) >= request.page_size:
                break
        return FilterResponse(results=filtered)


if __name__ == "__main__":
    sample_data = [
        {"name": "Alice", "age": 30, "city": "NYC"},
        {"name": "Bob", "age": 25, "city": "LA"},
        {"name": "Charlie", "age": 35, "city": "NYC"},
        {"name": "Diana", "age": 28, "city": "SF"},
    ]
    service = DataFilterService(sample_data)

    req = FilterRequest(field_name="city", operator="eq", value="NYC", page_size=10)
    resp = service.filter(req)
    print("NYC residents:", [r["name"] for r in resp.results])

    req2 = FilterRequest(field_name="age", operator="gt", value=26, page_size=10)
    resp2 = service.filter(req2)
    print("Over 26:", [r["name"] for r in resp2.results])