Data model

These are the classes that make up ipyflow’s dataflow graph. The The dataflow model page explains how they fit together; this page is the class reference. They are internal-heavy – only the user-facing members are documented here.

Timestamp

class ipyflow.data_model.timestamp.Timestamp(cell_num: int, stmt_num: int)[source]

A (cell_num, stmt_num) pair naming one point in execution.

cell_num is the cell execution counter (1-indexed, strictly increasing across the session); stmt_num is the 0-indexed statement within that cell execution. Comparing the timestamp of a symbol against those of its dependencies is how ipyflow decides staleness.

cell_num: int: Alias for field number 0

stmt_num: int: Alias for field number 1

classmethod current() → Timestamp[source]: Return the timestamp of the currently-executing point.

property is_initialized: bool: Whether this is a real timestamp (not the sentinel uninitialized one).

Symbol

Obtain a Symbol from a value with lift(value), or from the graph via the deps / users helpers.

A node in the dataflow graph: a variable binding or object member.

A Symbol tracks the name it is bound under, a reference to the underlying Python object (obj), the Timestamp at which it was last written, and its dataflow edges – parents (the symbols it was computed from) and children (the symbols computed from it). The public ipyflow.api helpers (deps, users, code, timestamp, …) are thin wrappers that resolve a value to its Symbol and read these attributes. Use lift(value) to obtain one directly.

add_tag(tag_value: str) → None[source]: Attach the string tag tag_value to this symbol.

remove_tag(tag_value: str) → None[source]: Remove the string tag tag_value from this symbol (a no-op if absent).

has_tag(tag_value: str) → bool[source]: Return whether this symbol carries the tag tag_value.

property timestamp: Timestamp: The Timestamp of the last write, accounting for updates to the symbol’s namespace members.

code(format_type: Type[FormatType] | None = None, version: int = -1) → Slice[source]

Return the backward program slice that reconstructs this symbol.

Parameters:

format_type – optional output format (e.g. str); defaults to a rich HTML when available, otherwise plain text.
version – which historical version of the symbol to slice for. -1 (the default) is the current version.

property readable_name: str: The human-readable, namespace-qualified name of this symbol.

property is_waiting: bool: Whether this symbol is stale – i.e. a dependency has a newer timestamp.

In addition to the documented members above, a Symbol exposes obj (the underlying object), parents and children (the dataflow edges, as dicts keyed by Symbol), and containing_scope.

Cell

Access cells with cells() (the class) and cells(id) (an instance); see Model accessors (ipyflow.models).

class ipyflow.data_model.cell.Cell(cell_id: str | int, cell_ctr: int, content: str, tags: Tuple[str, ...], prev_cell: Cell | None = None, placeholder_id: bool = False, memoized_output_level: MemoizedOutputLevel | None = None)[source]

A notebook code cell and its place in the dataflow graph.

Each Cell records the frontend cell_id, the execution counter cell_ctr at which it ran, its source content, its tags, and its position in the notebook. Cell-to-cell dataflow edges are derived from the symbol edges the tracer records. Access cells with the cells() accessor: cells() returns this class (use classmethods like at_counter and current_cell), and cells(id) returns a specific instance.

property is_memoized: bool: Whether this cell opted into memoization via the %%memoize directive.

slice(stmts: bool = False, seed_only: bool = False, format_type: Type[FormatType] | None = None, include_cell_headers: bool = True) → Slice[source]

Return the backward slice needed to reconstruct this cell.

Parameters:

stmts – if True, slice at statement granularity (dropping unneeded statements within cells); otherwise include whole cells.
seed_only – restrict the slice to this cell alone (no upstream).
format_type – optional output format (e.g. str).
include_cell_headers – whether to emit # Cell N headers.

Instances also carry the attributes set at execution time: cell_id (frontend id), cell_ctr (execution counter), current_content / executed_content (source), position (notebook order), and tags.

Scope, Namespace, and Statement

A Scope is a symbol table mapping names to symbols. A Namespace is a Scope attached to a particular object, representing its attributes and items (for example df.columns or d["key"]); this is what enables dependency tracking below the variable level. A Statement is the per-AST-statement analog of a Cell and underpins statement-level slicing.

These classes are primarily internal; interact with them through the accessors in Model accessors (ipyflow.models) (scopes(), namespaces(), statements()) and the concepts overview in The dataflow model.

Watchpoints

class ipyflow.tracing.watchpoint.Watchpoints(iterable=(), /)[source]

The collection of Watchpoint objects registered on a symbol.

Obtain one with watchpoints(sym). It behaves like a read-only list; add watchpoints with add() rather than the usual list-mutation methods (which are disabled).

add(pred: Callable[[...], bool] | None = None, name: str | None = None)[source]

Register a watchpoint.

Parameters:

pred – a callable invoked as pred(obj, position=(cell_num, stmt_num), symbol_name=...) on each write to the watched symbol, returning truthy when the condition is met. None always passes.
name – an optional label for the watchpoint (used in repr).

class ipyflow.tracing.watchpoint.Watchpoint(name: str | None, pred: Callable[[...], bool] | None)[source]

A single named predicate evaluated whenever a watched symbol is written.

The predicate is called as pred(obj, position=(cell_num, stmt_num), symbol_name=...) and should return a truthy value when the watchpoint condition is met. A None predicate always passes.