ptera.overlay

class ptera.overlay.BaseOverlay(*handlers)

An Overlay contains a set of selectors and associated rules.

When used as a context manager, the rules are applied within the with block.

Parameters

handlers – A collection of handlers, each typically an instance of either Immediate or Total.

add(*handlers)

Add new handlers.

fork()

Create a clone of this overlay.

class ptera.overlay.HandlerCollection(handler_pairs=None)

List of (selector, accumulator) pairs.

The selector in the pair may not be the same as accumulator.selector. When processing a selector such as f > g > x, after entering f, we may map the g > x selector to the same accumulator in a new collection that represents what should be done inside f.

plus(handler_pairs)

Clone this collection with additional (selector, accumulator) pairs.

proceed(fn)

Proceed into a call to fn with this collection.

Considers each selector to see if it matches fn. Returns an Interactor object for the call and a new HandlerCollection with the selectors to use inside the call.

class ptera.overlay.Overlay(*handlers)

An Overlay contains a set of selectors and associated rules.

When used as a context manager, the rules are applied within the with block.

Rules can be given in the constructor or built using helper methods such as on, tapping or tweaking.

Parameters

handlers – A collection of handlers, each typically an instance of either Immediate or Total.

on(selector, **kwargs)

Make a decorator for a function to trigger on a selector.

Parameters

• selector – The selector to use.

• full – (default False) Whether to return a dictionary of Capture objects.

• all – (default False) If not full, whether to return a list of results for each variable or a single value.

• immediate – (default True) Whether to use an Immediate() accumulator. If False, use a Total() accumulator.

register(selector, fn, full=False, all=False, immediate=True)

Register a function to trigger on a selector.

Parameters

• selector – The selector to use.

• fn – The function to register.

• full – (default False) Whether to return a dictionary of Capture objects.

• all – (default False) If not full, whether to return a list of results for each variable or a single value.

• immediate – (default True) Whether to use an Immediate accumulator. If False, use a Total accumulator.

rewrite(rewriters, full=False)

Override the focus variables of selectors.

Parameters

rewriters – A {selector: override_function} dictionary.

rewriting(values, full=False)

Fork this Overlay and rewrite().

Can be called on the class (with Overlay.rewriting(...):).

tap(selector, dest=None, **kwargs)

Tap values from a selector into a list.

Parameters

• selector – The selector to use.

• dest – The list in which to append. If None, a list is created.

Returns

The list in which to append.

tapping(selector, dest=None, **kwargs)

Context manager yielding a list in which results will be accumulated.

Can be called on the class (with Overlay.tapping(...):).

tweak(values)

Override the focus variables of selectors.

Parameters

values – A {selector: value} dictionary.

tweaking(values)

Fork this Overlay and tweak().

Can be called on the class (with Overlay.tweaking(...):).

ptera.overlay.autotool(selector, undo=False)

Automatically tool functions inplace.

Parameters

selector – The selector to use as a basis for the tooling. Any function it refers to will be tooled.

ptera.overlay.fits_selector(pfn, selector)

Check whether a PteraFunction matches a selector.

Parameters

• pfn – The PteraFunction.

• selector – The selector. We are trying to match the outer scope.

class ptera.overlay.proceed(fn)

Context manager to wrap execution of a function.

This uses the current HandlerCollection to proceed through the current selectors.

Parameters

fn – The function that will be executed.

Yields

An Interactor that will be used by Ptera.

ptera.overlay.tooled(fn)

Tool a function so that it can report changes in its variables to Ptera.

@tooled can be used as a decorator.

Note

You may write @tooled.inplace as a decorator to tool a function inplace.

Parameters

fn – The function to tool.