/satyrn

A Notebook alternative that supports branching code and local collaboration.

Primary LanguageJavaScriptMIT LicenseMIT

Codacy Badge made-with-python PyPI

GitHub license Open Source Love png1 Documentation Status

Maintenance PRs Welcome

GitHub issues GitHub issues-closed

Say Thanks!

Satyrn

Satyrn Satyrn is an alternative to Jupyter notebooks that supports branching code cells and network collaboration.

Contributing

What that means

Code in Satyrn is executed in "Cells", which are small blocks of code that should perform a few small functions, but share variables, functions, imports, etc. Splitting code into these Cells allows users to run lots of "setup" cells and then play around with a cell that depends on the setup to function. This prevents users from having to run lengthy code over and over again. A similar application is Jupyter's Notebook.

Most code is executed as a list of instructions,

print(1)
print(2)
print(3)

However, Satyrn's code execution is different. Code inside of cells still executes normally, but cells are not necessarily linked linearly. One cell, which we'll call "root", can have two "Children", "childA" and "childB". Because root is the parent, it will run first. But because childA and childB are siblings on the same level in the hierarchy, they will be run simultaneously. This is particularly useful in situations like data analysis, where lots of data must be preprocessed before they can be used. If you have multiple sets of data to preprocess, why not preprocess them simultaneously instead of waiting for them to finish 1-by-1?

Satyrn is also a great tool for collaboration. While using the UI, the graph state is shared over your local network via a CherryPy WSGI server. This allows machines on your local network to edit the same code you're working on by navigating to your IP address in their browser, no Python/Satyrn installations required. If you desire more security, the --hidden command line argument will hide your Satyrn instance from the network. Use caution when working with Satyrn on public networks.

Setup

Latest Release

python -m pip install satyrn-python

Build from source

git clone https://github.com/CharlesAverill/satyrn
python setup.py install

Startup

  • Run satyrn to open the UI (in development, unstable)
  • Run satyrn cli to open the CLI

Command Line Arguments

  • cli - Starts the CLI instead of the UI

  • ui - Starts the UI (Default behavior)

  • -h --hidden - Starts the UI on 127.0.0.1 instead of 0.0.0.0, preventing machines on your local network to access your Satyrn instance

  • -p n --port=n - Forces UI to run on port n

  • -l n --lang=n - Sets UI Language. Currently supported:

    • english (default)
    • latin
    • chinese-simplified
    • chinese-traditional

  • -q --quiet - Quiet startup + shutdown

CLI Commands

  • quit - Quits out of interpreter

  • cell [cell_name] [content_type](python/markdown) [add_content](y/n)

    • Creates cell with given parameters
    • All cells require unique names
    • The first cell created will always be treated as the "root" cell, and will always be executed first in a complete execution call.
    • Set content_type to "python" for python cells
    • If add_content is "y", a text box will pop up. Input your python code here.

  • remove [cell_name]

    • Deletes cell and its links from graph.

  • edit [cell_name]

    • Reopens text input window so that users can edit cells

  • link [first_cell_name] [second_cell_name]

    • Links the two cells whose names are provided. You can technically still make branching graphs this way, but they will not work at all.

  • sever [first_cell_name] [second_cell_name]

    • Severs the link between the two cells whose names are provided

  • merge [first_cell_name] [second_cell_name]

    • Merges the two cells if they are adjacent.

  • swap [first_cell_name] [second_cell_name]

    • Swaps the contents and names of the named cells. e.g.
      • a -> b -> c
      • swap a b
      • b -> a -> c

  • execute [cell_name_1] [cell_name_2] ...

    • If no cell names are defined, the entire graph will execute sequentially
    • If cell names are defined, they will execute in the order they are named

  • display [cell_name]

    • If cell_name is defined, that cell's contents will be printed to the console
    • Otherwise, the entire graph will be displayed in matplotlib.

  • list

    • Prints a list of all cell names and edge pairs in graph

  • reset_runtime

    • Deletes all local variables created by cells.

  • reset_graph

    • Deletes all cells and variables. Equivalent of restarting Satyrn session.

  • save [filename]

    • Saves graph, supported formats are .satx, .py, and .ipynb.

  • [filename]

    • This will run a .satx file. It's just a reformatted version of the normal Satyrn input. This test file shows the basic syntax rules.

CLI Example

Here, code written in [ ] brackets was typed into the text box popup.

♄: cell root python y
[x = 10]
♄: cell mid python y
[x *= 22]
♄: cell bottom python y
[print(x)]
♄: link root mid
♄: link mid bottom
♄: execute
220
♄: quit

Contributors

Join the dev Discord!