Metadata-Version: 2.1
Name: nanb
Version: 0.0.4
Summary: Not A NoteBook
Author-email: Espen Notodden <espen@enotodden.com>
Project-URL: Homepage, https://github.com/enotodden/nanb
Project-URL: Bug Tracker, https://github.com/enotodden/nanb/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp ==3.8.5
Requires-Dist: aiosignal ==1.3.1
Requires-Dist: anyio ==4.0.0
Requires-Dist: async-timeout ==4.0.3
Requires-Dist: attrs ==23.1.0
Requires-Dist: charset-normalizer ==3.3.0
Requires-Dist: click ==8.1.7
Requires-Dist: frozenlist ==1.4.0
Requires-Dist: idna ==3.4
Requires-Dist: importlib-metadata ==6.8.0
Requires-Dist: linkify-it-py ==2.0.2
Requires-Dist: markdown-it-py ==3.0.0
Requires-Dist: mdit-py-plugins ==0.4.0
Requires-Dist: mdurl ==0.1.2
Requires-Dist: msgpack ==1.0.7
Requires-Dist: multidict ==6.0.4
Requires-Dist: Pygments ==2.16.1
Requires-Dist: rich ==13.5.3
Requires-Dist: sniffio ==1.3.0
Requires-Dist: textual ==0.38.1
Requires-Dist: textual-dev ==1.2.1
Requires-Dist: toml ==0.10.2
Requires-Dist: tree-sitter ==0.20.2
Requires-Dist: tree-sitter-languages ==1.7.0
Requires-Dist: typing-extensions ==4.8.0
Requires-Dist: uc-micro-py ==1.0.2
Requires-Dist: watchfiles ==0.20.0
Requires-Dist: yarl ==1.9.2
Requires-Dist: zipp ==3.17.0

nanb - Not A NoteBook
=====================

Jupyter-style execution with plain Python files, in the terminal.

Example:

```python

# My Notebook
# ===========
#
# Welcome to my **not-a-notebook**!
#
# Here is a description, and some bullet points:
# - foo
# - bar
# - baz
#
# Here is a code block:
# ```python
# print("hello world")
# ```
#
# Here is a table:
# | foo | bar |
# |-----|-----|
# | 1   | 2   |
# | 3   | 4   |
#


# --- Do some imports
import os
import json


# --- Set a var
hello_abc = "Hello ABC!"

# --- Print it
print(hello_abc)

# ---
# This cell has no name, which is also fine
print("Hello world")
```

## Installation

```shell
$ pip install nanb
```


## Running a file

```shell
$ nanb run ./myfile.py
```

## Why?

Jupyter notbooks are great, but they are not regular Python files, and can be hard to work with in your editor of choice.

This project is an attempt at providing a stateful REPL-like execution environment for vanilla Python,
in the terminal, with regular source files that you edit using the editor/IDE of your choice.

## 101

Like in jupyter, a file used in nanb is divided into cells that can be executed independently.

Code cells are marked using `# ---`
```python
# ---
print('Hello world')
```

Markdown cells are just regular comments using `# %%%` to indicate their beginning:
```python
# %%%
# ## This is an H2 
# - These
# - Are 
# - List 
# - Items
```

Code cells can also have labels:

```python
# --- Do stuff
do_stuff()
```

## Configuring nanb

nanb can be configured by adding a toml configuration file in `$HOME/.nanb/nanb.toml`.

### Default config:

```
cell_name_max = 30

[server]
log_file = "/tmp/nanb_server.log"
prefix = "/tmp/nanb_socket_"

[code]
theme = "github-dark"
background = "#1a1a1a"

[output]
theme = "vscode_dark"
line_numbers = false

[keybindings]
quit = "q"
restart_kernel = "ctrl+r"
copy = "ctrl+y"

[tr]
action_quit = "Quit ❌"
action_restart_kernel = "Restart Kernel 🔄"
action_copy = "Copy 📋"
state_running = "RUNNING"
state_pending = "PENDING"
```


### Config options:

- `server`: Config options for the server/kernel that actually runs your code.
    - `log_file`: Specifies where to write the server log to.
    - `prefix`: Sets where to put the socket file the main application uses to communicate with the server.
- `code`: Settings for displaying code.
    - `theme`: Pygments theme used to render code. See https://pygments.org/demo/ for available options.
    - `background`: The background color used for code cells.
- `output`: Settings for the output pane.
    - `theme`: Available options: `'dracula', 'github_light', 'monokai', 'vscode_dark'`.
    - `line_numbers`: Wether to display line numbers in the output.
- `keybindings`:
    - `quit`: Key combination used to quit the application.
    - `restart_kernel`: Key combination used to kill the code execution server and start a new one.
    - `copy`: Key combination used to copy selected text from the output.
- `tr`: Strings/translations used to render state info and help text.
- `cell_name_max`: Sets the max number of characters cell names/labels are displayed with.


### Custom CSS:
Since nanb uses textual, it is also possible to override the looks using custom CSS.

If the file `~/.nanb/nanb.css` exists, it's content will be appended to the default css on startup.

See https://textual.textualize.io/guide/CSS/ for more information.



## Q&A

### Does nanb support editing code?

No. The whole idea is providing an environment for execution, letting you use your own editor to write code.

### Does nanb support jupyter style magic like `#!` for shell commands?

No, as that would make your files behave differently in nanb vs running your files using the regular python commmand.
