cli

import nblite.cli as this_module

Helper functions

derive_cli_meta

derive_cli_meta(source_func: FunctionType) -> Callable

A decorator factory that transfers docstring and argument annotations from a source functio and turns

them into a typer annotations for the target function.

Arguments: - source_func: The function from which to derive the docstring and argument annotations.

---

Define CLIs

entrypoint

entrypoint(ctx: typer.Context, version: bool)

---

main

main()

---

nbl export

cli_export

cli_export(
   root_path: Annotated[Union[str,None], Option(help="Path to the root folder of the nblite project.")],
   config_path: Annotated[Union[str,None], Option(help="Path to the nblite.toml config file. Will be used instead of the config file in the root folder if provided.")],
   export_pipeline: Annotated[Union[str,None], Option(help=" The export pipeline to use. E.g. 'nbs->pts,pts->lib'.")],
   nb_paths: Annotated[Union[List[str],None], Option(help="If provided, only the notebooks specified in the paths will be exported.")]
)

Export notebooks in an nblite project, as specified in the nblite.toml config file.

If the root_path is not provided, nblite will search for a nblite.toml file in the current directory and all parent directories, and use the directory containing the nblite.toml file as the root folder.

---

nbl to-md

cli_to_md

cli_to_md(nb_path, out_path, nb_format)

---

nbl readme

cli_readme

cli_readme(root_path)

---

nbl convert

cli_convert

cli_convert(nb_path, dest_path, nb_format, dest_format)

---

nbl init

cli_init

cli_init(
   module_name: Annotated[Union[str,None], Option(help="The name of the module to create")],
   root_path: Annotated[Union[str,None], Option(help="The root path of the project")],
   use_defaults: Annotated[bool, Option(help="Use default values for module name and root path")]
)

Initialize a new nblite project.

---

nbl new

cli_new

cli_new(
   nb_path: Annotated[str, Argument(help="The notebook to create.")],
   mod_name: Annotated[Union[str,None], Option("-n", "--name", help="The name of the exported module. Defaults to the notebook path relative to the code location root.")],
   nb_title: Annotated[Union[str,None], Option("-t", "--title", help="The display title of the notebook. Defaults to the notebook path stem.")],
   root_path: Annotated[Union[str,None], Option("-r", "--root", help="The root path of the project. If not provided, the project root will be determined by searching for a nblite.toml file.")]
)

Create a new notebook in a code location.

---

nbl clean

cli_clean

cli_clean(
   nb_paths: Annotated[Union[List[str], None], Argument(help="Specify the jupyter notebooks to clean. If omitted, all ipynb files in the project's code locations will be cleaned.")],
   remove_outputs: Annotated[bool, Option(help="Remove the outputs from the notebook.")],
   remove_cell_metadata: Annotated[bool, Option(help="Remove the metadata from the notebook.")],
   remove_top_metadata: Annotated[bool, Option(help="Remove the top-level metadata from the notebook.")],
   root_path: Annotated[Union[str,None], Option("-r", "--root", help="The root path of the project. If not provided, the project root will be determined by searching for a nblite.toml file.")],
   exclude_dunders: Annotated[bool, Option("--exclude-dunders", help="Exclude notebooks with that begin with a dunder (double underscore '__') in their filenames or in any of their parent folders. ")],
   exclude_periods: Annotated[bool, Option("--exclude-periods", help="Exclude notebooks with that begin with a period in their filenames or in their parent folders.")]
)

Clean notebooks in an nblite project by removing outputs and metadata.

If nb_path is not provided, all notebooks in the project will be cleaned.

---

nbl fill

cli_fill

cli_fill(
   nb_paths: Annotated[Union[List[str], None], Argument(help="Specify the jupyter notebooks to fill. If omitted, all ipynb files in the project's code locations will be filled.")],
   remove_prev_outputs: Annotated[bool, Option("-r", "--remove-prev-outputs", help="Remove the pre-existing outputs from the notebooks.")],
   remove_cell_metadata: Annotated[bool, Option("-m", "--remove-metadata", help="Remove the metadata from notebook cells.")],
   root_path: Annotated[Union[str,None], Option("-r", "--root", help="The root path of the project. If not provided, the project root will be determined by searching for a nblite.toml file.")],
   cell_exec_timeout: Annotated[Union[int,None], Option("-t", "--timeout", help="The timeout for the cell execution.")],
   include_dunders: Annotated[bool, Option("-i", "--include-dunders", help="Include notebooks with that begin with a dunder (double underscore '__') in their filenames or in any of their parent folders. ")],
   include_periods: Annotated[bool, Option("-p", "--include-periods", help="Include notebooks that begin with a period in their filenames or in their parent folders.")],
   dry_run: Annotated[bool, Option(help="Dry run the command.")],
   n_workers: Annotated[int, Option("-n", "--n-workers", help="The number of workers to use.")],
   allow_export_during: Annotated[bool, Option("--allow-export-during", help="Allow export during the command.")],
   fill_unchanged: Annotated[bool, Option("-f", "--fill-unchanged", help="Fill the notebook even if the source has not changed.")]
)

Clean notebooks in an nblite project by removing outputs and metadata.

If nb_path is not provided, all notebooks in the project will be cleaned.

---

nbl test

cli_test

cli_test(
   nb_paths: Annotated[Union[List[str], None], Argument(help="Specify the jupyter notebooks to fill. If omitted, all ipynb files in the project's code locations will be filled.")],
   root_path: Annotated[Union[str,None], Option("-r", "--root", help="The root path of the project. If not provided, the project root will be determined by searching for a nblite.toml file.")],
   cell_exec_timeout: Annotated[Union[int,None], Option("-t", "--timeout", help="The timeout for the cell execution.")],
   include_dunders: Annotated[bool, Option("-i", "--include-dunders", help="Include notebooks with that begin with a dunder (double underscore '__') in their filenames or in any of their parent folders. ")],
   include_periods: Annotated[bool, Option("-p", "--include-periods", help="Include notebooks that begin with a period in their filenames or in their parent folders.")]
)

Alias for nbl fill --dry-run. Used to test that all cells in the notebooks can be executed without errors.

---

nbl validate-staging

cli_validate_staging

cli_validate_staging(
   root_path: Annotated[Union[str,None], Option("-r", "--root", help="The root path of the project. If not provided, the project root will be determined by searching for a nblite.toml file.")]
)

Validate the staging of the project.

The staging is valid if all notebooks are clean and the twins of all notebooks that are staged have no unstaged changes.

The command will exit with code 1 if the staging is invalid.

---

nbl install-hooks

cli_install_hooks

cli_install_hooks(
   root_path: Annotated[Union[str,None], Option("-r", "--root", help="The root path of the project. If not provided, the project root will be determined by searching for a nblite.toml file.")]
)

Install the git hooks for the project.

---

nbl git-add

cli_git_add

cli_git_add(
   file_paths: Annotated[List[str], Argument(help="The file paths to add to the staging area.", autocompletion=_get_nbs)],
   extra_args: Annotated[List[str], Option("--", help="Extra arguments to pass to git add.")]
)

Like git add, but also runs nbl export, cleans any notebooks that are passed, and stages their twins.

---

nbl clear

cli_clear_downstream

cli_clear_downstream(
   code_location: Annotated[Optional[str], Argument(help="The code location to clear downstream from.")],
   all: Annotated[bool, Option(help="Clear all downstream notebooks.")]
)

Clear a code location or all code locations downstream from the top-level code location.

---

nbl prepare

cli_prepare

cli_prepare(
   root_path: Annotated[Union[str,None], Option("-r", "--root", help="The root path of the project. If not provided, the project root will be determined by searching for a nblite.toml file.")],
   cell_exec_timeout: Annotated[Union[int,None], Option("-t", "--timeout", help="The timeout for the cell execution.")],
   include_dunders: Annotated[bool, Option("-i", "--include-dunders", help="Include notebooks with that begin with a dunder (double underscore '__') in their filenames or in any of their parent folders. ")],
   include_periods: Annotated[bool, Option("-p", "--include-periods", help="Include notebooks that begin with a period in their filenames or in their parent folders.")],
   dry_run: Annotated[bool, Option(help="Dry run the command.")],
   n_workers: Annotated[int, Option("-n", "--n-workers", help="The number of workers to use.")],
   allow_export_during: Annotated[bool, Option("--allow-export-during", help="Allow export during the command.")],
   fill_unchanged: Annotated[bool, Option("-f", "--fill-unchanged", help="Fill the notebook even if the source has not changed.")]
)

Export, clean, and fill the notebooks in the project.

---

nbl render-docs

cli_render_docs

cli_render_docs(
   root_path: Annotated[Union[str,None], Option("-r", "--root", help="The root path of the project. If not provided, the project root will be determined by searching for a nblite.toml file.")],
   docs_cl: Annotated[Optional[str], Option("-d", "--docs-cl", help="The code location to render the documentation for. If not provided, the code location will be retrieved from the nblite.toml file.")],
   output_folder: Annotated[Optional[str], Option("-o", "--output-folder", help="The folder to output the documentation to. Default is '_docs'.")]
)

Render the documentation for the project using Quarto.

---

nbl preview-docs

cli_render_docs

cli_render_docs(
   root_path: Annotated[Union[str,None], Option("-r", "--root", help="The root path of the project. If not provided, the project root will be determined by searching for a nblite.toml file.")],
   docs_cl: Annotated[Optional[str], Option("-d", "--docs-cl", help="The code location to render the documentation for. If not provided, the code location will be retrieved from the nblite.toml file.")]
)

Preview the documentation for the project using Quarto.

---