{"id":14977422,"url":"https://github.com/msftserver/colab-convert","last_synced_at":"2025-04-10T01:10:45.066Z","repository":{"id":37401682,"uuid":"478762558","full_name":"MSFTserver/colab-convert","owner":"MSFTserver","description":"Convert .py files runnable in VSCode/Python or Atom/Hydrogen to jupyter/colab .ipynb notebooks and vice versa","archived":false,"fork":false,"pushed_at":"2022-08-31T03:44:27.000Z","size":332,"stargazers_count":116,"open_issues_count":2,"forks_count":21,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-10T01:10:40.428Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MSFTserver.png","metadata":{"files":{"readme":"README.md","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}},"created_at":"2022-04-06T23:46:46.000Z","updated_at":"2024-05-08T09:16:04.000Z","dependencies_parsed_at":"2022-08-02T20:45:12.897Z","dependency_job_id":null,"html_url":"https://github.com/MSFTserver/colab-convert","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MSFTserver%2Fcolab-convert","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MSFTserver%2Fcolab-convert/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MSFTserver%2Fcolab-convert/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MSFTserver%2Fcolab-convert/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MSFTserver","download_url":"https://codeload.github.com/MSFTserver/colab-convert/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248137886,"owners_count":21053775,"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","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":[],"created_at":"2024-09-24T13:55:37.666Z","updated_at":"2025-04-10T01:10:45.045Z","avatar_url":"https://github.com/MSFTserver.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# colab-convert\n\nConverts ipython/Google Colab Notebooks into runable Python code and vice versa \n\n## Features\n\n- converts files: .ipynb to .py and .py to .ipynb.\n- converts ipython/colab magic % and ! to regular python code\n- Supported magic commands (%)\n    - %pwd, %ls, %cd, %cp, %mv, %mkdir, %rm, %rmdir, %cat, %pip, %conda, %env, %setenv\n- comments out unsupported ipython magic\n- creates new import blocks for converted code\n- logs all changes to a log file for review\n- converted magic commands are appended with `#\u003ccc-cm\u003e`\n- commented magic commands are prefixed with `#\u003ccc-ac\u003e`\n- multi-lingual support to detect system language and let users choose\n    - Arabic, Dutch, English, German,\n        - consider helping expand translations by adding your langauge in the `/lang` folder\n\n\nAtom/Hydrogen or VSCode/Python allows creating a python file split into cells with `# %%` separators having the ability to run cells via the backend of a Jupyter session and interactively show results back.\n\n**VSCode**\n\n![](https://raw.githubusercontent.com/MSFTserver/colab-convert/main/examples/vscode.png)\n\n**Jupyter ipynb notebook**\n\n![](https://raw.githubusercontent.com/MSFTserver/colab-convert/main/examples/jupyter.png)\n\n## Install \u0026 Basic Usage\n\n```console\npip install colab-convert\n```\n\n```console\nUsage: colab-convert \u003cinput_file\u003e \u003coutput_file\u003e \u003cflags\u003e\n\n\u003cinput_file\u003e: input file to convert\n\u003coutput_file\u003e: output file to write to\n\u003cflags\u003e: extra flags to pass to the converter\n\nall flags are optional and have set defaults for best results\nuse flags to enable or disable certain functions on/off by default\n```\n\n```console\ncolab-convert in.ipynb out.py -nc -rm -o\n```\n\n## Default options and Flags\n```console\nDefault Flags Set (defaults are determined by input file)\n  ipynb input file:\n    [YES] convert magic , [YES] auto comment , [YES] imports , [NO] Outputs\n  py input file:\n    [NO] convert magic , [NO] auto comment , [NO] imports , [NO] Outputs\n\nAvailable Flags\n  toggle certain items on or off\n\n  --retain-magic  (-rm)  : Keep magic commands in the output\n      .py default    [ON]\n      .ipynb default [OFF]\n  --convert-magic  (-cm) : Convert magic commands to python code\n      .py default    [OFF]\n      .ipynb default [ON]\n  --auto-comment  (-ac)  : Convert unsupported magic commands to comments\n      .py default    [OFF]\n      .ipynb default [ON]\n  --no-comment  (-nc)    : Keep unsupported magic commands\n      .py default    [ON]\n      .ipynb default [OFF]\n  --no-imports  (-ni)    : Do not add imports from converted magic commands\n      .py default    [OFF]\n      .ipynb default [OFF]\n  --outputs  (-o)        : Outputs to console of conversions and commented lines.\n      .py default    [OFF]\n      .ipynb default [OFF]\n  --lang=  (-l=)         : Language to change output messages to\n       default [English]\n      --lang=en_US\n      en_US, en, english, eng, nl_NL, nl, dutch, dut, nlt, nederlands\n```\n\n# Conversion Code used\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003eclick me to see code\u003c\u003c/summary\u003e\n\n### Magic commands using bang (!)\n\nfor this particular magic we send the command to the subprocess system and print the results\n\n```python\n#   !git clone https://test.com/test/test.git\n\nsub_p_res = subprocess.run(['git', 'clone' ,'https://test.com/test/test.git'], stdout=subprocess.PIPE).stdout.decode('utf-8')\nprint(sub_p_res)\n```\n\n### Magic commands using percent (%)\n\n%pwd - get current working directory\n```python\n#   %pwd\n\nos.getcwd()\n```\n\n-----\n\n%ls - list items in directory\n```python\n#   %ls\n\nos.listdir()\n```\n```python\n#   %ls folderName/subFolder\n\nos.listdir('folderName/subFolder')\n```\n\n-----\n\n%cd - change directory\n```python\n#   %cd test-directory\n\nos.chdir('test-directory')\n```\n\n-----\n\n%mkdir - make a new directory\n\n```python\n#   %mkdir test/newFolder\n\nos.makedirs('test/newFolder')\n```\n\n%mv - move file from one location to another\n```python\n#   %mv testFile.txt testFolder/\n\nshutil.move('testFile.txt', 'testFolder/testFile.txt')\n```\n\n-----\n\n%cp - copy file from one location to another\n```python\n#   %cp testFolder/testFile.txt newFolder/newTestFile.txt\n\nshutil.copy('testFolder/testFile.txt', 'newFolder/newTestFile.txt')\n```\n\n-----\n\n%cat - show the output of a file in standard format\n```python\n#   %cat testFolder/testFile.txt\n\ncat_read_file = open('testFolder/testFile.txt', 'r')\ncat_read_text = cat_read_file.read()\nprint(cat_read_text)\ncat_read_file.close()\n```\n\n-----\n\n%env \u0026 %set_env - get, set or list environmental variables\n\nthis command actually has 5 ways to be used\n```console\n%env\n    lists all environment variables/values\n%env var\n    get value for var\n[%env or %set_env] var val\n    set value for var\n[%env or %set_env] var=val\n    set value for var\n[%env or %set_env] var=$val\n    set value for var, using python expansion if possible\n```\n```python\n#   %env\n\nfor k, v in os.environ.items():\n    print(f'{k}={v}')\n```\n```python\n#   %env var\n\nos.environ['var']\n```\n```python\n#   %env var value\n#   %set_env var value\n\nos.environ['var'] = 'value'\n```\n```python\n#   %env var=value\n#   %set_env var=value\n\nos.environ['var'] = 'value'\n```\n```python\n#   %env var=$value\n#   %set_env var=$value\n\nos.environ['var'] = '$value'\n```\n\n-----\n\n%pip - install a pip package or other pip functions\n```python\n#   %pip install colab-convert\n\npip_sub_p_res = subprocess.run(['pip', 'install', 'colab-convert'], stdout=subprocess.PIPE).stdout.decode('utf-8')\nprint(pip_sub_p_res)\n```\n\n%conda - install a conda package or other conda functions\n```python\n#   %conda install colab-convert\n\nconda_sub_p_res = subprocess.run(['conda', 'install', 'colab-convert'], stdout=subprocess.PIPE).stdout.decode('utf-8')\nprint(conda_sub_p_res)\n```\n\n### Unsupported Magic Commands\n\nthese will be commented out\n```python\n#   %quickref\n\n#\u003ccc-cm\u003e %quickref\n```\n\n\u003c/details\u003e\n\n\n## Example\n\n`colab-convert examples/plot.py examples/plot.ipynb`\n\nor\n\n`colab-convert examples/plot.ipynb examples/plot.py`\n\n\nMarkdown cells are converted to python multiline strings `'''`. Code cells are left as is.\n\neg. will render header section\n\n```python\n\"\"\"\n## Matplot example\n\n** Run the cell below to import some packages and show a line plot **\n\"\"\"\n```\n\n`# %%` is used by vscode as the cell marker on which 'Run Cell' action is available.\n\n\neg. will render a code cell\n\n```python\n# %%\nimport matplotlib.pyplot as plt\n```\n\nMetadata is converted from notebooks into .py and vise versa using `# !!` to denote the meta data lines in the .py files\n\neg.\n```python\n# %%\n# !! {\"metadata\":{\n# !!   \"id\": \"PlotIt\"\n# !! }}\nimport matplotlib.pyplot as plt\n```\n\neg. final code block must include atleast this\n```python\n# %%\n# !! {\"main_metadata\":{\n# !!   \"anaconda-cloud\": {},\n# !!   \"kernelspec\": {\n# !!     \"display_name\": \"Python 3\",\n# !!     \"language\": \"python\",\n# !!     \"name\": \"python3\"\n# !!   },\n# !!   \"language_info\": {\n# !!     \"codemirror_mode\": {\n# !!       \"name\": \"ipython\",\n# !!       \"version\": 3\n# !!     },\n# !!     \"file_extension\": \".py\",\n# !!     \"mimetype\": \"text/x-python\",\n# !!     \"name\": \"python\",\n# !!     \"nbconvert_exporter\": \"python\",\n# !!     \"pygments_lexer\": \"ipython3\",\n# !!     \"version\": \"3.6.1\"\n# !!   }\n# !! }}\n```\n\n## Troubleshooting\n\n* If encoding problems on Windows try using `python\u003e=3.7`, setting `set PYTHONUTF8=1` in Windows console and use `colab-convert` for UTF-8 files only. If using [Git-Bash on Windows](https://git-scm.com/download/win) setting:\n\n```console\nexport LANG=C.UTF-8\nexport PYTHONIOENCODING=utf-8\nexport PYTHONUTF8=1\n```\nshould be enough. Also try setting default Bash settings to UTF-8: [Options] - [Text] - [Locale / Character set] - [C / UTF-8]. It might affect all Bash runs so there would be no need to setting encoding every time. \n\n\n# Credits \n\n**colab-convert** is a fork of the [ipynb-py-convert](https://github.com/kiwi0fruit/ipynb-py-convert).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsftserver%2Fcolab-convert","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmsftserver%2Fcolab-convert","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmsftserver%2Fcolab-convert/lists"}