Directives¶

Directives are inline comments that control how lectrace traces and displays your code. They follow the # @name syntax and sit at the end of a line.

x = 42  # @inspect x

@inspect¶

Show the value of one or more variables in the variable panel after this line executes.

x = [1, 2, 3]         # @inspect x
y = x[0] + x[-1]      # @inspect y
a, b = 10, 20         # @inspect a b

Multiple variables are separated by spaces. You can also inspect object attributes:

node = Node(val=5)    # @inspect node.val node.left

The variable panel accumulates values as you step forward — once a variable appears it stays visible until cleared with @clear.

Inside helper functions: you do not need @inspect at all. When the viewer steps into any called function, all local variables are shown automatically. @inspect is only needed in main() to select which variables to highlight.

Bare @inspect in main(): omit the variable names to show all locals at that point:

result = compute()   # @inspect   ← shows everything in scope here

@clear¶

Remove a variable from the variable panel.

temp = compute_intermediate()  # @inspect temp
result = finalize(temp)        # @inspect result
temp                           # @clear temp

Use it to keep the panel tidy — scaffolding variables that were only relevant for a few steps can be hidden once you've moved past them.

@stepover¶

Skip the body of a function call — trace over it as a single step rather than entering it.

def sort(arr):       # called many times — noise in the viewer
    ...

data = [3, 1, 4]
data = sort(data)    # @stepover  ← one step, no internals shown

This is especially useful for utility functions, recursive helpers, or library calls that students don't need to follow line by line.

@hide¶

Hide this line from the source code panel. The line still executes and still produces a trace step — it just doesn't appear in the code view.

assert isinstance(root, Node)  # @hide  ← sanity check, not relevant to lecture
logging.debug("here")          # @hide

Use it for assertions, debug prints, and any code that is correct but distracting.

@invisible¶

Completely remove this line from the viewer — no trace step is recorded and the line is hidden from the source code panel. The line still executes normally; any variables assigned on it are available to subsequent steps.

import matplotlib.pyplot as plt
from lectrace import text, plot

def main():
    text("# My Plot")

    x = [1, 2, 3, 4, 5]
    y = [1, 4, 9, 16, 25]

    ax = plt.subplot()     # @invisible
    ax.scatter(x, y)       # @invisible
    ax.set_title("y = x²") # @invisible
    plot(ax)
    plt.show()             # @invisible

The viewer steps are only text(...), x = ..., y = ..., plot(ax). The matplotlib setup lines are completely absent.

Combining directives¶

Multiple directives on the same line are all applied:

x = compute()  # @inspect x @stepover

This inspects x after the line runs and steps over the compute() call.

Helper files¶

Files named with a leading underscore (_utils.py, _data.py) are excluded from the viewer automatically — they're imported as normal Python modules but never traced or shown in the sidebar.

from _data import sample_arrays   # helper — not traced

def main():
    arr = sample_arrays[0]  # @inspect arr
    ...