@deepnote/convert 1.2.1 → 1.4.0

package/README.md

@@ -1,6 +1,14 @@
 # @deepnote/convert
 
-Convert Jupyter Notebook files (`.ipynb`) to Deepnote project files (`.deepnote`).
+Bidirectional converter between Jupyter Notebook files (`.ipynb`) and Deepnote project files (`.deepnote`) with lossless roundtrip support.
+
+```bash
+# Convert a Jupyter notebook to a Deepnote project
+npx @deepnote/convert notebook.ipynb
+
+# Convert a Deepnote project to Jupyter notebooks
+npx @deepnote/convert project.deepnote
+```
 
 ## Installation
 
@@ -10,9 +18,11 @@ npm install -g @deepnote/convert
 
 ## CLI Usage
 
-The package provides a `deepnote-convert` command-line tool for converting Jupyter notebooks to Deepnote format.
+The package provides a `deepnote-convert` command-line tool for bidirectional conversion between Jupyter and Deepnote formats.
+
+### Convert Jupyter → Deepnote
 
-### Convert a Single Notebook
+#### Convert a Single Notebook
 
 Convert a single `.ipynb` file to a `.deepnote` file:
 
@@ -22,7 +32,7 @@ deepnote-convert path/to/notebook.ipynb
 
 This will create a `notebook.deepnote` file in the current directory.
 
-### Convert a Directory of Notebooks
+#### Convert a Directory of Notebooks
 
 Convert all `.ipynb` files in a directory to a single `.deepnote` project:
 
@@ -32,6 +42,16 @@ deepnote-convert path/to/notebooks/
 
 This will create a `notebooks.deepnote` file in the current directory containing all notebooks from the directory.
 
+### Convert Deepnote → Jupyter
+
+Convert a `.deepnote` file to Jupyter notebooks:
+
+```bash
+deepnote-convert path/to/project.deepnote
+```
+
+This will create a `project/` directory containing separate `.ipynb` files for each notebook in the Deepnote project.
+
 ### Options
 
 #### `--projectName <name>`
@@ -46,36 +66,57 @@ If not specified, the project name will default to the filename (without extensi
 
 #### `-o, --outputPath <path>`
 
-Specify where to save the output `.deepnote` file:
+Specify where to save the output file(s):
 
 ```bash
-# Save to a specific file
+# For Jupyter → Deepnote: Save to a specific file
 deepnote-convert notebook.ipynb -o output/project.deepnote
 
-# Save to a directory (filename will be auto-generated)
+# For Jupyter → Deepnote: Save to a directory (filename will be auto-generated)
 deepnote-convert notebook.ipynb -o output/
+
+# For Deepnote → Jupyter: Specify output directory for notebooks
+deepnote-convert project.deepnote -o output/jupyter-notebooks/
 ```
 
-If not specified, the output file will be saved in the current directory.
+If not specified:
+
+- For Jupyter → Deepnote: Output file will be saved in the current directory
+- For Deepnote → Jupyter: A directory will be created using the `.deepnote` filename (e.g., `project.deepnote` → `project/`)
 
 ### Examples
 
 ```bash
-# Convert a single notebook with custom name
+# Jupyter → Deepnote: Convert a single notebook with custom name
 deepnote-convert titanic.ipynb --projectName "Titanic Analysis"
 
-# Convert all notebooks in a directory
+# Jupyter → Deepnote: Convert all notebooks in a directory
 deepnote-convert ./analysis --projectName "Data Science Project" -o ./output
 
-# Convert multiple notebooks from a folder
+# Jupyter → Deepnote: Convert multiple notebooks from a folder
 deepnote-convert ~/notebooks/ml-experiments -o ~/projects/
+
+# Deepnote → Jupyter: Convert a Deepnote project to Jupyter notebooks
+deepnote-convert my-project.deepnote
+
+# Deepnote → Jupyter: Specify output directory
+deepnote-convert my-project.deepnote -o ./jupyter-notebooks/
 ```
 
+### Lossless Roundtrip Conversion
+
+The converter supports lossless roundtrip conversions:
+
+- **Deepnote → Jupyter → Deepnote**: Preserves all Deepnote-specific metadata in Jupyter cell metadata, enabling faithful reconstruction of the original notebook's structure and metadata (note: serialization formatting or key ordering may differ)
+- **Jupyter → Deepnote → Jupyter**: Preserves original Jupyter content while adding Deepnote metadata
+
+This is achieved by storing Deepnote-specific metadata as flat `deepnote_*` keys directly on Jupyter notebook metadata (e.g., `deepnote_notebook_id`, `deepnote_execution_mode`) and cell metadata (e.g., `deepnote_cell_type`, `deepnote_sorting_key`, `deepnote_source`).
+
 ## Programmatic Usage
 
-You can also use the conversion function programmatically in your Node.js or TypeScript applications.
+You can also use the conversion functions programmatically in your Node.js or TypeScript applications.
 
-### Basic Usage
+### Jupyter → Deepnote
 
 ```typescript
 import { convertIpynbFilesToDeepnoteFile } from "@deepnote/convert";
@@ -86,6 +127,45 @@ await convertIpynbFilesToDeepnoteFile(["path/to/notebook.ipynb"], {
 });
 ```
 
+### Deepnote → Jupyter
+
+#### File-based Conversion
+
+For automatic file I/O (reading and writing files):
+
+```typescript
+import { convertDeepnoteFileToJupyter } from "@deepnote/convert";
+
+await convertDeepnoteFileToJupyter("path/to/project.deepnote", {
+  outputDir: "./jupyter-notebooks",
+});
+```
+
+#### Pure Conversion (No File I/O)
+
+For programmatic use with in-memory data:
+
+```typescript
+import fs from "node:fs/promises";
+import { deserializeDeepnoteFile } from "@deepnote/blocks";
+import { convertDeepnoteToJupyterNotebooks } from "@deepnote/convert";
+
+// Read and deserialize the Deepnote file
+const yamlContent = await fs.readFile("project.deepnote", "utf-8");
+const deepnoteFile = deserializeDeepnoteFile(yamlContent);
+
+// Convert to Jupyter notebooks (pure function, no I/O)
+const notebooks = convertDeepnoteToJupyterNotebooks(deepnoteFile);
+
+// Now you can work with the notebooks in memory
+for (const { filename, notebook } of notebooks) {
+  console.log(`${filename}: ${notebook.cells.length} cells`);
+
+  // Or save them yourself
+  await fs.writeFile(filename, JSON.stringify(notebook, null, 2));
+}
+```
+
 ## License
 
 Apache-2.0

package/dist/bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { t as convertIpynbFilesToDeepnoteFile } from "./src-n1bYyJ74.js";
+import { a as convertDeepnoteFileToJupyterFiles, t as convertIpynbFilesToDeepnoteFile } from "./src-DgOsAHcf.js";
 import { cli } from "cleye";
 import fs from "node:fs/promises";
 import { basename, extname, resolve } from "node:path";
@@ -60,7 +60,19 @@ async function convert(options) {
 			throw error;
 		}
 	}
-	if (ext === ".deepnote") throw new Error("The .deepnote format is not supported for conversion yet.");
+	if (ext === ".deepnote") {
+		const spinner = ora("Converting Deepnote project to Jupyter Notebooks...").start();
+		try {
+			const outputDirName = basename(absolutePath, ext);
+			const outputDir = customOutputPath ? resolve(cwd, customOutputPath) : resolve(cwd, outputDirName);
+			await convertDeepnoteFileToJupyterFiles(absolutePath, { outputDir });
+			spinner.succeed(`Jupyter Notebooks have been saved to ${chalk.bold(outputDir)}`);
+			return outputDir;
+		} catch (error) {
+			spinner.fail("Conversion failed");
+			throw error;
+		}
+	}
 	throw new Error("Unsupported file type. Please provide a .ipynb or .deepnote file.");
 }