API

class pypagate.Bucket(universe: Universe, condition: Callable[[Term], bool])

A linear-time spatial partition to restrict O(N^k) Law searches.

class pypagate.Formula(_value: Any = None, unary_op: Callable[[Any], Any] | None = None, bin_op: Callable[[Any, Any], Any] | None = None, operands: list['Formula' | 'Term'] = <factory>, _parents: list[Formula | Law] = <factory>, _binds: Any = <factory>, _fire_on: list[Callable] = <factory>, _on_change: list[Callable] = <factory>, _needs_update: bool = True)

A Well-Formed-Formula that consists of Term objects (i.e. variables) and operators.

unwrap()

Get the value the formula currently evaluates to.

class pypagate.Law(universe: 'Universe', variables: 'list[Variable]' = <factory>, unary_op: 'Callable[[Any], Any] | None' = None, bin_op: 'Callable[[Any, Any], Any] | None' = None, operands: "list['Law' | 'Variable' | 'Term' | 'Formula']" = <factory>, _parents: 'list[Law]' = <factory>, _binds: 'Any' = <factory>, _fire_on: 'list[Callable]' = <factory>, _on_change: 'list[Callable]' = <factory>, _needs_update: 'bool' = True, _var_count: 'int' = 0, _specializations: 'list[Formula]' = <factory>, _true_cache: 'dict[int, Formula]' = <factory>, _false_cache: 'dict[int, Formula]' = <factory>)
class pypagate.Term(_value: Any = None, _parents: list[Formula | Law] = <factory>, _binds: list[tuple[~typing.Any, ~typing.Any]]=<factory>, _fire_on: list[Callable] = <factory>, _on_change: list[Callable] = <factory>, _var_count: int = 0)

Essentially a variable that may be updated by the user. Can be included in more complicated formula and whenever it is changed, the parent formula are also updated to reflect this change.

change(new_value)

Change the wrapped value of the term. (Internally updates formulas that use this term.)

Parameters:

new_value – The value to change self.value to.

unwrap()

Returns the value of the Term at the current moment.

class pypagate.Universe(entities: 'list[Term]' = <factory>)
class pypagate.Variable(universe: 'Universe', _var_count: 'int' = 1, _temp_value: 'Any' = None, _parents: 'list[Law]' = <factory>)
pypagate.as_float(f: Term | Formula)

Floatify the contents of a Formula. If you want to actually extract the values of a Formula, call float on it.

Params f:

The formula to convert.

pypagate.as_int(f: Term | Formula)

Intify the contents of a Formula. If you want to actually extract the values of a Formula, call int on it.

Params f:

The formula to convert.

pypagate.as_str(f: Term | Formula)

Stringify the contents of a Formula. If you want to actually extract the values of a Formula, call str on it.

Params f:

The formula to convert.

pypagate.bind(obj: Any, field_name: Any, form: Formula | Term)

Given an object and a field name, you can “bind” it to a Formula (or Term). That is, whenever the Formula (or Term) is updated, the field for the object is also updated.

Parameters:

  • obj – The object to update.

  • field_name – The field specific field of obj to change.

  • form – A Formula or Term that obj.field is updated to be equivalent to.

pypagate.either(form: Formula | Term, f: Callable[[], None], g: Callable[[], None])

Creates a new function with name name that, when called, executes f when form is True and g when form is False.

Parameters:

  • form – Formula to test.

  • f – Function to evaluate when form is True.

  • g – Function to evaluate when form is False

pypagate.evaluate(form: Formula | Term) → Any

Given a Term or Formula get the current value it contains. For terms this is the same as .unwrap() method, but for for Formula, the entire expression is recursively evaluated.

Parameters:

form (class: Formula | Term) – A formula (or term) to extract the current value of.

Returns:

The current value of the Formula or Term.

pypagate.fire_on(form: Formula | Term, *args, **kwargs)

Use as a decorator: If a Formula’s truthiness is True, call the decorated function.

Parameters:

  • form – Execute the proceeding function if form evaluates to True at some point in time.

  • args – Additional positional arguments to pass to the decorated function.

  • kwargs – Additional keyword arguments to pass to the decorated function.

pypagate.fire_on_all(law, *args, **kwargs)

Raw Evaluation: Bypasses the cache and queries the Universe directly.

pypagate.fire_on_each(law: Law, *args, **kwarg)

Use as a decorator: If some specialization of a Law’s truthiness is True, call the decorated function.

Parameters:

  • form – Execute the proceeding function if form evaluates to True at some point in time.

  • args – Additional positional arguments to pass to the decorated function.

  • kwargs – Additional keyword arguments to pass to the decorated function.

pypagate.fire_on_some(law, n: int, *args, **kwargs)

Raw Evaluation: Bypasses the cache and queries the Universe directly.

pypagate.on_change(form: Formula | Term, *args, **kwargs)

Use as a decorator: If a Formula’s truthiness is True, call the decorated function.

Parameters:

  • form – Execute the proceeding function if form evaluates to True at some point in time.

  • args – Additional positional arguments to pass to the decorated function.

  • kwargs – Additional keyword arguments to pass to the decorated function.

pypagate.permit(form: Formula | Term, *args, **kwargs)

Use as a decorator: If a Formula’s truthiness is True, allow the decorated function to be called, otherwise calling the decorated function does nothing.

Parameters:

  • form – Allow execution of the proceeding function if form evaluates to true at the time of calling the proceeding function.

  • args – Additional positional arguments to pass to the decorated function.

  • kwargs – Additional keyword arguments to pass to the decorated function.

class pypagate.source.SourceMap(terms: dict[str, Number])

A collection of Terms (with starting values) where Terms can be updated with the listen method.

listen(terms: dict[str, Number])

Take in a new set of values and update them all.

Parameters:

terms – Dictionary of terms to take in and “listen” too. These will then update the values in self.

pypagate.source.exec_always(source)

Use as a decorator: Every time source.listen(…) is called, evaluate this function.

Parameters:

source – The source that triggers listen(…).

pypagate.source.exec_either(form, f, g, source)

Either executes f if form evaluates to True or g if form evaluates to False whenever source.listen(...) is called.

Parameters:

  • form – The Formula to test against.

  • f – The function to execute if form is True.

  • g – The function to execute if form is False.

  • source – Either f or g is executed whenever source.listen(…) is called.

pypagate.source.exec_while(form, source)

Use as a decorator: Every time source.listen(…) is called and the formula evaluates to True, execute this function.

Parameters:

  • form – The formula to check if it evaluates to True.

  • source – The source that triggers listen(…).