{"id":15014903,"url":"https://github.com/williamjameshandley/py2nb","last_synced_at":"2025-09-06T16:41:07.768Z","repository":{"id":57455639,"uuid":"156086469","full_name":"williamjameshandley/py2nb","owner":"williamjameshandley","description":"convert python scripts to jupyter notebooks","archived":false,"fork":false,"pushed_at":"2025-06-03T13:28:21.000Z","size":271,"stargazers_count":43,"open_issues_count":2,"forks_count":8,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-08-16T02:35:41.675Z","etag":null,"topics":["converter","ipython","jupyter-notebook","python","python-script"],"latest_commit_sha":null,"homepage":null,"language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/williamjameshandley.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2018-11-04T13:44:39.000Z","updated_at":"2025-08-01T00:29:00.000Z","dependencies_parsed_at":"2025-09-06T16:41:06.215Z","dependency_job_id":null,"html_url":"https://github.com/williamjameshandley/py2nb","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/williamjameshandley/py2nb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamjameshandley%2Fpy2nb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamjameshandley%2Fpy2nb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamjameshandley%2Fpy2nb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamjameshandley%2Fpy2nb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/williamjameshandley","download_url":"https://codeload.github.com/williamjameshandley/py2nb/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamjameshandley%2Fpy2nb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273933333,"owners_count":25193599,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-06T02:00:13.247Z","response_time":2576,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["converter","ipython","jupyter-notebook","python","python-script"],"created_at":"2024-09-24T19:46:14.812Z","updated_at":"2025-09-06T16:41:07.755Z","avatar_url":"https://github.com/williamjameshandley.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"==================================================\npy2nb: convert python scripts to jupyter notebooks\n==================================================\n:py2nb: convert python scripts to jupyter notebooks\n:Author: Will Handley\n:Version: 1.1.1\n:Homepage: https://github.com/williamjameshandley/py2nb\n\n.. image:: https://badge.fury.io/py/py2nb.svg\n   :target: https://badge.fury.io/py/py2nb\n   :alt: PyPi location\n\nDescription\n===========\n\n``py2nb`` is a python package for converting python scripts with minimal\nmarkdown to jupyter notebooks.\n\nMarkdown cells are rendered from comments beginning with ``#|``, splits between\ncode cells are created by comment lines beginning with ``#-``, and command cells\n(for shell commands like pip installs) are created from comments beginning with ``#!``\n\n``nb2py`` converts from jupyter notebooks to python\n\nInstallation\n============\n\nUsers can install using pip:\n\n.. code:: bash\n\n   pip install py2nb\n\nfrom source:\n\n.. code:: bash\n\n   git clone https://github.com/williamjameshandley/py2nb\n   cd py2nb\n   python setup.py install\n\nor for those on `Arch linux \u003chttps://www.archlinux.org/\u003e`__ it is\navailable on the\n`AUR \u003chttps://aur.archlinux.org/packages/python-py2nb/\u003e`__\n\nProgrammatic Usage\n==================\n\nBoth ``py2nb`` and ``nb2py`` can be imported and used programmatically:\n\n.. code:: python\n\n   import py2nb\n   import nb2py\n   \n   # Convert script to notebook\n   notebook_path = py2nb.convert('script.py')\n   \n   # Convert with custom output and execution\n   executed_notebook = py2nb.convert('script.py', \n                                     output_name='workshop.ipynb', \n                                     execute=True)\n   \n   # Convert notebook back to script  \n   script_path = nb2py.convert('notebook.ipynb', output_name='converted.py')\n\nExample\n=======\n\nIf one has a script named ``example.py`` containing the code:\n\n.. code:: python\n\n    #| # Testing ipython notebook\n    #| This is designed to demonstrate a simple script that converts a script into\n    #| a jupyter notebook with a simple additional markdown format.\n    #|\n    #| Code by default will be put into code cells\n    #|\n    #| * To make a markdown cell, prefix the comment line with '#|' or '# |'\n    #| * To split a code cell, add a line beginning with '#-' or '# -'\n    #| * To make a command cell, prefix the comment line with '#!' or '# !'\n\n    #! pip install matplotlib numpy\n    #! pip install scipy\n\n    import matplotlib.pyplot as plt\n    import numpy as np\n\n    %matplotlib inline\n\n    #| Here is a markdown cell.\n    #| Maths is also possible: $A=B$\n    #|\n    #| There are code cells below, split by `'#-'`:\n\n    # | Here is another markdown cell\n\n    x = np.random.rand(5)\n\n    #-------------------------------\n\n    y = np.random.rand(4)\n    z = np.random.rand(3)\n\n    #| Here are some plots\n\n    x = np.linspace(-2,2,1000)\n    y = x**3\n    fig, ax = plt.subplots()\n    ax.plot(x,y)\n\n    # -------------------------------\n\n    # | Here is another plot\n\n    x = np.linspace(-np.pi, np.pi, 201)\n    fig, ax = plt.subplots()\n    ax.plot(x,np.sin(x))\n\n\nthen running\n\n.. code :: bash\n\n   py2nb example.py\n\nproduces the notebook `example.ipynb \u003chttps://github.com/williamjameshandley/py2nb/blob/master/example.ipynb\u003e`_\n\nTo see an executed version with outputs and plots, run:\n\n.. code :: bash\n\n   py2nb example.py --execute --output example_executed\n\nwhich produces `example_executed.ipynb \u003chttps://github.com/williamjameshandley/py2nb/blob/master/example_executed.ipynb\u003e`_ with all code cells executed and outputs displayed.\n\nCommand Line Options\n====================\n\n.. code:: bash\n\n   py2nb script.py                      # Basic conversion\n   py2nb script.py --no-validate        # Skip notebook validation  \n   py2nb script.py --execute            # Convert and execute notebook\n   py2nb script.py --output workshop    # Custom output name\n   py2nb script.py --output workshop --execute  # Custom name + execution\n\n   nb2py notebook.ipynb                 # Convert notebook to script\n   nb2py notebook.ipynb --output script # Custom output script name\n\nCommand Blocks\n==============\n\nCommand blocks allow you to run shell commands (like pip installs) in separate notebook cells:\n\n.. code:: python\n\n    #| # Workshop Example\n    #| This demonstrates command blocks for dependency management\n\n    #! pip install numpy matplotlib\n    #! pip install seaborn\n\n    import numpy as np\n    import matplotlib.pyplot as plt\n\n    #| ## Advanced Analysis\n    #| Install additional dependencies when needed\n\n    #! pip install scikit-learn\n\n    from sklearn import datasets\n\nThis creates dedicated cells for commands, improving modularity and compatibility\nwith platforms like Google Colab.\n\nExecution Option\n================\n\nThe ``--execute`` option runs the converted notebook using jupyter nbconvert,\ncreating a new notebook with outputs included:\n\n.. code:: bash\n\n   py2nb workshop.py --execute                    # Execute in place\n   py2nb workshop.py --output clean               # Create clean.ipynb\n   py2nb workshop.py --output executed --execute  # Create executed.ipynb with outputs\n\nThe ``--output`` option allows you to specify custom filenames, giving you complete control\nover the generated notebook names. Useful for creating workshop materials with pre-computed \nresults, or for testing that your workshop notebooks execute successfully.\n\n**Requirements**: Requires ``nbconvert`` to be installed (``pip install nbconvert``).\n\nTesting\n=======\n\nTo run the test suite:\n\n.. code:: bash\n\n   python test_py2nb.py\n\nThe test suite includes 16 test cases covering:\n\n* Basic conversion functionality\n* Markdown cell creation (``#|`` syntax)\n* Code cell splitting (``#-`` syntax)\n* Command block creation (``#!`` syntax)\n* Notebook execution (``--execute`` option)\n* Custom output filenames (``--output`` option)\n* nb2py reverse conversion with custom output\n* Programmatic module usage\n* Mixed syntax combinations\n* Notebook metadata and validation\n* UTF-8 encoding support\n* Backward compatibility\n* Error handling\n\nVim Integration\n===============\n\nFor vim users working with py2nb syntax, you can enhance your editing experience:\n\n**Syntax Highlighting**\n\nAdd to your ``.vimrc`` for basic py2nb syntax support:\n\n.. code:: vim\n\n   \" py2nb syntax highlighting\n   autocmd BufRead,BufNewFile *.py syntax match Comment \"#|.*$\" \n   autocmd BufRead,BufNewFile *.py syntax match Special \"#!.*$\"\n   autocmd BufRead,BufNewFile *.py syntax match Delimiter \"#-.*$\"\n\n**File Templates**\n\nCreate a py2nb template in ``~/.vim/templates/py2nb.py``:\n\n.. code:: python\n\n   #| # Workshop Title\n   #| \n   #| Brief description and learning objectives\n   \n   #! pip install required_packages\n   \n   import standard_libraries\n   \n   #| ## Section 1: Core Concepts\n   #| Essential material description\n   \n   # Your code here\n   \n   #-\n   \n   # Next code cell\n   \n   #| ## Section 2: Advanced Topics\n   #| Building on previous concepts\n\nThen use ``:read ~/.vim/templates/py2nb.py`` to insert the template.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilliamjameshandley%2Fpy2nb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwilliamjameshandley%2Fpy2nb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilliamjameshandley%2Fpy2nb/lists"}