ptera.interpret

Create events on transformed functions based on selectors.

There are some extra features here compared to the standard Probe interface, namely Total which can accumulate multiple values for non-focus variables and is only triggered when the selector’s outer function finishes.

class ptera.interpret.BaseAccumulator(*, selector, intercept=None, trigger=None, close=None, parent=None, template=True, check=True, pass_info=False)

Accumulates the values of variables in Capture objects.

Under certain conditions, call user-provided event functions.

Any function given to the constructor must take one argument which is the dictionary of captures.

Parameters

  • selector – The selector to use.

  • trigger – The function to call when the focus variable is set.

  • intercept – The function to call to override the value of the focus variable.

  • close – The function to call when the selector is closed.

  • parent – The parent Accumulator.

  • template – Whether the Accumulator is a “template” and should be cloned prior to accumulating anything.

  • check – Whether to filter that the values are correct in a selector such as f(x=1) > y. Otherwise the =1 would be ignored.

  • pass_info – Whether to pass the accumulator and current triggered element to trigger or intercept.

build()

Build the dictionary of captures.

The built dictionary includes captures from the parents.

fork(selector=None)

Fork the Accumulator, possibly with a new selector.

Children Accumulators can accumulate new data while sharing what is accumulated by their parents.

getcap(element)

Get the Capture object for a leaf element.

class ptera.interpret.Capture(element)

Represents captured values for a variable.

Parameters

element – The selector element for which we are capturing.

element

The selector element for which we are capturing.

capture

The variable name or alias corresponding to the capture (same as element.capture).

names

The list of names of the variables that match the element.

values

The list of values taken by matching variables.

accum(varname, value)

Accumulate a variable name and value.

property name

Name of the capture.

For a generic element such as $x, there may be multiple names, in which case the .names attribute should be used instead.

set(varname, value)

Set a variable name and value, overwriting the previous capture.

snapshot()

Return a snapshot of the capture at this moment.

property value

Value of the capture.

This only works if there is a unique value. Otherwise, you must use .values.

class ptera.interpret.Immediate(selector, trigger=None, **kwargs)

Accumulator triggered when the focus variable is set.

The Immediate accumulator only keeps the last value of each variable in the selector.

Any function given to the constructor must take one argument which is the dictionary of captures.

Parameters

  • selector – The selector to use.

  • trigger – The function to call when the focus variable is set.

  • intercept – The function to call to override the value of the focus variable.

  • close – The function to call when the selector is closed.

class ptera.interpret.Interactor(fn, accumulators=None)

Represents an interactor for a tooled function.

Define an interact method called by the tooled function when variables are changed.

exit()

Exit the interactor.

This triggers the close function on available accumulators.

interact(varname, key, category, value, overridable)

Interaction function called when setting a variable in a tooled function.

Parameters

  • varname – The variable’s name.

  • key – The attribute or index set on the variable (as a Key object)

  • category – The variable’s category or tag (annotation)

  • value – The value given to the variable in the original code.

  • overridable – Whether the value can be overriden.

Returns

The value to actually set the variable to.

register(acc, captures, close_at_exit)

Register an accumulator for a certain set of captures.

Parameters

  • acc – An Accumulator.

  • captures – A dictionary of elements to sets of matching variable names for which the accumulator will be triggered.

  • close_at_exit – Whether to call the accumulator’s close function when the interactor exits.

work_on(varname, key, category)

Return a WorkingFrame for the given variable.

Parameters

  • varname – The name of the variable.

  • key – The key (attribute or index) that is being set on the variable.

  • category – The variable’s category or tag.

exception ptera.interpret.OverrideException

Exception raised when trying to override a closure variable.

class ptera.interpret.Total(selector, close, trigger=None, **kwargs)

Accumulator usually triggered when the selector’s outer function ends.

The Total accumulator keeps all values taken by the variables in the selector for each value taken by the focus variable. For example, if the selector is f(x) > g(!y) > h(z) and h is called multiple times for multiple values of z, they will all be accumulated together. However, if y is set multiple times, there will be multiple events.

Any function given to the constructor must take one argument which is the dictionary of captures.

Parameters

  • selector – The selector to use.

  • close – The function to call when the selector is closed.

  • trigger – The function to call when the focus variable is set.

  • intercept – The function to call to override the value of the focus variable.

class ptera.interpret.WorkingFrame(varname, key, category, accumulators)

Context manager to facilitate working on a variable.

intercept(tentative)

Execute the intercepts of all matching accumulators.

The last intercept that does not return ABSENT wins.

Parameters

tentative – The tentative value for the variable, as provided in the original code.

Returns

The value the intercepted variable should take.

log(value)

Log a value for the variable.

trigger()

Trigger an event using what was accumulated.