SoS Notebook

SoS Notebook is a Jupyter kernel that allows the use of multiple kernels in one Jupyter notebook. Using language modules that understand datatypes of underlying languages (modules sos-bash, sos-r, sos-matlab, etc), SoS Notebook allows data exchange among live kernels of supported languages.

SoS Notebook also extends the Jupyter frontend and adds a console panel for the execution of scratch commands and display of intermediate results and progress information, and a number of shortcuts and magics to facilitate interactive data analysis. All these features have been ported to JupyterLab, either in the sos extension jupyterlab-sos or contributed to JupyterLab as core features.

SoS Notebook also serves as the IDE for the SoS Workflow that allows the development and execution of workflows from Jupyter notebooks. This not only allows easy translation of scripts developed for interactive data analysis to workflows running in containers and remote systems, but also allows the creation of scientific workflows in a format with narratives, sample input and output.

SoS Notebook is part of the SoS suite of tools. Please refer to the SoS Homepage for details about SoS, and this page for documentations and examples on SoS Notebook. If a language that you are using is not yet supported by SoS, please submit a ticket, or consider adding a language module by yourself following the guideline here.

Installation

For Users

Install from PyPI:

pip install sos-notebook

Install from conda-forge:

conda install -c conda-forge sos-notebook

For Developers

SoS Notebook uses modern Python packaging and development tools. See CONTRIBUTING.md for detailed development setup instructions.

Quick development setup:

# Prerequisites: Python 3.8+ and uv (https://github.com/astral-sh/uv)
git clone https://github.com/vatlab/sos-notebook.git
cd sos-notebook
invoke dev-setup    # Sets up virtual environment and dependencies
source .venv/bin/activate

Development

This project uses modern Python development tools:

• uv for fast dependency management and virtual environments
• ruff for linting and code formatting
• invoke for task automation
• pytest for testing
• Modern build system with pyproject.toml (PEP 517/518)

Quick Commands

# Set up development environment
invoke dev-setup

# Run quality checks
invoke check          # Run all checks (format, lint, test)
invoke format         # Format code with ruff
invoke lint --fix     # Lint and auto-fix issues
invoke test           # Run tests

# Build and release
invoke build          # Build distributions
invoke release-check  # Comprehensive pre-release checks

For detailed contribution guidelines, see CONTRIBUTING.md.

Testing

The project includes comprehensive tests that run in Docker containers to simulate real Jupyter environments:

invoke test           # Quick tests (skip Docker/selenium)
invoke test-docker    # Full test suite in Docker (as in CI)

License

This project is licensed under the 3-clause BSD License.