notebook-to-code

Jupyter Notebook ➜ Python converter with round‑trip metadata, semantic Markdown processing, a pluginable theme system, batch mode, and a friendly CLI.

Key features

• Convert .ipynb ➜ .py with clear, annotated cells
• Optional reverse conversion (annotated .py ➜ .ipynb)
• Semantic Markdown processing and wrapping
• Round‑trip metadata to validate integrity
• Batch processing for folders/patterns
• Theme plugins (e.g., default, minimal)
• Rich CLI output (optional)

Install

• Stable release:
  • pip install notebook-to-code
• Extras:
  • GUI: pip install notebook-to-code[gui]
  • Analysis: pip install notebook-to-code[analysis]
  • Dev: pip install notebook-to-code[dev]

Quickstart

• Convert a single notebook:
  • CLI: notebook-to-code convert path/to/notebook.ipynb -o out.py --stats
  • Python one‑liner:
    • from notebook_converter import convert_notebook; convert_notebook("path/to/notebook.ipynb", "out.py")
• Batch convert a folder:
  • notebook-to-code batch notebooks/ -o converted/ --pattern *.ipynb
• Reverse (annotated .py ➜ .ipynb):
  • notebook-to-code reverse script.py -o out.ipynb
• List themes:
  • notebook-to-code themes

CLI Options (highlights)

• --theme default|minimal choose a theme
• --no-metadata disable metadata preservation
• --no-round-trip disable round‑trip metadata
• --no-semantic-markdown disable semantic Markdown
• --quality-analysis enable code quality checks
• --max-line-length 88 wrap text/comments at length
• --stats show conversion statistics

Python API (minimal)

from notebook_converter import AdvancedNotebookConverter, ConversionOptions

options = ConversionOptions(semantic_markdown=True, round_trip_metadata=True)
converter = AdvancedNotebookConverter(options=options)

out_file, stats = converter.convert_notebook("path/to/notebook.ipynb", "out.py")
print("Converted:", out_file)

Project structure

• Package: notebook_converter (import path)
• CLI: notebook-to-code (entry point)
• Source: notebook_converter/src/notebook_converter/

Contributing

• Create a virtual env and install in editable mode:
  • pip install -e .[dev]
• Run tests (if configured):
  • pytest -q

License

• MIT

How PyPI description works

• The "Project description" on PyPI is rendered from this README.md.
• Configuration is set in pyproject.toml via readme = "README.md" and description.
• To update what appears on PyPI:
  1. Edit this README.
  2. Bump the version in pyproject.toml and in notebook_converter/src/notebook_converter/__init__.py.
  3. Rebuild and upload a new release:
     • py -m build && py -m twine upload dist/*
• PyPI does not allow editing a release’s metadata in place; publish a new version to change the description.