sy-nb-sy

Synapse -> Jupyter notebook -> Synapse

An open-source Python utility for converting Microsoft Azure Synapse Notebook JSON files to and from Jupyter Notebook .ipynb files. Conversion parses notebook structures and maps cells and metadata; it does not execute notebook code.

Features

• Convert individual Synapse JSON and Jupyter notebook files in either direction.
• Bulk and optional recursive Synapse-to-Jupyter conversion.
• Preserve cell order, code, Markdown, outputs, execution counts, and supported metadata.
• Preserve Synapse-only notebook and cell properties in a namespaced Jupyter metadata field for round trips.
• Create destination directories and write output atomically.
• Refuse to overwrite existing output unless --force is supplied.
• Python 3.10+; lightweight runtime dependency on nbformat.

Installation

Once published on PyPI:

python -m pip install sy-nb-sy

To install from this repository:

python -m pip install .

For development, install the editable package and test tools:

python -m pip install -e ".[dev]"

Quick Start

sy-nb-sy --help
sy-nb-sy --version

The CLI works with absolute and relative paths. On Windows PowerShell:

sy-nb-sy synapse-to-ipynb --source ".\Notebook_json\Sales.json" --target ".\Notebook_ipynb\Sales.ipynb"

On Windows Command Prompt:

sy-nb-sy synapse-to-ipynb --source ".\Notebook_json\Sales.json" --target ".\Notebook_ipynb\Sales.ipynb"

On macOS/Linux:

sy-nb-sy synapse-to-ipynb \
  --source "./Notebook_json/Sales.json" \
  --target "./Notebook_ipynb/Sales.ipynb"

Synapse JSON -> Jupyter IPYNB

sy-nb-sy synapse-to-ipynb --source <source.json> --target <target.ipynb>

Example:

sy-nb-sy synapse-to-ipynb --source "./Notebook_json/Kundan_TimeGEN_Mantis_1.json" --target "./Notebook_ipynb/Kundan_TimeGEN_Mantis_1.ipynb"

Jupyter IPYNB -> Synapse JSON

sy-nb-sy ipynb-to-synapse --source <source.ipynb> --target <target.json>

Example:

sy-nb-sy ipynb-to-synapse --source "./Notebook_ipynb/Sales.ipynb" --target "./Notebook_json/Sales.json"

Bulk Conversion

Convert each .json file in a source directory. Unrelated files are ignored; a failed notebook does not prevent other files from being converted.

sy-nb-sy bulk --source "./Notebook_json" --target "./Notebook_ipynb"

Existing targets are skipped. Add --force to replace them.

Recursive Conversion

Use --recursive to also search subdirectories. Relative directory structure is retained under the target directory:

sy-nb-sy bulk --source "./Notebook_json" --target "./Notebook_ipynb" --recursive

Examples

The Example folder contains three Synapse JSON inputs, matching converted Jupyter notebooks, and a runnable testing walkthrough. The supplied sales-analysis example has sanitized Azure identifiers; the other demos use fictional data. Conversion and walkthrough checks do not execute source notebook code.

sy-nb-sy bulk --source ".\Example\source" --target ".\Example\Target" --force

CLI Reference

Command	Purpose
synapse-to-ipynb --source PATH --target PATH	Convert a single Synapse JSON notebook
ipynb-to-synapse --source PATH --target PATH	Convert a single Jupyter notebook
bulk --source DIR --target DIR	Convert .json files in a directory

Common options are --force (replace existing targets) and --verbose (show diagnostics). bulk additionally supports --recursive. --help is available for the application and each command; --version prints the installed version.

Python API

from sy_nb_sy import ipynb_to_synapse, synapse_to_ipynb

synapse_to_ipynb("Notebook_json/test.json", "Notebook_ipynb/test.ipynb")
ipynb_to_synapse("Notebook_ipynb/test.ipynb", "Notebook_json/test.json")

For batch conversion, use synapse_to_ipynb_bulk(source, target, recursive=False, force=False). It returns a BulkConversionResult with succeeded, skipped, and failed items.

Conversion Behavior

• The Synapse parser accepts the common exported shape with root-level name and a properties object containing cells. It also accepts a properties-like root object with cells.
• code and markdown cell types are mapped directly. Source strings and arrays of source lines are accepted. Jupyter outputs and execution counts are retained for code cells.
• Synapse properties.metadata is mapped to Jupyter notebook metadata, and cell metadata maps directly to Jupyter cell metadata.
• Additional Synapse root fields, properties fields (including Spark pool/session configuration), and cell-level fields are carried in the _synapse_notebook_converter metadata namespace so they can be restored when converting back. This internal file-format key is intentionally unchanged from the original project name for compatibility with previously converted notebooks.
• Jupyter notebook metadata and cell metadata are retained in Synapse properties.metadata and cell metadata, respectively.
• A Jupyter notebook converted to Synapse without prior Synapse metadata gets a standard name/properties envelope and a notebook name based on the target filename.

Limitations

• This tool only transforms files; it never runs notebook code.
• Cell types other than code and Markdown cannot be converted to Synapse and produce an explicit error.
• Platform features that have no Jupyter equivalent are retained as namespaced metadata when present, but may not be interpreted by Jupyter or Synapse.
• Conversion is semantic rather than byte-for-byte; formatting, line-ending representation, and generated envelope defaults can differ.
• Generated Synapse JSON uses the exported notebook structure and may need adjustment for a specific Synapse workspace or runtime configuration.

Development

python -m pip install -e ".[dev]"
pytest
ruff check .

Testing

Tests use realistic Synapse/Jupyter fixtures and cover both directions, metadata, round trips, bulk/recursive operation, error cases, safe overwrite behavior, and the CLI.

Contributing

See CONTRIBUTING.md for setup and contribution guidance.

License

This project is licensed under the MIT License. See LICENSE.