notebook Module (stx.notebook)

SciTeX Notebook — Jupyter notebook verification and compilation.

Provides tools to verify, compile, convert, and check Jupyter notebooks for reproducibility using the Clew verification system.

Key Concept: Notebooks can be executed in any cell order. SciTeX records actual execution order via timestamps, then reconstructs the dependency DAG afterward (“do what you want, organize later”).

Examples

>>> from scitex_notebook import verify_notebook, compile_notebook
>>> results = verify_notebook("experiment.ipynb")
>>> compiled = compile_notebook("experiment.ipynb")
>>> print(compiled.to_mermaid())  # DAG visualization
>>> print(compiled.to_script())   # DAG-ordered .py

scitex.notebook.parse_notebook(path)

Parse a .ipynb file and extract code cells.

Parameters:

path (str or Path) – Path to the .ipynb file.

Returns:

Code cells with keys: index, source, cell_id, cell_type.

Return type:

list of dict

scitex.notebook.get_code_cells(path)

Parse notebook and return only code cells.

Parameters:

path (str or Path) – Path to the .ipynb file.

Returns:

Code cells only.

Return type:

list of dict

scitex.notebook.get_notebook_name(path)

Return the notebook stem name without extension.

Return type:

str

scitex.notebook.verify_notebook(path)

Verify all clew sessions associated with a notebook.

Finds all runs in the clew DB whose metadata contains this notebook’s path, then runs L1 (cache) verification on each.

Parameters:

path (str or Path) – Path to the .ipynb file.

Returns:

Verification results per session.

Return type:

list of dict

scitex.notebook.check_notebook(path)

Find cells with scitex.io calls not wrapped in @scitex.session.

Parameters:

path (str or Path) – Path to the .ipynb file.

Returns:

Cells with untracked IO: {index, has_load, has_save, has_session}.

Return type:

list of dict

scitex.notebook.compile_notebook(path)

Compile a notebook’s execution history into a DAG.

Queries the clew DB for all sessions associated with this notebook, sorts by timestamp, and builds a dependency DAG based on shared input/output files.

Parameters:

path (str or Path) – Path to the .ipynb file.

Returns:

Compiled execution history with DAG and execution order.

Return type:

CompiledNotebook

class scitex.notebook.CompiledNotebook(notebook_path, execution_order=<factory>, dag=<factory>, runs=<factory>)

Bases: object

Result of compiling a notebook’s execution history.

notebook_path

Path to the source notebook.

Type:

str

execution_order

Session IDs in actual execution order (by timestamp).

Type:

list of str

dag

Adjacency list: {session_id: [dependent_session_ids]}.

Type:

dict

runs

Run records sorted by execution time.

Type:

list of dict

notebook_path: str

execution_order: List[str]

dag: Dict[str, List[str]]

runs: List[Dict]

to_script()

Generate a .py script with sessions in DAG order.

Return type:

str

to_mermaid()

Generate a Mermaid DAG diagram of execution flow.

Return type:

str

scitex.notebook.convert_notebook(path, output=None, order='cell', mode='per_cell')

Convert a .ipynb notebook to a .py script with @stx.session.

Parameters:

• path (str or Path) – Path to the .ipynb file.

• output (str or Path, optional) – Output .py file path. If None, returns string only.

• order (str) – Cell ordering: “cell” (notebook order) or “dag” (execution order from clew DB timestamps).

• mode (str) –

  Conversion mode: - “per_cell”: Each code cell becomes a separate @stx.session function (default). - “unified”: All cells merged into a single @stx.session main() function.

  Markdown cells become comments, imports are hoisted, and common notebook patterns (plt.show, pd.read_csv, etc.) are converted to SciTeX equivalents (stx.io.save/load).

Returns:

The generated Python script content.

Return type:

str