nbbinder¶

NBBinder generates a navigable book-like structure to a collection of Jupyter notebooks.

nbbinder.add_badges(path_to_notes: str = None, badges: list = None) → None¶

Adds badges to each notebook in the collection.

Adds a badge cell with one or more badges to each notebook in the collection of indexed notebooks in the folder path_to_notes. The information for creating each badge is in the list badges.

Parameters:

path_to_notes (str) – The path to the directory that contains the notebooks, either absolute or relative to the script that calls nbbinder.bind().
badges (list of dict) –
A list of dictionaries with the necessary information to add the badges.

Each item in the list is a dictionary which should have the keys title (str), url (str), an optional extension (str), and either src or the three keys label (str), message (str), and color (str).

The key url is used for building link address, with the href argument being composed of the given url appended by the nam of the corresponding notebook.

The keys label, message, and color are used to build the badge image via the shields.io constructor, which will then become the argument src of the badge image. Alternatively, one can provide a direct src link to the badge image. The key title complements the information of the image.

The key extension is used in case there is a need to replace the .ipynb extension of each notebook to the appropriate extension, e.g .md, .slides.html, .pdf, .py, .tex, and so on. If extension is omitted, no replacement occurs.

nbbinder.add_contents(path_to_notes: str = None, toc_nb_name: str = None, toc_title: str = '', show_index_in_toc: bool = True) → None¶

Adds the table of contents to a selected notebook.

It adds the table of contents, generated from the collection of notebooks in the directory path_to_notes, to the notebook toc_nb_name, with toc_title as the title of the Table of Contents. The inclusion, or not, of the Chapter and Section numbers in the table of contents is indicaded by the argument show_index_in_toc.

Parameters:

path_to_notes (str) – The path to the directory that contains the notebooks, either absolute or relative to the script that calls nbbinder.bind().
toc_nb_name (str) – filename of the notebook in which the table of contents is to be inserted
toc_title (str) – Text to be displayed as the title for the table of contents cell, e.g. ‘Contents’, ‘Table of Contents’, or in other languages, ‘Conteúdo’, ‘Table des Matières’, and so on.
show_index_in_toc (bool) – Whether to display the navigator with the chapter and section number of each notebook or just their title.

nbbinder.add_headers(path_to_notes: str = None, header: str = None) → None¶

Adds header to each notebook in the collection.

It adds the provided header`as the first cell of each notebook in the collection of indexed notebooks in the folder `path_to_notes.

Parameters:	path_to_notes (str) – The path to the directory that contains the notebooks, either absolute or relative to the script that calls nbbinder.bind(). header (str) – The string with the text to be shown in the header cell.

nbbinder.add_navigators(path_to_notes: str = None, core_navigators: list = None, show_nb_title_in_nav: bool = True, show_index_in_nav: bool = True) → None¶

Adds navigators to each notebook in the collection.

Adds top and bottom navigators to each notebook in the collection of indexed notebooks in the folder path_to_notes.

Parameters:

path_to_notes (str) – The path to the directory that contains the notebooks, either absolute or relative to the script that calls nbbinder.bind().
core_navigators (list of str) – A lists of strings with the filenames of each notebook to be included in the navigators, in between the links to the “previous” and the “next” notebooks.
show_nb_title_in_nav (bool) – Whether to diplay the title of the notebook in the previous and next links or just display the words ‘Previous’ and ‘Next’.
show_index_in_nav (bool) – Whether to display the navigator with the chapter and section number of each notebook or just their title.

nbbinder.bind(aux: str = None, path_to_notes: str = None, reindexing: dict = None, contents: dict = None, header: str = '', navigators: dict = None, badges: list = None, exports: list = None, config_filename: str = None) → None¶

Binds the collection of notebooks.

It binds the collection of notebooks from either a configuration file config_filename or from the given arguments.

Parameters:

aux (str) – It allows for the first argument to be a non keyword argument which can be either the config_filename (if it ends in .yaml or .yml) or the path_to_notes (otherwise). These can also be given with the corresponding keyword arguments mentioned below.
path_to_notes (str) – The path to the directory that contains the notebooks, either absolute or relative to the script that calls nbbinder.bind().
reindexing (dict) – A dict with the keys insert and tighten for the function reindex().
contents (dict) – A dict with the keys toc_nb_name, toc_title, and show_index_in_toc for the function add_contents().
header (str) – The string with the text to be shown in the header cell.
navigators (dict) – A dict with the keys core_navigators, show_nb_title_in_nav, and show_index_in_nav for the function add_navigators()
badges (list) – A list of dictionaries with keys to composing each badge in the cell. See the function add_badge() for details.
exports (list) – A list of dictionaries with each dictionary containing the keys export_path, exporter_name, and exporter_args used by the function export_notebooks().
config_filename (str) – The filename of the configuration file.

nbbinder.cleanup_marker_cells(path_to_notes: str = None, marker: str = None, mode: str = 'remove') → None¶

Removes or clears the contents of any cell with the given marker.

Depending on the value of the argument mode, it removes all the cells with the given marker from all the indexed notebooks in path_to_notes, if mode == ‘remove’, or clears the contents of these cells (leaving the marker in the cell), if mode == ‘clear’.

Parameters:	path_to_notes (str) – The path to the directory that contains the notebooks, either absolute or relative to the script that calls nbbinder.bind(). marker (str) – The marker to be searched for. mode (str) – A string which should be either ‘remove’ or ‘clear’.

nbbinder.export_notebooks(path_to_notes: str = None, export_path: str = None, exporter_name: str = None, exporter_args: dict = None) → None¶

Export notebooks via nbconvert.

It reads all the indexed notebooks in path_to_notes and export them to the directory export_path using the exporter defined by exporter_name, with the arguments in exporter_args.

The name of the exporter (exporter_name) must be one of the default exporters listed in nbconvert.exporters.get_export_names().

Parameters:

path_to_notes (str) – The path to the directory that contains the notebooks, either absolute or relative to the script that calls nbbinder.bind().
export_path (str) – The path to the directory where the exported, or converted, files should be saved in.
exporter_name (str) – The name of the exporter to be used in nbconvert via nbconvert.exporters.get_exporter(exporter_name). Possible choices are ‘markdown’, ‘pdf’, ‘slides’, ‘latex’, etc.
exporter_args (dict) – Arguments, if any, to be passed on to the exporter via nbconvert.exporters.get_exporter(exporter_name)(**exporter_args).

nbbinder.get_badge_entries(path_to_notes: str = None, badges: list = None) → Iterable[tuple]¶

Iterable with the bagdes info for each notebook.

It reads the indexed notebooks in the folder path_to_notes and generates an iterable with the information needed to build the badges for each notebook.

Parameters:	path_to_notes (str) – The path to the directory that contains the notebooks, either absolute or relative to the script that calls nbbinder.bind(). badges (list of dict) – A list of dictionaries with the necessary information to add badges. See the docstring of add_badges() for the explanation of required and optional key-value pairs in each dictionary.
Yields:	str – Path to current notebook in the iterator. list – The list of badge links for the current notebook in the iterator.

nbbinder.get_contents(path_to_notes: str = None, toc_title: str = '', show_index_in_toc: bool = True) → str¶

Returns the ‘Table of Contents’.

Returns a string with the ‘Table of Contents’ constructed from the collection of notebooks in the folder indicated by the argument path_to_notes.

Parameters:	path_to_notes (str) – The path to the directory that contains the notebooks, either absolute or relative to the script that calls nbbinder.bind(). toc_title (str) – Text to be displayed as the title for the table of contents cell, e.g. ‘Contents’, ‘Table of Contents’, or in other languages, ‘Conteúdo’, ‘Table des Matières’, and so on. show_index_in_toc (bool) – Whether to display the table of contents with the chapter and section number of each notebook or just their title.
Returns:	The table of contents.
Return type:	str

nbbinder.get_navigator_entries(path_to_notes: str = None, core_navigators: list = None, show_nb_title_in_nav: bool = True, show_index_in_nav: bool = True) → Iterable[str]¶

Iterable with the navigator info for each notebook.

It reads the indexed notebooks in the folder path_to_notes and generates an iterable with the information needed to build the navigators for each notebook.

Parameters:

path_to_notes (str) – The path to the directory that contains the notebooks, either absolute or relative to the script that calls nbbinder.bind().
core_navigators (list of str) – A lists of strings with the filenames of each notebook to be included in the navigators, in between the links to the “previous” and the “next” notebooks.
show_nb_title_in_nav (bool) – Whether to diplay the title of the notebook in the previous and next links or just display the words ‘Previous’ and ‘Next’.
show_index_in_nav (bool) – Whether to display the navigator with the chapter and section numbers of each notebook or just their title.

Yields:

str – Path to current notebook in the iterator.
str – Contents of the navigation bar for the current notebook in the iterator.

nbbinder.get_nb_entry(path_to_notes: str = None, nb_name: str = None, show_index: bool = True) → str¶

Returns the entry of a notebook.

This entry is to be used for the link to the notebook from the table of contents and from the navigators. Depending on the value of the argument show_index, the entry can be either the full entry provided by the function get_nb_full_entry() or simply the title of the notebook, provided by the function get_nb_title().

Parameters:	path_to_notes (str) – The path to the directory that contains the notebooks, either absolute or relative to the script that calls nbbinder.bind(). nb_name (str) – The name of the jupyter notebook file. show_index (boolean) – Indicates whether to include the chapter and section numbers of the notebook in the table of contents (if True) or just the title (if False).
Returns:	entry – A string with the entry name.
Return type:	str

nbbinder.get_nb_full_entry(path_to_notes: str = None, nb_name: str = None) → list¶

Returns the full entry of a notebook.

This entry is to be used for the link to the notebook from the table of contents and from the navigators.

Parameters:

path_to_notes (str) – The path to the directory that contains the notebooks, either absolute or relative to the script that calls nbbinder.bind().
nb_name (str) – The name of the jupyter notebook file.

Returns:

md_pre_entry (str) – The type of markdown header or identation for the entry in Table of Contents
idx_entry (str) – The index entry, with the Chapter and Section numbers or letters.
title (str) – The title of the notebook, as obtained from get_nb_title().

nbbinder.get_nb_title(path_to_notes: str = None, nb_name: str = None) → str¶

Returns the title of a juyter notebook.

It looks for the first cell, in the notebook, that starts with a single markdown symbol ‘#’ and returns the contents of the first line of this cell, striped out of ‘# ‘ and of any remaining lines.

Parameters:	path_to_notes (str) – The path to the directory that contains the notebooks, either absolute or relative to the script that calls nbbinder.bind(). nb_name (str) – The name of the jupyter notebook file.
Returns:	The desired title of the notebook or None if not found.
Return type:	str

nbbinder.increase_index(idx: str) → str¶

Increases an index by one unit.

If the index is numeric, in the range ‘00’ to ‘98’, it adds one to the index and returns an index in the range ‘01’ to ‘99’. If the index is already ‘99’, there is an Exception error.

If the index is alphanumeric, with the first character being a letter and the second character being a digit in the range ‘0’ to ‘8’, the digit is increased by one, and the function returns an index with the same first letter and with the digit in the range ‘1’ to ‘9’. If the digit is already ‘9’, there is an Exception error.

If the index is purely alphabetical, then the ordinal ascii number of the letter is increased by 1, with the function returning an index with the same first character and with the second character in the range ‘B’ to ‘Z’. If the second character is already ‘Z’, there is an Exception error.

It also raises an exception if the given argument is not an index.

Parameters:	idx (str) – The index to be increased by one unit.
Returns:	The index increased by one unit.
Return type:	str
Raises:	Exception if string is not an index. Exception if index is increasead beyond the allowed range.

nbbinder.indexed_notebooks(path_to_notes: str = None) → list¶

Returns a sorted list with the filenames of the “indexed notebooks”.

The notebooks are expected to be in the folder indicated by the argument path_to_notes. The “indexed notebooks” are those that match the regular expression REG. Filenames that do not match this regular expression are ignored.

Parameters:	path_to_notes (str) – The path to the directory that contains the notebooks, either absolute or relative to the script that calls nbbinder.bind().
Returns:	A list with the filenames of the notebooks that match the regular expression, ordered by the lexicographycal order.
Return type:	list of str

nbbinder.insert_notebooks(path_to_notes: str = None) → None¶

Includes a notebook in the colllection.

Checks whether there is any notebook that matches the regular expression indicating it is to be incuded in the collection of indexed notebooks and, if so, renames the affected notebooks in the appropriate order.

Parameters:	path_to_notes (str) – The path to the directory that contains the notebooks, either absolute or relative to the script that calls nbbinder.bind().

nbbinder.prev_this_next(collection: list = None) → None¶

Iterable with previous, current, and next notebooks in collection.

It reads a list of indexed notebooks and gives an iterable with the previous, current, and next notebooks for each notebook in the list.

Parameters:	collection (list of str) – The collection of indexed notebooks.
Yields:	str – A string with the filename of the previous notebook in the iteration. str – A string with the filename of the current notebook in the iteration. str – A string with the filename of the next notebook in the iteration.

nbbinder.reindex(path_to_notes: str = None, insert: bool = True, tighten: bool = False) → None¶

Reindex the collection of notebooks.

Reindex the notebooks by inserting (via insert_notebooks()) and/or tightening (calling tighten_notebooks()) the collection of notebooks, depending on whether the corresponding arguments are True or False.

Parameters:	path_to_notes (str) – The path to the directory that contains the notebooks, either absolute or relative to the script that calls nbbinder.bind(). insert (bool) – Whether to insert notebooks in the collection or not. tighten (bool) – Whether to tighten the indices of notebooks or not.

nbbinder.tighten_notebooks(path_to_notes: str = None) → None¶

Tighten the indices of the notebooks in the colllection.

Checks whether there are gaps in the indices of the notebooks and, if so, renames the affected notebooks in the appropriate order.

Parameters:	path_to_notes (str) – The path to the directory that contains the notebooks, either absolute or relative to the script that calls nbbinder.bind().

nbbinder.yield_contents(path_to_notes: str = None, show_index_in_toc: bool = True) → Iterable[str]¶

Iterable with entries for each of the indexed notebooks.

It takes all the indexed notebooks and it creates a generator function to iterate from one notebook to the next, returning, each time, the navigator entry associated with that notebook.

Parameters:	path_to_notes (str) – The path to the directory that contains the notebooks, either absolute or relative to the script that calls nbbinder.bind(). show_index_in_toc (bool) – Whether to display the navigator with the chapter and section number of each notebook or just their title.
Yields:	Iterable[str] – Next navigator entry in the iterator