# The `nbless` python package¶

Using `nbless` you can create and execute Jupyter notebooks in

- your terminal or
- your favorite Python environment (e.g. PyCharm or Visual Studio Code).

The `nbless` python package consists of 3 functions:

- `nbuild`, which creates a notebook from python scripts and plain text files, e.g. markdown (`.md`) and text (`.txt`) files.
- `nbexec`, which runs a notebook from top to bottom and saves an executed version, leaving the source notebook untouched.
- `nbless`, which calls `nbuild` and `nbexec` to create and execute a notebook.

These functions rely on the `nbconvert` and `nbformat` modules that are included with `jupyter`.

## Installation¶

    pip install nbless

or clone this repo and use locally, e.g. `python nbless.py README.md plot.py notes.txt`.

## Basic usage: terminal¶

### Creating and executing a notebook with `nbless` in the terminal¶

Run `nbless` in your terminal, providing all of the names of the source files as arguments, e.g.

    python nbless.py README.md plot.py notes.txt

First, the contents of Python code files (`.py`) are stored as Jupyter notebook code cells, while the contents of all other files are stored in markdown cells.

Then, the newly created notebook is copied, run from top to bottom and saved. The default name of the first notebook is `raw.ipynb` while the executed notebook is called `out.ipynb` by default output. The default filepath where the notebooks are saved is the current directory (`'./'`).

You can provide more descriptive names for the notebooks and set a different path:

    nbless README.md plot.py notes.txt --raw unexecuted --out executed.ipynb --path notebooks/
    # Or
    nbless README.md plot.py notes.txt -r not_executed.ipynb -o executed.ipynb -p notebooks/

### Creating a notebook with `nbuild` in the terminal¶

If you do not want an executed version of the notebook, run `nbuild.py` instead of `nbless.py`.

    nbuild README.md plot.py notes.txt

The default output filename for `nbuild` is `raw.ipynb`. The default output filepath is the current directory (`'./'`).

You can provide a more descriptive filename (`-o`) and set a different path (`-p`):

    nbuild README.md plot.py -o not_executed.ipynb -p notebooks/
    # Or
    nbuild README.md plot.py --out not_executed.ipynb --path notebooks/

If you only want to execute a notebook, run `nbexec.py`.

    nbexec raw.ipynb

The default output filename for `nbexec.py` is `out.ipynb`. The default output filepath is the current directory (`'.'`).

You can provide more descriptive names for the output name (`-o`) and path (`-p`):

    nbexec raw.ipynb -o executed.ipynb -p notebooks/
    # Or
    nbexec raw.ipynb --out executed.ipynb --path notebooks/

## Basic usage: python environment¶

    # You can also import each function individually
    from nbless import nbuild
    from nbless import nbexec
    from nbless import nbless

    nbuild(["README.md", "plot.py", "notes.txt"], output_path="notebooks/")
    nbexec("notebooks/raw.ipynb", output_path="notebooks/")

    # Or to run both nbuild and nbexec at once, use nbless
    nbless(["README.md", "plot.py", "notes.txt"], nbexec_path="notebooks/")

    # Another alternative is to import the package and use it as a namespace.
    import nbless
    nbless.nbuild(["README.md", "plot.py", "notes.txt"], output_path="notebooks/")
    nbless.nbexec("notebooks/raw.ipynb", output_path="notebooks/")
    nbless.nbless(["README.md", "plot.py", "notes.txt"], nbexec_path="notebooks/")

### Missing a dependency?¶

If you installed Anaconda, you should already have all of the dependencies (`python`, `nbformat`, and `nbconvert`).

If not, or if you have Miniconda installed, run

    conda install -yc conda-forge jupyter

If you have any other Python installation, run

    pip install jupyter

## Too many file names to type out?¶

You can use the `ls` command to assign all of the relevant names in the current directory to a variable and pass this variable as an argument to `nbconvert.py`.

To preserve the order and differentiate files that should be incorporated into the notebook, I recommend left padding your file names with zeros (e.g. 01_intro.md, 02_figure1.py).

Consider the example below:

    touch {01..09}.py
    name_list=`ls 0*.py`
    python nbuild.py `echo $name_list`

In a python environment, I recommend `os.listdir` to obtain a list of all files:

    from os import listdir
    from os.path import isfile, join
    onlyfiles = [f for f in listdir(mypath) if isfile(join(mypath, f))]

In [1]:

    import numpy as np
    import matplotlib.pyplot as plt
    # %% scatter
    N = 50
    x = np.random.rand(N)
    y = np.random.rand(N)
    colors = np.random.rand(N)
    area = np.pi * (15 * np.random.rand(N))**2  # 0 to 15 point radii
    plt.scatter(x, y, s=area, c=colors, alpha=0.5)
    plt.show()

cryzen codecademy PyDataDC