pyruleset 0.1.0__tar.gz

pyruleset-0.1.0/PKG-INFO

@@ -0,0 +1,385 @@
+Metadata-Version: 2.4
+Name: pyruleset
+Version: 0.1.0
+Summary: Conditional values: pick a value by the first matching condition, composable with | and definable as JSON.
+Keywords: rules,decision-table,policy,conditional,json,dsl,composition
+Author: aaltatan
+Author-email: aaltatan <a.altatan@gmail.com>
+License-Expression: GPL-3.0-only
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: pyvocabulary>=0.1.0
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/aaltatan/pyruleset
+Project-URL: Repository, https://github.com/aaltatan/pyruleset
+Project-URL: Issues, https://github.com/aaltatan/pyruleset/issues
+Description-Content-Type: text/markdown
+
+# pyruleset
+
+Conditional values that compose with `|` and can be defined as JSON: the first branch whose
+condition matches decides.
+
+```python
+price = (
+    when(tier__eq("gold"), subtotal * Decimal("0.80"), label="gold 20%")
+    | when(items__ge(10), subtotal * Decimal("0.95"), label="bulk 5%")
+    | otherwise(subtotal)
+)
+
+price(order)  # Decimal('142.5000')
+price.explain(order)  # 'bulk 5%'
+```
+
+Conditions are any `T -> bool` callable, such as a
+[pyspecification](https://github.com/aaltatan/pyspecification) `Predicate`. Values are any
+`T -> V` callable, such as a [pyformula](https://github.com/aaltatan/pyformula) `Formula`, a
+[pyflowstep](https://github.com/aaltatan/pyflowstep) `Flow`, or a plain function.
+
+| Piece | What it does |
+| --- | --- |
+| [`when`, `otherwise`](#quick-start) | Build branches and the fallback, chained with `\|` |
+| [`Ruleset`](#deciding-and-explaining) | Callable: returns the value of the first matching branch; `explain` and `decide` say which one |
+| [`PartialRuleset`](#a-missing-fallback-is-a-type-error) | Branches without a fallback: composes, but is not callable |
+| [`RulesetCompiler`](#from-json) | Builds a `Ruleset` from JSON, delegating `when` and `then` to compilers you inject |
+| [`get_ruleset_json_schema`](#json-schema) | The JSON Schema of that JSON, embedding your condition and value schemas |
+
+## Installation
+
+pyruleset is not on PyPI yet. Install it from GitHub:
+
+```bash
+pip install git+https://github.com/aaltatan/pyruleset
+```
+
+or with uv:
+
+```bash
+uv add git+https://github.com/aaltatan/pyruleset
+```
+
+Python 3.12+. The only runtime dependency is
+[pyvocabulary](https://github.com/aaltatan/pyvocabulary). pyspecification, pyformula and
+pyflowstep are optional: pyruleset only needs callables.
+
+## Quick start
+
+The examples in this README build on each other and run as doctests.
+
+```python
+>>> from dataclasses import dataclass
+>>> from decimal import Decimal
+>>> from pyformula import variable
+>>> from pyspecification import object_rule
+>>> from pyruleset import otherwise, when
+
+>>> @dataclass(frozen=True)
+... class Order:
+...     tier: str
+...     subtotal: Decimal
+...     items: int
+
+>>> @object_rule()
+... def tier__eq(order: Order, tier: str) -> bool:
+...     return order.tier == tier
+
+>>> @object_rule()
+... def items__ge(order: Order, count: int) -> bool:
+...     return order.items >= count
+
+>>> @variable()
+... def subtotal(order: Order) -> Decimal:
+...     return order.subtotal
+
+>>> price = (
+...     when(tier__eq("gold"), subtotal * Decimal("0.80"), label="gold 20%")
+...     | when(items__ge(10), subtotal * Decimal("0.95"), label="bulk 5%")
+...     | otherwise(subtotal)
+... )
+>>> price
+Ruleset(gold 20% | bulk 5% | otherwise)
+
+>>> order = Order("regular", Decimal("150.00"), 12)
+>>> price(order)
+Decimal('142.5000')
+
+```
+
+Branches are tried in order and the first match wins. Conditions after the match are not
+evaluated. When nothing matches, the `otherwise` value is used.
+
+## Deciding and explaining
+
+`explain(subject)` names the branch that decided, e.g. for an audit log: its label, else the
+condition's name, else `"otherwise"`. `decide(subject)` returns the `Branch` (or `Otherwise`)
+itself.
+
+```python
+>>> price.explain(order)
+'bulk 5%'
+>>> price.explain(Order("regular", Decimal("60.00"), 1))
+'otherwise'
+>>> price.decide(order)
+Branch(condition=..., label='bulk 5%')
+
+>>> unlabelled = when(items__ge(10), subtotal) | otherwise(subtotal)
+>>> unlabelled.explain(order), unlabelled
+('items__ge', Ruleset(items__ge | otherwise))
+
+```
+
+A condition can return any value: truthy counts as a match.
+
+```python
+>>> size = when(len, lambda items: f"{len(items)} items") | otherwise(lambda _: "empty")
+>>> size([1, 2]), size([])
+('2 items', 'empty')
+
+```
+
+## A missing fallback is a type error
+
+`when(...) | when(...)` is a `PartialRuleset`. It composes, but it has no `__call__`, so a
+type checker flags a call to it, and at run time it fails instead of returning `None`. Only
+`| otherwise(...)` (or `| ruleset`) makes it callable.
+
+```python
+>>> partial = when(tier__eq("gold"), subtotal * Decimal("0.80"), label="gold")
+>>> partial
+PartialRuleset(gold)
+>>> partial(order)
+Traceback (most recent call last):
+...
+TypeError: 'PartialRuleset' object is not callable
+
+```
+
+A `Ruleset` is closed: it has no `|`, so nothing can be added after its fallback by accident.
+
+## Overrides on top of a base policy
+
+`partial | ruleset` puts the partial's branches first. The base policy stays unchanged, and
+the override is easy to drop later.
+
+```python
+>>> black_friday = when(items__ge(5), subtotal * Decimal("0.70"), label="black friday")
+>>> today = black_friday | price
+>>> today
+Ruleset(black friday | gold 20% | bulk 5% | otherwise)
+>>> today(order), price(order)
+(Decimal('105.0000'), Decimal('142.5000'))
+
+```
+
+Every operator returns a new object; rulesets are frozen dataclasses.
+
+## Any callable as a value
+
+Values do not have to be formulas. A pyflowstep `Flow` turns the ruleset into "pick a
+procedure and run it":
+
+```python
+>>> from pyflowstep import step
+>>> @step
+... def add(total: int, amount: int) -> int:
+...     return total + amount
+
+>>> bonus = when(lambda n: n >= 100, add(10) >> add(5), label="big") | otherwise(add(0))
+>>> bonus(100), bonus(7)
+(115, 7)
+
+```
+
+## From JSON
+
+A definition has `branches` (optional) and `otherwise` (required). Each branch has `when`,
+`then` and an optional `label`:
+
+```json
+{
+  "branches": [
+    {"label": "gold 20%",
+     "when": {"name": "tier__eq", "args": ["gold"], "kwargs": {}, "inverse": false},
+     "then": {"operator": "multiply", "expressions": ["subtotal", 0.80]}}
+  ],
+  "otherwise": "subtotal"
+}
+```
+
+pyruleset does not know the languages inside `when` and `then`. `RulesetCompiler` delegates
+them to the compilers you pass in: anything with a `compile(definition)` method, such as
+pyspecification's `PredicateCompiler` and pyformula's `FormulaCompiler`.
+
+```python
+>>> import json
+>>> from pyformula import FormulaCompiler
+>>> from pyspecification import Predicate, PredicateCompiler
+>>> from pyruleset import RulesetCompiler
+
+>>> rules = {"tier__eq": tier__eq, "items__ge": items__ge}
+>>> compiler = RulesetCompiler(
+...     PredicateCompiler(
+...         rules,
+...         lambda wrapper: Predicate(lambda _: wrapper["operator"] == "all", operator="logical"),
+...     ),
+...     FormulaCompiler({"subtotal": subtotal}),
+... )
+
+>>> stored = '''
+... {
+...   "branches": [
+...     {"label": "gold 20%",
+...      "when": {"name": "tier__eq", "args": ["gold"], "kwargs": {}, "inverse": false},
+...      "then": {"operator": "multiply", "expressions": ["subtotal", 0.80]}}
+...   ],
+...   "otherwise": "subtotal"
+... }
+... '''
+>>> policy = compiler.compile(json.loads(stored, parse_float=Decimal))
+>>> policy
+Ruleset(gold 20% | otherwise)
+>>> policy(Order("gold", Decimal("120.00"), 2))
+Decimal('96.0000')
+
+```
+
+### Errors
+
+The whole definition is checked when it is compiled, before any subject is evaluated.
+
+A wrong shape raises `InvalidRulesetDefinitionError` (also a `ValueError`) with its JSON
+path:
+
+```python
+>>> compiler.compile({"branches": []})
+Traceback (most recent call last):
+...
+pyruleset.exceptions.InvalidRulesetDefinitionError: Invalid ruleset at $: missing 'otherwise'
+
+```
+
+Errors from the injected compilers keep their own type. pyruleset only adds a note with the
+full JSON path, nested paths included (e.g. `at $.branches[1].when.expressions[0]`):
+
+```python
+>>> from pyspecification import RuleDoesNotExistError
+>>> typo = json.loads(stored.replace("tier__eq", "tier__is"), parse_float=Decimal)
+>>> try:
+...     compiler.compile(typo)
+... except RuleDoesNotExistError as error:
+...     print(f"{type(error).__name__}: {error}", error.__notes__)
+RuleDoesNotExistError: Rule 'tier__is' does not exist. Available rules: tier__eq, items__ge ['at $.branches[0].when']
+
+```
+
+## Money
+
+`json.loads` turns `0.80` into a binary float, which then leaks into every `Decimal` it
+touches. Keep money exact in one of two ways:
+
+- Parse with `json.loads(text, parse_float=Decimal)`, as above, so every JSON number with a
+  decimal point becomes a `Decimal` before it reaches the compiler.
+- Or, with pyformula 0.2+, build the value compiler with
+  `FormulaCompiler(variables, literal=decimal_literal)`, which converts each number literal
+  through `str` (`Decimal("0.8")`, not `Decimal(0.8)`), whoever parsed the JSON.
+
+## JSON Schema
+
+`get_ruleset_json_schema(condition_schema, value_schema)` describes a definition, e.g. to
+validate an admin form or to get completion in an editor. The two schemas describe one
+`when` and one `then`/`otherwise`. Each is embedded under its own `$id`, so the
+`#/$defs/...` refs inside it keep pointing into itself.
+
+```python
+>>> from jsonschema import Draft202012Validator
+>>> from pyspecification import get_expression_json_schema
+>>> from pyruleset import get_ruleset_json_schema
+
+>>> formula_schema = {"anyOf": [{"const": "subtotal"}, {"type": "number"}, {"type": "object"}]}
+>>> schema = get_ruleset_json_schema(get_expression_json_schema(rules), formula_schema)
+>>> validator = Draft202012Validator(schema)
+>>> validator.is_valid(json.loads(stored))
+True
+>>> validator.is_valid(json.loads(stored.replace("tier__eq", "tier__is")))
+False
+
+```
+
+`jsonschema` is only used here to show the schema at work; pyruleset does not depend on it.
+
+## First match only
+
+A ruleset picks exactly one value. There is no "all matches" mode, on purpose: each ruleset
+stays easy to read and to explain. To stack several decisions, give each part its own
+ruleset and add the results:
+
+```python
+>>> shipping = (
+...     when(items__ge(10), lambda _: Decimal("0.00"), label="free shipping")
+...     | otherwise(lambda _: Decimal("5.00"))
+... )
+>>> def total(order: Order) -> Decimal:
+...     return price(order) + shipping(order)
+>>> small = Order("regular", Decimal("60.00"), 1)
+>>> total(small), [price.explain(small), shipping.explain(small)]
+(Decimal('65.00'), ['otherwise', 'otherwise'])
+
+```
+
+Progressive brackets (tax bands) are not a ruleset either: they are a sum of clamped terms,
+one per band.
+
+## Examples
+
+Runnable scripts in [`examples/`](examples), each asserting its own results:
+
+- [`pricing_policy.py`](examples/pricing_policy.py): a JSON policy from an admin panel,
+  rejected on save with the JSON path of a typo, and `explain` for the audit log.
+- [`expense_approvals.py`](examples/expense_approvals.py): who approves an expense, with a
+  temporary "CFO on leave" override on top of the base policy.
+- [`ticket_routing.py`](examples/ticket_routing.py): each branch's value is a pyflowstep
+  `Flow` that assigns, prioritizes and tags the ticket.
+
+```bash
+uv run python examples/pricing_policy.py
+```
+
+## API reference
+
+| Name | Kind | Summary |
+| --- | --- | --- |
+| `when(condition, value, /, *, label=None) -> PartialRuleset` | function | One branch; chain more with `\|` |
+| `otherwise(value, /) -> Otherwise` | function | The fallback that closes a ruleset |
+| `Ruleset(branches, fallback)` | class | `__call__(subject)`, `decide(subject)`, `explain(subject)` |
+| `PartialRuleset(branches)` | class | `\|` with a partial, an `Otherwise` or a `Ruleset`; not callable |
+| `Branch(condition, value, label=None)` | class | One `when` pair; `str()` is its label or condition name |
+| `Otherwise(value)` | class | What `decide` returns when no branch matches |
+| `FALLBACK_LABEL` | constant | `"otherwise"`, what `explain` returns for the fallback |
+| `Condition[T]`, `Value[T, V]` | type | `Callable[[T], Any]`, `Callable[[T], V]` |
+| `RulesetCompiler(conditions, values, /)` | class | `compile(definition) -> Ruleset` |
+| `Compiler[F]` | protocol | Anything with `compile(definition, /) -> F` |
+| `RulesetDict`, `BranchDict` | type | `TypedDict`s of the JSON shape |
+| `get_ruleset_json_schema(condition_schema, value_schema, /) -> dict` | function | JSON Schema of a definition |
+| `PyrulesetError` | exception | Base class of pyruleset's errors |
+| `InvalidRulesetDefinitionError` | exception | Wrong definition shape; also a `ValueError` |
+
+## Development
+
+```bash
+uv sync
+uv run pytest --cov --cov-branch     # tests, doctests in src/ and this README, examples
+uv run --python 3.13 pytest
+uvx ruff check . && uvx ruff format --check .
+uvx pyright src
+```
+
+## License
+
+GPL-3.0-only.

pyruleset-0.1.0/README.md

@@ -0,0 +1,361 @@
+# pyruleset
+
+Conditional values that compose with `|` and can be defined as JSON: the first branch whose
+condition matches decides.
+
+```python
+price = (
+    when(tier__eq("gold"), subtotal * Decimal("0.80"), label="gold 20%")
+    | when(items__ge(10), subtotal * Decimal("0.95"), label="bulk 5%")
+    | otherwise(subtotal)
+)
+
+price(order)  # Decimal('142.5000')
+price.explain(order)  # 'bulk 5%'
+```
+
+Conditions are any `T -> bool` callable, such as a
+[pyspecification](https://github.com/aaltatan/pyspecification) `Predicate`. Values are any
+`T -> V` callable, such as a [pyformula](https://github.com/aaltatan/pyformula) `Formula`, a
+[pyflowstep](https://github.com/aaltatan/pyflowstep) `Flow`, or a plain function.
+
+| Piece | What it does |
+| --- | --- |
+| [`when`, `otherwise`](#quick-start) | Build branches and the fallback, chained with `\|` |
+| [`Ruleset`](#deciding-and-explaining) | Callable: returns the value of the first matching branch; `explain` and `decide` say which one |
+| [`PartialRuleset`](#a-missing-fallback-is-a-type-error) | Branches without a fallback: composes, but is not callable |
+| [`RulesetCompiler`](#from-json) | Builds a `Ruleset` from JSON, delegating `when` and `then` to compilers you inject |
+| [`get_ruleset_json_schema`](#json-schema) | The JSON Schema of that JSON, embedding your condition and value schemas |
+
+## Installation
+
+pyruleset is not on PyPI yet. Install it from GitHub:
+
+```bash
+pip install git+https://github.com/aaltatan/pyruleset
+```
+
+or with uv:
+
+```bash
+uv add git+https://github.com/aaltatan/pyruleset
+```
+
+Python 3.12+. The only runtime dependency is
+[pyvocabulary](https://github.com/aaltatan/pyvocabulary). pyspecification, pyformula and
+pyflowstep are optional: pyruleset only needs callables.
+
+## Quick start
+
+The examples in this README build on each other and run as doctests.
+
+```python
+>>> from dataclasses import dataclass
+>>> from decimal import Decimal
+>>> from pyformula import variable
+>>> from pyspecification import object_rule
+>>> from pyruleset import otherwise, when
+
+>>> @dataclass(frozen=True)
+... class Order:
+...     tier: str
+...     subtotal: Decimal
+...     items: int
+
+>>> @object_rule()
+... def tier__eq(order: Order, tier: str) -> bool:
+...     return order.tier == tier
+
+>>> @object_rule()
+... def items__ge(order: Order, count: int) -> bool:
+...     return order.items >= count
+
+>>> @variable()
+... def subtotal(order: Order) -> Decimal:
+...     return order.subtotal
+
+>>> price = (
+...     when(tier__eq("gold"), subtotal * Decimal("0.80"), label="gold 20%")
+...     | when(items__ge(10), subtotal * Decimal("0.95"), label="bulk 5%")
+...     | otherwise(subtotal)
+... )
+>>> price
+Ruleset(gold 20% | bulk 5% | otherwise)
+
+>>> order = Order("regular", Decimal("150.00"), 12)
+>>> price(order)
+Decimal('142.5000')
+
+```
+
+Branches are tried in order and the first match wins. Conditions after the match are not
+evaluated. When nothing matches, the `otherwise` value is used.
+
+## Deciding and explaining
+
+`explain(subject)` names the branch that decided, e.g. for an audit log: its label, else the
+condition's name, else `"otherwise"`. `decide(subject)` returns the `Branch` (or `Otherwise`)
+itself.
+
+```python
+>>> price.explain(order)
+'bulk 5%'
+>>> price.explain(Order("regular", Decimal("60.00"), 1))
+'otherwise'
+>>> price.decide(order)
+Branch(condition=..., label='bulk 5%')
+
+>>> unlabelled = when(items__ge(10), subtotal) | otherwise(subtotal)
+>>> unlabelled.explain(order), unlabelled
+('items__ge', Ruleset(items__ge | otherwise))
+
+```
+
+A condition can return any value: truthy counts as a match.
+
+```python
+>>> size = when(len, lambda items: f"{len(items)} items") | otherwise(lambda _: "empty")
+>>> size([1, 2]), size([])
+('2 items', 'empty')
+
+```
+
+## A missing fallback is a type error
+
+`when(...) | when(...)` is a `PartialRuleset`. It composes, but it has no `__call__`, so a
+type checker flags a call to it, and at run time it fails instead of returning `None`. Only
+`| otherwise(...)` (or `| ruleset`) makes it callable.
+
+```python
+>>> partial = when(tier__eq("gold"), subtotal * Decimal("0.80"), label="gold")
+>>> partial
+PartialRuleset(gold)
+>>> partial(order)
+Traceback (most recent call last):
+...
+TypeError: 'PartialRuleset' object is not callable
+
+```
+
+A `Ruleset` is closed: it has no `|`, so nothing can be added after its fallback by accident.
+
+## Overrides on top of a base policy
+
+`partial | ruleset` puts the partial's branches first. The base policy stays unchanged, and
+the override is easy to drop later.
+
+```python
+>>> black_friday = when(items__ge(5), subtotal * Decimal("0.70"), label="black friday")
+>>> today = black_friday | price
+>>> today
+Ruleset(black friday | gold 20% | bulk 5% | otherwise)
+>>> today(order), price(order)
+(Decimal('105.0000'), Decimal('142.5000'))
+
+```
+
+Every operator returns a new object; rulesets are frozen dataclasses.
+
+## Any callable as a value
+
+Values do not have to be formulas. A pyflowstep `Flow` turns the ruleset into "pick a
+procedure and run it":
+
+```python
+>>> from pyflowstep import step
+>>> @step
+... def add(total: int, amount: int) -> int:
+...     return total + amount
+
+>>> bonus = when(lambda n: n >= 100, add(10) >> add(5), label="big") | otherwise(add(0))
+>>> bonus(100), bonus(7)
+(115, 7)
+
+```
+
+## From JSON
+
+A definition has `branches` (optional) and `otherwise` (required). Each branch has `when`,
+`then` and an optional `label`:
+
+```json
+{
+  "branches": [
+    {"label": "gold 20%",
+     "when": {"name": "tier__eq", "args": ["gold"], "kwargs": {}, "inverse": false},
+     "then": {"operator": "multiply", "expressions": ["subtotal", 0.80]}}
+  ],
+  "otherwise": "subtotal"
+}
+```
+
+pyruleset does not know the languages inside `when` and `then`. `RulesetCompiler` delegates
+them to the compilers you pass in: anything with a `compile(definition)` method, such as
+pyspecification's `PredicateCompiler` and pyformula's `FormulaCompiler`.
+
+```python
+>>> import json
+>>> from pyformula import FormulaCompiler
+>>> from pyspecification import Predicate, PredicateCompiler
+>>> from pyruleset import RulesetCompiler
+
+>>> rules = {"tier__eq": tier__eq, "items__ge": items__ge}
+>>> compiler = RulesetCompiler(
+...     PredicateCompiler(
+...         rules,
+...         lambda wrapper: Predicate(lambda _: wrapper["operator"] == "all", operator="logical"),
+...     ),
+...     FormulaCompiler({"subtotal": subtotal}),
+... )
+
+>>> stored = '''
+... {
+...   "branches": [
+...     {"label": "gold 20%",
+...      "when": {"name": "tier__eq", "args": ["gold"], "kwargs": {}, "inverse": false},
+...      "then": {"operator": "multiply", "expressions": ["subtotal", 0.80]}}
+...   ],
+...   "otherwise": "subtotal"
+... }
+... '''
+>>> policy = compiler.compile(json.loads(stored, parse_float=Decimal))
+>>> policy
+Ruleset(gold 20% | otherwise)
+>>> policy(Order("gold", Decimal("120.00"), 2))
+Decimal('96.0000')
+
+```
+
+### Errors
+
+The whole definition is checked when it is compiled, before any subject is evaluated.
+
+A wrong shape raises `InvalidRulesetDefinitionError` (also a `ValueError`) with its JSON
+path:
+
+```python
+>>> compiler.compile({"branches": []})
+Traceback (most recent call last):
+...
+pyruleset.exceptions.InvalidRulesetDefinitionError: Invalid ruleset at $: missing 'otherwise'
+
+```
+
+Errors from the injected compilers keep their own type. pyruleset only adds a note with the
+full JSON path, nested paths included (e.g. `at $.branches[1].when.expressions[0]`):
+
+```python
+>>> from pyspecification import RuleDoesNotExistError
+>>> typo = json.loads(stored.replace("tier__eq", "tier__is"), parse_float=Decimal)
+>>> try:
+...     compiler.compile(typo)
+... except RuleDoesNotExistError as error:
+...     print(f"{type(error).__name__}: {error}", error.__notes__)
+RuleDoesNotExistError: Rule 'tier__is' does not exist. Available rules: tier__eq, items__ge ['at $.branches[0].when']
+
+```
+
+## Money
+
+`json.loads` turns `0.80` into a binary float, which then leaks into every `Decimal` it
+touches. Keep money exact in one of two ways:
+
+- Parse with `json.loads(text, parse_float=Decimal)`, as above, so every JSON number with a
+  decimal point becomes a `Decimal` before it reaches the compiler.
+- Or, with pyformula 0.2+, build the value compiler with
+  `FormulaCompiler(variables, literal=decimal_literal)`, which converts each number literal
+  through `str` (`Decimal("0.8")`, not `Decimal(0.8)`), whoever parsed the JSON.
+
+## JSON Schema
+
+`get_ruleset_json_schema(condition_schema, value_schema)` describes a definition, e.g. to
+validate an admin form or to get completion in an editor. The two schemas describe one
+`when` and one `then`/`otherwise`. Each is embedded under its own `$id`, so the
+`#/$defs/...` refs inside it keep pointing into itself.
+
+```python
+>>> from jsonschema import Draft202012Validator
+>>> from pyspecification import get_expression_json_schema
+>>> from pyruleset import get_ruleset_json_schema
+
+>>> formula_schema = {"anyOf": [{"const": "subtotal"}, {"type": "number"}, {"type": "object"}]}
+>>> schema = get_ruleset_json_schema(get_expression_json_schema(rules), formula_schema)
+>>> validator = Draft202012Validator(schema)
+>>> validator.is_valid(json.loads(stored))
+True
+>>> validator.is_valid(json.loads(stored.replace("tier__eq", "tier__is")))
+False
+
+```
+
+`jsonschema` is only used here to show the schema at work; pyruleset does not depend on it.
+
+## First match only
+
+A ruleset picks exactly one value. There is no "all matches" mode, on purpose: each ruleset
+stays easy to read and to explain. To stack several decisions, give each part its own
+ruleset and add the results:
+
+```python
+>>> shipping = (
+...     when(items__ge(10), lambda _: Decimal("0.00"), label="free shipping")
+...     | otherwise(lambda _: Decimal("5.00"))
+... )
+>>> def total(order: Order) -> Decimal:
+...     return price(order) + shipping(order)
+>>> small = Order("regular", Decimal("60.00"), 1)
+>>> total(small), [price.explain(small), shipping.explain(small)]
+(Decimal('65.00'), ['otherwise', 'otherwise'])
+
+```
+
+Progressive brackets (tax bands) are not a ruleset either: they are a sum of clamped terms,
+one per band.
+
+## Examples
+
+Runnable scripts in [`examples/`](examples), each asserting its own results:
+
+- [`pricing_policy.py`](examples/pricing_policy.py): a JSON policy from an admin panel,
+  rejected on save with the JSON path of a typo, and `explain` for the audit log.
+- [`expense_approvals.py`](examples/expense_approvals.py): who approves an expense, with a
+  temporary "CFO on leave" override on top of the base policy.
+- [`ticket_routing.py`](examples/ticket_routing.py): each branch's value is a pyflowstep
+  `Flow` that assigns, prioritizes and tags the ticket.
+
+```bash
+uv run python examples/pricing_policy.py
+```
+
+## API reference
+
+| Name | Kind | Summary |
+| --- | --- | --- |
+| `when(condition, value, /, *, label=None) -> PartialRuleset` | function | One branch; chain more with `\|` |
+| `otherwise(value, /) -> Otherwise` | function | The fallback that closes a ruleset |
+| `Ruleset(branches, fallback)` | class | `__call__(subject)`, `decide(subject)`, `explain(subject)` |
+| `PartialRuleset(branches)` | class | `\|` with a partial, an `Otherwise` or a `Ruleset`; not callable |
+| `Branch(condition, value, label=None)` | class | One `when` pair; `str()` is its label or condition name |
+| `Otherwise(value)` | class | What `decide` returns when no branch matches |
+| `FALLBACK_LABEL` | constant | `"otherwise"`, what `explain` returns for the fallback |
+| `Condition[T]`, `Value[T, V]` | type | `Callable[[T], Any]`, `Callable[[T], V]` |
+| `RulesetCompiler(conditions, values, /)` | class | `compile(definition) -> Ruleset` |
+| `Compiler[F]` | protocol | Anything with `compile(definition, /) -> F` |
+| `RulesetDict`, `BranchDict` | type | `TypedDict`s of the JSON shape |
+| `get_ruleset_json_schema(condition_schema, value_schema, /) -> dict` | function | JSON Schema of a definition |
+| `PyrulesetError` | exception | Base class of pyruleset's errors |
+| `InvalidRulesetDefinitionError` | exception | Wrong definition shape; also a `ValueError` |
+
+## Development
+
+```bash
+uv sync
+uv run pytest --cov --cov-branch     # tests, doctests in src/ and this README, examples
+uv run --python 3.13 pytest
+uvx ruff check . && uvx ruff format --check .
+uvx pyright src
+```
+
+## License
+
+GPL-3.0-only.

pyruleset-0.1.0/pyproject.toml

@@ -0,0 +1,125 @@
+[project]
+name = "pyruleset"
+version = "0.1.0"
+description = "Conditional values: pick a value by the first matching condition, composable with | and definable as JSON."
+readme = "README.md"
+license = "GPL-3.0-only"
+requires-python = ">=3.12"
+dependencies = ["pyvocabulary>=0.1.0"]
+keywords = [
+    "rules",
+    "decision-table",
+    "policy",
+    "conditional",
+    "json",
+    "dsl",
+    "composition",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+[[project.authors]]
+name = "aaltatan"
+email = "a.altatan@gmail.com"
+
+[project.urls]
+Homepage = "https://github.com/aaltatan/pyruleset"
+Repository = "https://github.com/aaltatan/pyruleset"
+Issues = "https://github.com/aaltatan/pyruleset/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.32,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "jsonschema>=4.26.0",
+    "pyflowstep>=0.6.0",
+    "pyformula>=0.1.1",
+    "pyspecification>=2.0.2",
+    "pytest>=9.1.1",
+    "pytest-cov>=6.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = [
+    "tests",
+    "src",
+    "README.md",
+]
+pythonpath = ["."]
+addopts = [
+    "--doctest-modules",
+    "--doctest-glob=README.md",
+    "--strict-markers",
+]
+doctest_optionflags = [
+    "ELLIPSIS",
+    "NORMALIZE_WHITESPACE",
+]
+
+[tool.coverage.run]
+source = ["pyruleset"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+exclude_also = [
+    "@overload",
+    "if TYPE_CHECKING:",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "COM812",
+    "CPY001",
+    "D100",
+    "D101",
+    "D102",
+    "D103",
+    "D104",
+    "D105",
+    "D107",
+    "D203",
+    "D213",
+    "ANN401",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "S101",
+    "PLR2004",
+    "ANN",
+    "ARG",
+    "INP001",
+    "E501",
+]
+"examples/**" = [
+    "S101",
+    "T201",
+    "INP001",
+    "PT017",
+]
+
+[tool.uv.sources.pyvocabulary]
+path = "../pyvocabulary"
+editable = true
+
+[tool.pyright]
+venvPath = "."
+venv = ".venv"
+typeCheckingMode = "strict"

pyruleset-0.1.0/pyproject.toml.orig

@@ -0,0 +1,84 @@
+[project]
+name = "pyruleset"
+version = "0.1.0"
+description = "Conditional values: pick a value by the first matching condition, composable with | and definable as JSON."
+readme = "README.md"
+authors = [
+    { name = "aaltatan", email = "a.altatan@gmail.com" }
+]
+license = "GPL-3.0-only"
+requires-python = ">=3.12"
+dependencies = [
+    "pyvocabulary>=0.1.0",
+]
+keywords = ["rules", "decision-table", "policy", "conditional", "json", "dsl", "composition"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/aaltatan/pyruleset"
+Repository = "https://github.com/aaltatan/pyruleset"
+Issues = "https://github.com/aaltatan/pyruleset/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.32,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "jsonschema>=4.26.0",
+    "pyflowstep>=0.6.0",
+    "pyformula>=0.1.1",
+    "pyspecification>=2.0.2",
+    "pytest>=9.1.1",
+    "pytest-cov>=6.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "src", "README.md"]
+pythonpath = ["."]
+addopts = ["--doctest-modules", "--doctest-glob=README.md", "--strict-markers"]
+doctest_optionflags = ["ELLIPSIS", "NORMALIZE_WHITESPACE"]
+
+[tool.coverage.run]
+source = ["pyruleset"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+exclude_also = ["@overload", "if TYPE_CHECKING:"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "COM812",  # conflicts with the formatter
+    "CPY001",  # no per-file copyright headers
+    "D100", "D101", "D102", "D103", "D104", "D105", "D107", "D203", "D213",
+    "ANN401",  # JSON definitions and condition results genuinely are `Any`
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["S101", "PLR2004", "ANN", "ARG", "INP001", "E501"]
+"examples/**" = ["S101", "T201", "INP001", "PT017"]  # plain scripts that print and assert
+
+[tool.uv.sources]
+# the sibling checkout in ~/dev until pyvocabulary is published on PyPI
+pyvocabulary = { path = "../pyvocabulary", editable = true }
+
+[tool.pyright]
+venvPath = "."
+venv = ".venv"
+typeCheckingMode = "strict"

pyruleset-0.1.0/src/pyruleset/__init__.py

@@ -0,0 +1,40 @@
+"""pyruleset: conditional values that are composable and definable as JSON.
+
+Pick a value by the first condition that matches. Conditions are any
+`T -> bool` callable (a pyspecification `Predicate` fits), values any
+`T -> V` callable (a pyformula `Formula` or a pyflowstep `Flow` fits).
+"""
+
+from .compilers import BranchDict, Compiler, RulesetCompiler, RulesetDict
+from .exceptions import InvalidRulesetDefinitionError, PyrulesetError
+from .json_schema import get_ruleset_json_schema
+from .ruleset import (
+    FALLBACK_LABEL,
+    Branch,
+    Condition,
+    Otherwise,
+    PartialRuleset,
+    Ruleset,
+    Value,
+    otherwise,
+    when,
+)
+
+__all__ = [
+    "FALLBACK_LABEL",
+    "Branch",
+    "BranchDict",
+    "Compiler",
+    "Condition",
+    "InvalidRulesetDefinitionError",
+    "Otherwise",
+    "PartialRuleset",
+    "PyrulesetError",
+    "Ruleset",
+    "RulesetCompiler",
+    "RulesetDict",
+    "Value",
+    "get_ruleset_json_schema",
+    "otherwise",
+    "when",
+]

pyruleset-0.1.0/src/pyruleset/compilers.py

@@ -0,0 +1,124 @@
+"""Compile a ruleset from JSON: `{"branches": [{"when": ..., "then": ...}], "otherwise": ...}`.
+
+pyruleset does not know the expression languages inside `when` and `then`. Both
+are delegated to injected compilers, e.g. pyspecification's `PredicateCompiler`
+for conditions and pyformula's `FormulaCompiler` for values.
+"""
+
+from collections.abc import Mapping
+from typing import Any, NotRequired, Protocol, TypedDict, cast
+
+from pyvocabulary import index_path, key_path, located
+
+from .exceptions import InvalidRulesetDefinitionError
+from .ruleset import Branch, Condition, Ruleset, Value
+
+_BRANCH_KEYS = {"when", "then", "label"}
+_RULESET_KEYS = {"branches", "otherwise"}
+
+
+class BranchDict(TypedDict):
+    when: Any
+    then: Any
+    label: NotRequired[str]
+
+
+class RulesetDict(TypedDict):
+    branches: list[BranchDict]
+    otherwise: Any
+
+
+class Compiler[F](Protocol):
+    """Anything with a `compile(definition) -> F` method."""
+
+    def compile(self, definition: Any, /) -> F: ...
+
+
+class RulesetCompiler[T, V]:
+    """Compile ruleset definitions, delegating `when` and `then` to injected compilers.
+
+    Every problem is reported here, before any subject is evaluated. Errors from
+    the injected compilers keep their type and get a note with the full JSON path.
+
+    Example:
+    ```python
+    >>> class Field:
+    ...     def compile(self, name):
+    ...         return lambda subject: subject[name]
+    >>> compiler = RulesetCompiler(Field(), Field())
+    >>> ruleset = compiler.compile({
+    ...     "branches": [{"when": "vip", "then": "vip_price", "label": "vip"}],
+    ...     "otherwise": "price",
+    ... })
+    >>> ruleset
+    Ruleset(vip | otherwise)
+    >>> ruleset({"vip": True, "vip_price": 80, "price": 100})
+    80
+
+    ```
+
+    """
+
+    __slots__ = ("_conditions", "_values")
+
+    def __init__(
+        self, conditions: Compiler[Condition[T]], values: Compiler[Value[T, V]], /
+    ) -> None:
+        self._conditions = conditions
+        self._values = values
+
+    def compile(self, definition: RulesetDict | Mapping[str, Any], /) -> Ruleset[T, V]:
+        """Compile `definition` into a `Ruleset`.
+
+        Raises:
+            InvalidRulesetDefinitionError: If the definition has the wrong shape.
+
+        """
+        _check_keys(definition, required={"otherwise"}, allowed=_RULESET_KEYS, path="$")
+        branches = definition.get("branches", [])
+        if not isinstance(branches, list):
+            msg = f"Invalid ruleset at $.branches: expected a list, received {branches!r}"
+            raise InvalidRulesetDefinitionError(msg)
+
+        path = key_path("$", "branches")
+        compiled = tuple(
+            self._compile_branch(branch, index_path(path, index))
+            for index, branch in enumerate(cast("list[Any]", branches))
+        )
+        with located(key_path("$", "otherwise"), Exception):
+            fallback = self._values.compile(definition["otherwise"])
+
+        return Ruleset(compiled, fallback)
+
+    def _compile_branch(self, branch: Any, path: str) -> Branch[T, V]:
+        _check_keys(branch, required={"when", "then"}, allowed=_BRANCH_KEYS, path=path)
+
+        label = branch.get("label")
+        if label is not None and not isinstance(label, str):
+            msg = f"Invalid branch at {path}.label: expected a string, received {label!r}"
+            raise InvalidRulesetDefinitionError(msg)
+
+        with located(key_path(path, "when"), Exception):
+            condition = self._conditions.compile(branch["when"])
+        with located(key_path(path, "then"), Exception):
+            value = self._values.compile(branch["then"])
+
+        return Branch(condition, value, label)
+
+
+def _check_keys(item: Any, *, required: set[str], allowed: set[str], path: str) -> None:
+    if not isinstance(item, Mapping):
+        msg = f"Invalid ruleset at {path}: expected an object, received {item!r}"
+        raise InvalidRulesetDefinitionError(msg)
+
+    keys = set(cast("Mapping[str, Any]", item))
+    if missing := sorted(required - keys):
+        msg = f"Invalid ruleset at {path}: missing {', '.join(map(repr, missing))}"
+        raise InvalidRulesetDefinitionError(msg)
+
+    if unknown := sorted(keys - allowed):
+        msg = (
+            f"Invalid ruleset at {path}: unknown {', '.join(map(repr, unknown))}. "
+            f"Allowed keys: {', '.join(sorted(allowed))}"
+        )
+        raise InvalidRulesetDefinitionError(msg)

pyruleset-0.1.0/src/pyruleset/exceptions.py

@@ -0,0 +1,14 @@
+"""Exceptions raised by pyruleset.
+
+Errors raised by the injected condition and value compilers keep their own type
+(e.g. pyspecification's `RuleDoesNotExistError`); pyruleset only adds a note
+with their full JSON path, e.g. `at $.branches[1].when.expressions[0]`.
+"""
+
+
+class PyrulesetError(Exception):
+    """Base class for every exception raised by pyruleset."""
+
+
+class InvalidRulesetDefinitionError(PyrulesetError, ValueError):
+    """Raised when a ruleset definition does not have the expected shape."""

pyruleset-0.1.0/src/pyruleset/json_schema.py

@@ -0,0 +1,65 @@
+"""The JSON Schema of a ruleset definition, as accepted by `RulesetCompiler.compile`.
+
+pyruleset does not know the languages inside `when` and `then`, so their schemas
+are passed in, e.g. pyspecification's `get_expression_json_schema(rules)`.
+"""
+
+from collections.abc import Mapping
+from typing import Any
+
+from pyvocabulary import JSON_SCHEMA_DIALECT
+
+CONDITION_SCHEMA_ID = "urn:pyruleset:condition"
+VALUE_SCHEMA_ID = "urn:pyruleset:value"
+
+
+def get_ruleset_json_schema(
+    condition_schema: Mapping[str, Any],
+    value_schema: Mapping[str, Any],
+    /,
+) -> dict[str, Any]:
+    """Return the JSON Schema of `{"branches": [{"when", "then", "label"}], "otherwise"}`.
+
+    Each sub-schema is embedded under its own `$id`, so the `#/$defs/...` refs it
+    uses internally keep pointing into itself rather than into the ruleset schema.
+
+    Args:
+        condition_schema: The schema of one `when`, e.g. a pyspecification expression.
+        value_schema: The schema of one `then` and of `otherwise`.
+
+    Example:
+    ```python
+    >>> schema = get_ruleset_json_schema({"type": "string"}, {"type": "number"})
+    >>> schema["required"], schema["properties"]["otherwise"]
+    (['otherwise'], {'$ref': 'urn:pyruleset:value'})
+    >>> schema["$defs"]["value"]
+    {'type': 'number', '$id': 'urn:pyruleset:value'}
+
+    ```
+
+    """
+    branch = {
+        "type": "object",
+        "properties": {
+            "when": {"$ref": CONDITION_SCHEMA_ID},
+            "then": {"$ref": VALUE_SCHEMA_ID},
+            "label": {"type": "string"},
+        },
+        "required": ["when", "then"],
+        "additionalProperties": False,
+    }
+    return {
+        "$schema": JSON_SCHEMA_DIALECT,
+        "type": "object",
+        "properties": {
+            "branches": {"type": "array", "items": {"$ref": "#/$defs/branch"}},
+            "otherwise": {"$ref": VALUE_SCHEMA_ID},
+        },
+        "required": ["otherwise"],
+        "additionalProperties": False,
+        "$defs": {
+            "branch": branch,
+            "condition": {**condition_schema, "$id": CONDITION_SCHEMA_ID},
+            "value": {**value_schema, "$id": VALUE_SCHEMA_ID},
+        },
+    }

pyruleset-0.1.0/src/pyruleset/ruleset.py

@@ -0,0 +1,174 @@
+"""Conditional values: the first branch whose condition matches decides.
+
+```python
+price = (
+    when(is_gold(), subtotal * Decimal("0.80"), label="gold 20%")
+    | when(items__ge(10), subtotal * Decimal("0.95"), label="bulk 5%")
+    | otherwise(subtotal)
+)
+```
+
+A chain without `otherwise` is a `PartialRuleset`: it composes, but it has no
+`__call__`, so a missing fallback is a type error instead of a `None` at run time.
+"""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, overload
+
+type Condition[T] = Callable[[T], Any]
+type Value[T, V] = Callable[[T], V]
+
+FALLBACK_LABEL = "otherwise"
+
+
+@dataclass(frozen=True, slots=True)
+class Branch[T, V]:
+    """One `when(condition, value)` pair, optionally labelled for `explain` and `repr`."""
+
+    condition: Condition[T]
+    value: Value[T, V]
+    label: str | None = None
+
+    def __str__(self) -> str:
+        return self.label or _name_of(self.condition)
+
+
+@dataclass(frozen=True, slots=True)
+class Otherwise[T, V]:
+    """The fallback that closes a ruleset. Build it with `otherwise(value)`."""
+
+    value: Value[T, V]
+
+
+@dataclass(frozen=True, slots=True)
+class Ruleset[T, V]:
+    """Branches tried in order, then a fallback. Calling it returns the decided value.
+
+    Example:
+    ```python
+    >>> sign = (
+    ...     when(lambda n: n < 0, lambda _: "negative", label="below zero")
+    ...     | when(lambda n: n == 0, lambda _: "zero", label="zero")
+    ...     | otherwise(lambda _: "positive")
+    ... )
+    >>> sign
+    Ruleset(below zero | zero | otherwise)
+    >>> [sign(n) for n in (-2, 0, 5)]
+    ['negative', 'zero', 'positive']
+    >>> sign.explain(-2), sign.explain(5)
+    ('below zero', 'otherwise')
+
+    ```
+
+    """
+
+    branches: tuple[Branch[T, V], ...]
+    fallback: Value[T, V]
+
+    def __call__(self, subject: T, /) -> V:
+        return self.decide(subject).value(subject)
+
+    def decide(self, subject: T, /) -> "Branch[T, V] | Otherwise[T, V]":
+        """Return the branch that decides for `subject`, or the fallback."""
+        return next(
+            (branch for branch in self.branches if branch.condition(subject)),
+            Otherwise(self.fallback),
+        )
+
+    def explain(self, subject: T, /) -> str:
+        """Name the branch that decides for `subject`, e.g. for an audit log."""
+        match self.decide(subject):
+            case Branch() as branch:
+                return str(branch)
+            case _:
+                return FALLBACK_LABEL
+
+    def __repr__(self) -> str:
+        return f"Ruleset({' | '.join([*map(str, self.branches), FALLBACK_LABEL])})"
+
+
+@dataclass(frozen=True, slots=True)
+class PartialRuleset[T, V]:
+    """Branches without a fallback. It composes with `|`, but it cannot be called.
+
+    Example:
+    ```python
+    >>> overrides = when(lambda n: n == 13, lambda _: "unlucky", label="13")
+    >>> overrides
+    PartialRuleset(13)
+    >>> callable(overrides)
+    False
+    >>> base = when(lambda n: n % 2 == 0, lambda _: "even", label="even") | otherwise(
+    ...     lambda _: "odd"
+    ... )
+    >>> combined = overrides | base
+    >>> combined, combined(13), combined(4)
+    (Ruleset(13 | even | otherwise), 'unlucky', 'even')
+
+    ```
+
+    """
+
+    branches: tuple[Branch[T, V], ...]
+
+    @overload
+    def __or__(self, other: "PartialRuleset[T, V]", /) -> "PartialRuleset[T, V]": ...
+    @overload
+    def __or__(self, other: Otherwise[T, V] | Ruleset[T, V], /) -> Ruleset[T, V]: ...
+    def __or__(
+        self,
+        other: "PartialRuleset[T, V] | Otherwise[T, V] | Ruleset[T, V]",
+        /,
+    ) -> "PartialRuleset[T, V] | Ruleset[T, V]":
+        match other:
+            case PartialRuleset(branches=branches):
+                return PartialRuleset((*self.branches, *branches))
+            case Otherwise(value=value):
+                return Ruleset(self.branches, value)
+            case Ruleset(branches=branches, fallback=fallback):
+                return Ruleset((*self.branches, *branches), fallback)
+            case _:
+                return NotImplemented
+
+    def __repr__(self) -> str:
+        return f"PartialRuleset({' | '.join(map(str, self.branches))})"
+
+
+def when[T, V](
+    condition: Condition[T],
+    value: Value[T, V],
+    /,
+    *,
+    label: str | None = None,
+) -> PartialRuleset[T, V]:
+    """Start a ruleset, or one more branch to chain with `|`.
+
+    Args:
+        condition: Decides whether this branch applies, e.g. a pyspecification `Predicate`.
+        value: Computes the result, e.g. a pyformula `Formula` or a pyflowstep `Flow`.
+        label: Names the branch in `explain` and `repr`. Defaults to the condition's name.
+
+    """
+    return PartialRuleset((Branch(condition, value, label),))
+
+
+def otherwise[T, V](value: Value[T, V], /) -> Otherwise[T, V]:
+    """Close a ruleset with the value used when no branch matches.
+
+    Example:
+    ```python
+    >>> (when(bool, str.upper) | otherwise(str.lower))("Hi")
+    'HI'
+
+    ```
+
+    """
+    return Otherwise(value)
+
+
+def _name_of(function: Callable[..., Any]) -> str:
+    # Predicates and formulas print their own name; plain functions use `__name__`.
+    if type(function).__str__ is not object.__str__:
+        return str(function)
+    return getattr(function, "__name__", repr(function))