export.base

convert_nb

convert_nb(nb_path: str, dest_path: str, nb_format: str, dest_format: str)

Convert a notebook from one format to another.

Arguments: - nb_path: Path to the notebook to convert. - dest_path: Path to the destination file. - nb_format: Format of the notebook to convert. - dest_format: Format of the destination file.

---

root_path = Path('../../../test_proj/')

(root_path / 'pcts').mkdir(parents=True, exist_ok=True)
(root_path / 'lgts').mkdir(parents=True, exist_ok=True)

convert_nb(
    nb_path=root_path / 'nbs' / 'notebook1.ipynb',
    dest_path=root_path / 'pcts' / 'notebook1.pct.py',
)

convert_nb(
    nb_path=root_path / 'nbs' / 'notebook2.ipynb',
    dest_path=root_path / 'pcts' / 'notebook2.pct.py',
)

convert_nb(
    nb_path=root_path / 'pcts' / 'notebook1.pct.py',
    dest_path=root_path / 'lgts' / 'notebook1.lgt.py',
)

convert_nb(
    nb_path=root_path / 'pcts' / 'notebook2.pct.py',
    dest_path=root_path / 'lgts' / 'notebook2.lgt.py',
)

# Test to see if the conversion is reversible
with tempfile.TemporaryDirectory() as tmpdirname:
    tempdir = Path(tmpdirname)
    convert_nb(
        root_path / "pcts" / "notebook1.pct.py",
        tempdir / "nb.ipynb",
    )
    convert_nb(
        tempdir / "nb.ipynb",
        tempdir / "nb.pct.py",
    )
    assert Path(root_path / "pcts" / "notebook1.pct.py").read_text() == Path(tempdir / "nb.pct.py").read_text()

get_nb_module_export_name

get_nb_module_export_name(nb_path: str, lib_path: str) -> str

---

get_nb_module_export_name(root_path / 'nbs/submodule/notebook3.ipynb', root_path / 'my_module')

'submodule.notebook3'

get_nb_module_export_name(root_path / 'pcts/submodule/notebook3.pct.py', root_path / 'my_module')

'submodule.notebook3'

get_nb_module_export_path

get_nb_module_export_path(nb_path: str, lib_path: str) -> str

---

get_nb_module_export_path(root_path / 'nbs/submodule/notebook3.ipynb', root_path / 'my_module')

Path('/Users/lukastk/dev/2025-03-05_00__nblite/test_proj/my_module/submodule/notebook3.py')

get_nb_twin_paths

get_nb_twin_paths(nb_path: str, root_path: str)

For a given notebook in a code location, returns the paths to all its ‘twins’ (the corresponding notebooks in the other code locations).

The original given notebook path is also returned.

---

get_nb_twin_paths(root_path / 'nbs/folder/notebook4.ipynb', root_path)

('/Users/lukastk/dev/2025-03-05_00__nblite/test_proj/lgts/folder/notebook4.lgt.py',
 '/Users/lukastk/dev/2025-03-05_00__nblite/test_proj/my_module/notebook4.py',
 '/Users/lukastk/dev/2025-03-05_00__nblite/test_proj/nbs/folder/notebook4.ipynb',
 '/Users/lukastk/dev/2025-03-05_00__nblite/test_proj/pcts/folder/notebook4.pct.py')

clean_ipynb

clean_ipynb(
   nb_path: str,
   remove_outputs: bool,
   remove_cell_metadata: bool,
   remove_top_metadata: bool
)

Clean a notebook by removing all outputs and metadata.

Arguments: - nb_path: Path to the notebook to clean. - remove_outputs: Whether to remove the outputs from the notebook. - remove_metadata: Whether to remove the metadata from the notebook.

---

clean_ipynb(root_path / 'nbs/notebook1.ipynb', remove_outputs=True, remove_cell_metadata=True)

get_nb_source_and_output_hash

get_nb_source_and_output_hash(
   nb: Union[str,nbformat.notebooknode.NotebookNode],
   return_nb: bool
) -> Tuple[bool, str]

Check the source hash of a notebook.

---

nb_src_and_out_hash, has_changed = get_nb_source_and_output_hash(root_path / 'nbs' / 'notebook1.ipynb')
has_changed

True

nb_src_and_out_hash, has_changed, nb, nb_src_and_out = get_nb_source_and_output_hash(root_path / 'nbs' / 'notebook1.ipynb', return_nb=True)
has_changed

True

fill_ipynb

fill_ipynb(
   nb_path: str,
   cell_exec_timeout,
   remove_pre_existing_outputs: bool,
   remove_cell_metadata: bool,
   working_dir: Union[str,None],
   dry_run: bool
) -> nbformat.notebooknode.NotebookNode

Execute a notebook and fills it with the outputs.

Cells can be skipped by adding the following directives to the cell: - #|skip_evals: Skip current and subsequent cells, until #|skip_evals_stop is encountered. - #|skip_evals_stop: Stop skipping cells. - #|eval: false: Skip the cell.

Arguments: - nb_path: Path to the notebook to fill. - cell_exec_timeout: Timeout for cell execution. - remove_pre_existing_outputs: Whether to remove the pre-existing outputs from the notebook. - remove_metadata: Whether to remove the metadata from the notebook.

---

fill_ipynb(root_path / 'nbs' / 'notebook1.ipynb');

get_cell_with_directives

get_cell_with_directives(cell: dict)

Get the cell with the directives from a cell as metadata.

---

get_nb_directives

get_nb_directives(nb_path, nb_format, only_code_cells: bool)

Get the directives from a notebook.

---

directives = get_nb_directives(root_path / 'nbs' / 'func_notebook.ipynb')
for directive in directives:
    print(f"#|{directive['directive']} {directive['args']}")

#|default_exp test_func_nb
#|export_as_func true
#|hide 
#|top_export 
#|set_func_signature 
#|export 
#|func_return 

lookup_directive

lookup_directive(nb_directives, directive)

Lookup the latest ocurring directive from the output of get_nb_directives.

---

lookup_directive(directives, 'set_func_signature')

{'directive': 'set_func_signature',
 'args': '',
 'cell': {'cell_type': 'code',
  'execution_count': None,
  'metadata': {},
  'outputs': [],
  'source': '#|set_func_signature\n@a_decorator\ndef nb_func(): ...',
  'directives': [{'directive': 'set_func_signature',
    'args': '',
    'cell_line': 0}],
  'source_without_directives': '@a_decorator\ndef nb_func(): ...'}}

generate_md_file

generate_md_file(
   nb_path: Union[str,None],
   out_path: Union[str,None],
   nb_format: Union[str,None]
)

Generate a markdown file from a notebook.

Arguments: - root_path: The root path of the project. If not provided, the project root will be determined by searching for a nblite.toml file.

---

import tempfile

# Create a temporary file path
with tempfile.NamedTemporaryFile(delete=True, suffix='.md') as temp_file:
    generate_md_file(root_path / 'nbs' / 'notebook1.ipynb', temp_file.name)
    md_file_content = Path(temp_file.name).read_text()
    print("\n".join(md_file_content.splitlines()[:10]))

# Notebook 1

```python
#|default_exp notebook1
```

```python
#|export
def foo():
    print("Hello")

generate_readme

generate_readme(root_path: Union[str,None])

Generate a README.md file for the project from the index.ipynb file.

Arguments: - root_path: The root path of the project. If not provided, the project root will be determined by searching for a nblite.toml file.

---

generate_readme(root_path)

export_to_lib

export_to_lib(nb_path, lib_path, nb_format)

---

root_path = Path('../../../test_proj/')

export_to_lib(
    root_path / 'nbs' / 'notebook1.ipynb',
    root_path / 'my_module',
)

export_to_lib(
    root_path / 'nbs' / 'notebook2.ipynb',
    root_path / 'my_module',
)

export_to_lib(
    root_path / 'pcts' / 'notebook1.pct.py',
    root_path / 'my_module',
)

export_to_lib(
    root_path / 'pcts' / 'notebook2.pct.py',
    root_path / 'my_module',
)

clear_code_location

clear_code_location(cl_key: str, root_path: Union[str,None])

Clear the code location of a given key.

---

clear_code_location('pcts', root_path)

clear_downstream_code_locations

clear_downstream_code_locations(root_path: Union[str,None])

---

clear_downstream_code_locations(root_path)