koalify 0.2.0__tar.gz

koalify-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dragos Dumitrache
+
+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.

koalify-0.2.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: koalify
+Version: 0.2.0
+Summary: A compact predicate DSL for matching criteria against any object
+License: MIT
+License-File: LICENSE
+Author: Dragos Dumitrache
+Author-email: dragos@afterburner.dev
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.14
+Description-Content-Type: text/markdown
+
+# koalify
+
+A compact predicate DSL for matching criteria against any Python object. Zero runtime dependencies.
+
+## Installation
+
+```bash
+pip install koalify
+```
+
+## Quick Start
+
+```python
+from koalify import F, all_of, any_of
+
+# Build rules with Python operators
+is_eligible = (
+    (F.status == "active")
+    & (F.age >= 18)
+    & (F.role.in_({"admin", "moderator", "editor"}))
+    & F.score.between(50, 100)
+)
+
+# Evaluate against any object with attributes
+is_eligible(user)  # True / False
+
+# Nested fields
+lives_in_london = F.address.city == "London"
+
+# Compose with OR / NOT
+can_access = is_eligible | (lives_in_london & ~(F.status == "banned"))
+
+# Dynamic composition from a list
+conditions = [F.status == "active", F.age >= 18]
+rule = all_of(*conditions)
+```
+
+## Examples
+
+### Dataclasses
+
+```python
+from dataclasses import dataclass
+from koalify import F, all_of
+
+@dataclass
+class Order:
+    product: str
+    quantity: int
+    price: float
+    fulfilled: bool
+
+needs_review = (F.quantity > 100) & (F.price >= 500) & (F.fulfilled == False)
+
+order = Order(product="Widget", quantity=200, price=750.0, fulfilled=False)
+needs_review(order)  # True
+```
+
+### Pydantic
+
+```python
+from pydantic import BaseModel
+from koalify import F, any_of
+
+class Address(BaseModel):
+    city: str
+    country: str
+
+class Customer(BaseModel):
+    name: str
+    tier: str
+    address: Address
+
+is_priority = (F.tier.in_({"gold", "platinum"})) | (F.address.country == "US")
+
+customer = Customer(name="Alice", tier="gold", address=Address(city="London", country="UK"))
+is_priority(customer)  # True
+```
+
+### Dynamic rule composition
+
+```python
+from koalify import F, all_of
+
+def build_filter(min_age: int | None = None, status: str | None = None, roles: set[str] | None = None):
+    criteria = []
+    if min_age is not None:
+        criteria.append(F.age >= min_age)
+    if status is not None:
+        criteria.append(F.status == status)
+    if roles is not None:
+        criteria.append(F.role.in_(roles))
+    return all_of(*criteria) if criteria else lambda _: True
+
+user_filter = build_filter(min_age=18, roles={"admin", "editor"})
+```
+
+## API
+
+| Symbol | Description |
+|---|---|
+| `F.field` | Reference a field (supports nesting: `F.a.b.c`) |
+| `==  !=  >  >=  <  <=` | Comparison operators on `FieldRef` |
+| `.in_(values)` | Set membership |
+| `.between(lo, hi)` | Inclusive range check |
+| `&` | AND (flattens nested ANDs) |
+| `\|` | OR (flattens nested ORs) |
+| `~` | NOT |
+| `all_of(*criteria)` | AND from a list |
+| `any_of(*criteria)` | OR from a list |
+
+## How It Works
+
+`F.field_name` returns a `FieldRef`. Comparison operators on `FieldRef` produce `Criterion` objects. Criteria compose with `&`, `|`, and `~`. Calling a criterion resolves field values via `getattr` — works with dataclasses, Pydantic models, namedtuples, or any object with attributes.
+
+## License
+
+MIT
+

koalify-0.2.0/README.md

@@ -0,0 +1,118 @@
+# koalify
+
+A compact predicate DSL for matching criteria against any Python object. Zero runtime dependencies.
+
+## Installation
+
+```bash
+pip install koalify
+```
+
+## Quick Start
+
+```python
+from koalify import F, all_of, any_of
+
+# Build rules with Python operators
+is_eligible = (
+    (F.status == "active")
+    & (F.age >= 18)
+    & (F.role.in_({"admin", "moderator", "editor"}))
+    & F.score.between(50, 100)
+)
+
+# Evaluate against any object with attributes
+is_eligible(user)  # True / False
+
+# Nested fields
+lives_in_london = F.address.city == "London"
+
+# Compose with OR / NOT
+can_access = is_eligible | (lives_in_london & ~(F.status == "banned"))
+
+# Dynamic composition from a list
+conditions = [F.status == "active", F.age >= 18]
+rule = all_of(*conditions)
+```
+
+## Examples
+
+### Dataclasses
+
+```python
+from dataclasses import dataclass
+from koalify import F, all_of
+
+@dataclass
+class Order:
+    product: str
+    quantity: int
+    price: float
+    fulfilled: bool
+
+needs_review = (F.quantity > 100) & (F.price >= 500) & (F.fulfilled == False)
+
+order = Order(product="Widget", quantity=200, price=750.0, fulfilled=False)
+needs_review(order)  # True
+```
+
+### Pydantic
+
+```python
+from pydantic import BaseModel
+from koalify import F, any_of
+
+class Address(BaseModel):
+    city: str
+    country: str
+
+class Customer(BaseModel):
+    name: str
+    tier: str
+    address: Address
+
+is_priority = (F.tier.in_({"gold", "platinum"})) | (F.address.country == "US")
+
+customer = Customer(name="Alice", tier="gold", address=Address(city="London", country="UK"))
+is_priority(customer)  # True
+```
+
+### Dynamic rule composition
+
+```python
+from koalify import F, all_of
+
+def build_filter(min_age: int | None = None, status: str | None = None, roles: set[str] | None = None):
+    criteria = []
+    if min_age is not None:
+        criteria.append(F.age >= min_age)
+    if status is not None:
+        criteria.append(F.status == status)
+    if roles is not None:
+        criteria.append(F.role.in_(roles))
+    return all_of(*criteria) if criteria else lambda _: True
+
+user_filter = build_filter(min_age=18, roles={"admin", "editor"})
+```
+
+## API
+
+| Symbol | Description |
+|---|---|
+| `F.field` | Reference a field (supports nesting: `F.a.b.c`) |
+| `==  !=  >  >=  <  <=` | Comparison operators on `FieldRef` |
+| `.in_(values)` | Set membership |
+| `.between(lo, hi)` | Inclusive range check |
+| `&` | AND (flattens nested ANDs) |
+| `\|` | OR (flattens nested ORs) |
+| `~` | NOT |
+| `all_of(*criteria)` | AND from a list |
+| `any_of(*criteria)` | OR from a list |
+
+## How It Works
+
+`F.field_name` returns a `FieldRef`. Comparison operators on `FieldRef` produce `Criterion` objects. Criteria compose with `&`, `|`, and `~`. Calling a criterion resolves field values via `getattr` — works with dataclasses, Pydantic models, namedtuples, or any object with attributes.
+
+## License
+
+MIT

koalify-0.2.0/koalify/__init__.py

@@ -0,0 +1,13 @@
+from koalify.criteria import And, Criterion, Not, Or, all_of, any_of
+from koalify.fields import F, FieldRef
+
+__all__ = [
+    "And",
+    "Criterion",
+    "F",
+    "FieldRef",
+    "Not",
+    "Or",
+    "all_of",
+    "any_of",
+]

koalify-0.2.0/koalify/comparisons.py

@@ -0,0 +1,89 @@
+"""Leaf criteria: field-vs-value comparisons."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from koalify.criteria import Criterion
+
+
+class _Compare(Criterion):
+    """Base for field-vs-value comparisons."""
+
+    op: str
+
+    def __init__(self, field: Any, value: Any):
+        self.field = field
+        self.value = value
+
+    def __repr__(self) -> str:
+        return f"{self.field!r} {self.op} {self.value!r}"
+
+
+class Eq(_Compare):
+    op = "=="
+
+    def match(self, obj: Any) -> bool:
+        return self.field.resolve(obj) == self.value
+
+
+class Ne(_Compare):
+    op = "!="
+
+    def match(self, obj: Any) -> bool:
+        return self.field.resolve(obj) != self.value
+
+
+class Gt(_Compare):
+    op = ">"
+
+    def match(self, obj: Any) -> bool:
+        return self.field.resolve(obj) > self.value
+
+
+class Ge(_Compare):
+    op = ">="
+
+    def match(self, obj: Any) -> bool:
+        return self.field.resolve(obj) >= self.value
+
+
+class Lt(_Compare):
+    op = "<"
+
+    def match(self, obj: Any) -> bool:
+        return self.field.resolve(obj) < self.value
+
+
+class Le(_Compare):
+    op = "<="
+
+    def match(self, obj: Any) -> bool:
+        return self.field.resolve(obj) <= self.value
+
+
+class In(Criterion):
+    def __init__(self, field: Any, values: set | frozenset | list | tuple):
+        self.field = field
+        self.values = values
+
+    def match(self, obj: Any) -> bool:
+        return self.field.resolve(obj) in self.values
+
+    def __repr__(self) -> str:
+        return f"{self.field!r} in {self.values!r}"
+
+
+class Between(Criterion):
+    """Inclusive on both bounds: lower <= value <= upper."""
+
+    def __init__(self, field: Any, lower: Any, upper: Any):
+        self.field = field
+        self.lower = lower
+        self.upper = upper
+
+    def match(self, obj: Any) -> bool:
+        return self.lower <= self.field.resolve(obj) <= self.upper
+
+    def __repr__(self) -> str:
+        return f"{self.lower!r} <= {self.field!r} <= {self.upper!r}"

koalify-0.2.0/koalify/criteria.py

@@ -0,0 +1,71 @@
+"""Base criterion type and composite operators (AND, OR, NOT)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class Criterion:
+    """A composable predicate that can be evaluated against any object with attributes."""
+
+    def match(self, obj: Any) -> bool:
+        raise NotImplementedError
+
+    def __call__(self, obj: Any) -> bool:
+        return self.match(obj)
+
+    def __and__(self, other: Criterion) -> Criterion:
+        left = self.criteria if isinstance(self, And) else (self,)
+        right = other.criteria if isinstance(other, And) else (other,)
+        return And(*left, *right)
+
+    def __or__(self, other: Criterion) -> Criterion:
+        left = self.criteria if isinstance(self, Or) else (self,)
+        right = other.criteria if isinstance(other, Or) else (other,)
+        return Or(*left, *right)
+
+    def __invert__(self) -> Not:
+        return Not(self)
+
+
+class And(Criterion):
+    def __init__(self, *criteria: Criterion):
+        self.criteria = criteria
+
+    def match(self, obj: Any) -> bool:
+        return all(c.match(obj) for c in self.criteria)
+
+    def __repr__(self) -> str:
+        return f"({' & '.join(repr(c) for c in self.criteria)})"
+
+
+class Or(Criterion):
+    def __init__(self, *criteria: Criterion):
+        self.criteria = criteria
+
+    def match(self, obj: Any) -> bool:
+        return any(c.match(obj) for c in self.criteria)
+
+    def __repr__(self) -> str:
+        return f"({' | '.join(repr(c) for c in self.criteria)})"
+
+
+class Not(Criterion):
+    def __init__(self, criterion: Criterion):
+        self.criterion = criterion
+
+    def match(self, obj: Any) -> bool:
+        return not self.criterion.match(obj)
+
+    def __repr__(self) -> str:
+        return f"~{self.criterion!r}"
+
+
+def all_of(*criteria: Criterion) -> And:
+    """Combine criteria with AND (useful for dynamic / programmatic composition)."""
+    return And(*criteria)
+
+
+def any_of(*criteria: Criterion) -> Or:
+    """Combine criteria with OR (useful for dynamic / programmatic composition)."""
+    return Or(*criteria)

koalify-0.2.0/koalify/fields.py

@@ -0,0 +1,79 @@
+"""Field reference and accessor — the ``F.field_name`` entry point."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from koalify.comparisons import Between, Eq, Ge, Gt, In, Le, Lt, Ne
+
+
+class FieldRef:
+    """
+    Reference to one (possibly nested) field on an object.
+
+    Supports Python comparison operators to produce criteria, and
+    attribute access for nested fields: F.address.city
+    """
+
+    def __init__(self, *path: str):
+        self._path = path
+
+    def resolve(self, obj: Any) -> Any:
+        value: Any = obj
+        for part in self._path:
+            value = getattr(value, part)
+        return value
+
+    # ── nested access ────────────────────────────────────────────
+
+    def __getattr__(self, name: str) -> FieldRef:
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return FieldRef(*self._path, name)
+
+    # ── comparison operators → criteria ──────────────────────────
+
+    def __eq__(self, value: Any) -> Eq:
+        return Eq(self, value)
+
+    def __ne__(self, value: Any) -> Ne:
+        return Ne(self, value)
+
+    def __gt__(self, value: Any) -> Gt:
+        return Gt(self, value)
+
+    def __ge__(self, value: Any) -> Ge:
+        return Ge(self, value)
+
+    def __lt__(self, value: Any) -> Lt:
+        return Lt(self, value)
+
+    def __le__(self, value: Any) -> Le:
+        return Le(self, value)
+
+    # ── set / range predicates ───────────────────────────────────
+
+    def in_(self, values: set | frozenset | list | tuple) -> In:
+        return In(self, values)
+
+    def between(self, lower: Any, upper: Any) -> Between:
+        return Between(self, lower, upper)
+
+    # ── repr ─────────────────────────────────────────────────────
+
+    def __repr__(self) -> str:
+        return ".".join(self._path)
+
+    def __hash__(self) -> int:
+        return hash(self._path)
+
+
+class _FieldAccessor:
+    """Singleton entry-point: ``F.field_name`` creates a :class:`FieldRef`."""
+
+    def __getattr__(self, name: str) -> FieldRef:
+        return FieldRef(name)
+
+
+F = _FieldAccessor()
+"""Use ``F.field_name`` to reference fields in criteria."""

koalify-0.2.0/pyproject.toml

@@ -0,0 +1,18 @@
+[tool.poetry]
+name = "koalify"
+version = "0.2.0"
+description = "A compact predicate DSL for matching criteria against any object"
+authors = ["Dragos Dumitrache <dragos@afterburner.dev>"]
+license = "MIT"
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.10"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0"
+pydantic = "^2.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"