Utilities & globals

Smaller helpers and constants that round out the public surface. All are importable from the top-level pyccolo package.

Tracer stack & contexts

pyccolo.tracer() → BaseTracer

pyccolo.instance() → BaseTracer

pyccolo.resolve_tracer(ref: str) → Type[BaseTracer]

pyccolo.multi_context(cms)

pyccolo.tracing_context(tracers=None, *args, **kwargs)

pyccolo.tracing_enabled(tracers=None, **kwargs)

pyccolo.tracing_disabled(tracers=None, **kwargs)

pyccolo.instrumented(tracers: List[BaseTracer], mutate: bool = False) → Callable[[Callable[[...], Any]], Callable[[...], Any]]

pyccolo.allow_reentrant_event_handling()

Frames & guards

pyccolo.set_frame_local(frame: FrameType, name: str, value: Any) → None

Assign name = value in frame’s local scope so a running function observes the write.

A frame’s f_locals is normally a read-only view from the outside: on CPython < 3.13 it is a snapshot dict, and mutating it does not touch the frame’s fast-locals array unless PyFrame_LocalsToFast copies the snapshot back. On 3.13+ (PEP 667) f_locals is a write-through proxy, so assigning to it is sufficient. This is the primitive pipescript uses to give macro block bodies write-back semantics into their enclosing function.

Only names that already have a local slot in frame (function parameters and variables assigned somewhere in the enclosing function) are guaranteed to persist; PyFrame_LocalsToFast will not create a brand-new fast slot.

pyccolo.make_guard_name(node: int | AST)

pyccolo.PYCCOLO_BUILTIN_PREFIX

The prefix used for the synthetic builtins Pyccolo injects (guard names, macro hooks). Handy when generating guard names or namespacing your own injected symbols.

Traceback visibility

By default, frames from sandboxed exec/eval code are hidden from tracebacks. These let you opt specific sandbox files back in.

pyccolo.mark_traceback_visible(filename: str) → None

Mark filename as a sandbox file worth showing in tracebacks.

pyccolo.is_traceback_visible(filename: str) → bool

Whether filename was marked visible via mark_traceback_visible().

Sentinels

The handler return-value sentinels are documented with the handler contract: Null, Skip, SkipAll, and Pass.