ptera.transform

Code transform that instruments probed functions.

class ptera.transform.ExternalVariableCollector(tree, comments, closure_vars)

Collect variables referred to but not defined in the given AST.

The attributes are filled after the object is created.

used

Set of used variable names (does not include the names of inner functions).

assigned

Set of assigned variable names.

vardoc

Dict that maps variable names to matching comments.

provenance

Dict that maps variable names to “body” or “argument” if they are defined as variables in the body or as function arguments.

funcnames

Set of function names defined in the body.

class ptera.transform.Key(type, value)

Represents an attribute or index on a variable.

type

Either “attr” or “index”.

value

The value of the attribute or index.

affix_to(sym)

Return a string representing getting the key from sym.

>>> Key("attr", "y").affix_to("x")
"x.y"
>>> Key("index", "y").affix_to("x")
"x['y']"

exception ptera.transform.PteraNameError(varname, function)

The Ptera equivalent of a NameError, which gives more information.

info()

Return information about the missing variable.

class ptera.transform.PteraTransformer(tree, evc, lib, filename, glb, to_instrument)

Transform the AST of a function to instrument it with ptera.

The result field is set to the AST of the transformed function after instantiation of the PteraTransformer.

make_interaction(target, ann, value, orig=None, expression=False)

Create code for setting the value of a variable.

visit_AnnAssign(node)

Rewrite an annotated assignment statement.

Before:

x: int

After:

x: int = _ptera_interact(‘x’, int)

visit_Assign(node)

Rewrite an assignment statement.

Before:

x = y + z

After:

x = _ptera_interact(‘x’, None, y + z)

visit_Import(node)

Rewrite an import statement.

Before:

import kangaroo

After:

import kangaroo kangaroo = _ptera_interact(‘kangaroo’, None, kangaroo)

visit_ImportFrom(node)

Rewrite an import statement.

Before:

from kangaroo import jump

After:

from kangaroo import jump jump = _ptera_interact(‘jump’, None, jump)

visit_NamedExpr(node)

Rewrite an assignment expression.

Before:

x := y + z

After:

x := _ptera_interact(‘x’, None, y + z)

class ptera.transform.SimpleVariableCollector(tree)

ptera.transform.name_error(varname, function, pop_frames=1)

Raise a PteraNameError pointing to the right location.

ptera.transform.transform(fn, proceed, to_instrument=True, set_conformer=True)

Return an instrumented version of fn.

The transform roughly works as follows.

def f(x: int):
    y = x * x
    return y + 1

Becomes:

def f(x: int):
    with proceed(f) as FR:
        FR.interact("#enter", None, None, True, False)
        x = FR.interact("x", None, int, x, True)
        y = FR.interact("y", None, None, x * x, True)
        VALUE = FR.interact("#value", None, None, y + 1, True)
        return VALUE

Parameters

• fn – The function to instrument.

• proceed – A context manager that will wrap the function body and which should yield some object that has an interact method. Whenever a variable is changed, the interact method receives the arguments (symbol, key, category, value, overridable). See proceed and interact.

• to_instrument – List of Element representing the variables to instrument, or True. If True (or if one Element is a generic), all variables are instrumented.

• set_conformer – Whether to set a “conformer” on the resulting function which will update the code when the original code is remapped through the codefind module (e.g. if you use jurigged to change source while it is running, the conformer will update the instrumentation to correspond to the new version of the function). Mostly for internal use.

Returns

A new function that is an instrumented version of the old one. The function has the following properties set:

• __ptera_info__: An info dictionary about all variables used in the function, their provenance, annotations and comments.

• __ptera_token__: The name of the global variable in which the function is tucked so that it can refer to itself.