{"id":13628153,"url":"https://github.com/hpi-swa/ipolyglot","last_synced_at":"2025-09-05T07:43:36.521Z","repository":{"id":51575486,"uuid":"181734261","full_name":"hpi-swa/ipolyglot","owner":"hpi-swa","description":"A polyglot kernel for Jupyter notebooks based on GraalVM.","archived":false,"fork":false,"pushed_at":"2023-07-20T17:37:49.000Z","size":2016,"stargazers_count":96,"open_issues_count":6,"forks_count":5,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-06-09T13:42:19.996Z","etag":null,"topics":["graalvm","jupyter","kernel","polyglot","polyglot-notebooks","polyglot-programming"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hpi-swa.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,"governance":null}},"created_at":"2019-04-16T17:16:01.000Z","updated_at":"2025-03-28T22:14:24.000Z","dependencies_parsed_at":"2023-01-23T01:15:12.798Z","dependency_job_id":"79c2302d-7a5e-4731-922e-d72d48609163","html_url":"https://github.com/hpi-swa/ipolyglot","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/hpi-swa/ipolyglot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hpi-swa%2Fipolyglot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hpi-swa%2Fipolyglot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hpi-swa%2Fipolyglot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hpi-swa%2Fipolyglot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hpi-swa","download_url":"https://codeload.github.com/hpi-swa/ipolyglot/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hpi-swa%2Fipolyglot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273728129,"owners_count":25157136,"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-05T02:00:09.113Z","response_time":402,"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":["graalvm","jupyter","kernel","polyglot","polyglot-notebooks","polyglot-programming"],"created_at":"2024-08-01T22:00:47.049Z","updated_at":"2025-09-05T07:43:31.505Z","avatar_url":"https://github.com/hpi-swa.png","language":"JavaScript","funding_links":[],"categories":["Uncategorized"],"sub_categories":["Uncategorized"],"readme":"# IPolyglot\nA polyglot [Jupyter kernel](https://jupyter.readthedocs.io/en/latest/projects/kernels.html) for the [GraalVM](https://www.graalvm.org/).\n\n\u003cimg width=\"1519\" alt=\"Screenshot\" src=\"https://user-images.githubusercontent.com/9486619/62134314-8d076000-b2e0-11e9-950e-b773f41ac085.png\"\u003e\n\n## Blog post\n\nGet some more background on how IPolyglot works, by reading the blog post about the [HPI Polyglot Programming Seminar](https://medium.com/graalvm/hpi-polyglot-programming-seminar-3fd06ffa59d2). And thereafter, follow on with the rest of the sections below.\n\n## Running IPolyglot on Docker\n\nIf you'd like to run IPolyglot on [Docker](https://www.docker.com/), this should get you started:\n\n```sh\n# 1. Clone IPolyglot's repository\ngit clone https://github.com/hpi-swa/ipolyglot.git\ncd ipolyglot\n# 2. Build an IPolyglot docker image\ndocker build --tag=ipolyglot .\n# 3. Run it! (choose a different port by changing 8888:\u003cdesired port\u003e)\ndocker run -p 8888:8888 ipolyglot\n```\n\nProceed by opening a web-browser on `localhost:8888`, and creating a new notebook.\n\n## Running IPolyglot from source\n\nMake sure to [install](https://www.graalvm.org/downloads) GraalVM (latest tested version is v19.0.2) and ensure GraalVM's `node` and `npm` are in your `PATH`:\n\n```sh\nexport PATH=$GRAALVM_HOME/Contents/Home/jre/languages/js/bin:$PATH\nexport PATH=$GRAALVM_HOME/Contents/Home/bin:$PATH\n```\n\nTo install the kernel on Linux follow these steps:\n```sh\n# 0. download and setup GraalVM\n# 1. install python and pip:\nyum install -y python36 python36-devel python36-pip\n# 2. install the jupyter pip package:\npip3 install jupyter_core==4.4 jupyter\n# 3. install ipolyglot from source:\ngit clone https://github.com/hpi-swa/ipolyglot.git\ncd ./ipolyglot \u0026\u0026 npm install .\n```\n\nOn macOS, run:\n```sh\n# 0. download and setup GraalVM\n# 1. install python and pip:\nbrew install python3\n# 2. install additional dependencies\nbrew install pkg-config zeromq\n# 3. install the jupyter pip package and its requirements\npip install jupyter_core==4.4 pyzmq jupyter\n# 3. install ipolyglot from source:\ngit clone https://github.com/hpi-swa/ipolyglot.git\ncd ./ipolyglot \u0026\u0026 npm install . --python=python2.7\n```\n\nProceed by starting a Jupyter notebook server (`jupyter notebook`), opening a web-browser on `localhost:8888`, and creating a new notebook.\n\n\n## Using different programming languages\n\nA different language can be used in each notebook cell. Simply specify the desired language as a [magic command](https://ipython.readthedocs.io/en/stable/interactive/magics.html) in the first line of the cell. Available language codes are `python`, `js`, `ruby`, `R`.\n\n```ruby\n%polyglot [language code]\n\n[code]\n```\n\nfor example:\n\n```python\n%polyglot python\n\nmy_dict = dict()\n```\n\nSee the [`polyglot-notebook.ipynb`](demo/polyglot-notebook.ipynb) for a detailed example.\n\nPlease be aware that you can use languages that have been [installed to your GraalVM](https://www.graalvm.org/docs/reference-manual/graal-updater/) only.\n\n## Inspecting Polyglot variables\n\nThe Polyglot Jupyter Kernel shares all available global variables across all notebook cells. It provides an inspector extension to the Jupyter notebook frontend that lists all polyglot variables available.\n\nTo install the extension, move the extension's code found in `varInspector` to your local installation of the `jupyter_contrib_nbextensions` package and install it, like so:\n\n```sh\ncd ./ipolyglot  # make sure to run all commands from the ipolyglot repository's root\ngit clone https://github.com/ipython-contrib/jupyter_contrib_nbextensions.git\npip install -e ./jupyter_contrib_nbextensions\ncp -r ./varInspector ./jupyter_contrib_nbextensions/src/jupyter_contrib_nbextensions/nbextensions/\njupyter contrib nbextensions install --user\njupyter nbextension enable varInspector/main\n```\n\nRestart your notebook and toggle the variable inspector with the \u003ckbd\u003e🎯\u003c/kbd\u003e button in top toolbar.\n\n## Debugging the IPolyglot Kernel\n\nThis describes how to debug the IPolyglot Kernel, _not_ how to debug code executed in the code cells.\n\nThe `jupyter notebook` command can be invoked like this `DEBUG=true jupyter-notebook --debug` to get debugging information about the messages sent between the kernel and the Jupyter notebook.\n\nHowever, it has often been more helpful to pass debug flags to GraalVM's Node.js process which actually evaluates the code of Jupyter Notebook cells. This is done in node_modules/nel/lib/nel.js where `Session._args` is defined. There is a commented out line which already includes the necessary flags and can be commented in if need be. Then, a `debugger;` statement can be set anywhere in the NEL code and the Node.js session can be found in [chrome://inspect/#devices](chrome://inspect/#devices) for debugging.\n\n## Current Limitations\n\n### [Output and error handling](https://github.com/hpi-swa/ipolyglot/issues/13)\n\nCurrently, if `print` / `put` / ... is called in a language other than JavaScript inside a Jupyter Notebook code cell, the print output is not displayed in the frontend of the Jupyter Notebook. Similarly, if an error occurs during execution of the code of a cell, the error might not be properly propagated to the frontend for display to the user.\n\nWe've tried a bunch of things to make output and error handling work but have not completely succeeded. Below we want to document two approaches that seem most promising.\n\n#### Approach 1 (more preferable option)\n\nBranch: https://github.com/hpi-swa/ipolyglot/tree/feature/output_handling_polyglot_context\n\nThis approach creates a `org.graalvm.polyglot.context polyglotContext` in node_modules/nel/lib/server/main.js and passes a `ByteArrayOutputStream polyglotStdout` to it. Whenever `polyglotContext.eval` is called now, print outputs of the executed code is written to `polyglotStdout`. Later on, `polyglotStdout`'s contents can be easily accessed and redirected to the frontend. See short code example here: https://github.com/hpi-swa-lab/pp19/issues/19#issuecomment-514649627\n\nRegarding error handling: If an error occurs during the call to `polyglotContext.eval`, the error is caught and the original error message from the guest language is redirected to the frontend (`initialContext.console.error(codeCellStderr)`).\n\nThe issue with this approach is that it doesn't work together at all with our automatic import/export feature: To make the automatic import/export work, we use `Polyglot.eval`, `Polyglot.import` and `Polyglot.export`. However, once we use our custom `polyglotContext.eval` (to capture the stdout properly), the code is evaluated in another context than the context we access using `Polyglot.*`. Therefore, we e.g. can't export variables defined in `polyglotContext.eval` using `Polyglot.import`. According to the [docs](https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/Context.html#getPolyglotBindings--), we might be able to work around this by doing `polyglotContext.getPolyglotBindings.import()` / `...export()`. However, calling `polyglotContext.getPolyglotBindings` results in [an error](https://github.com/hpi-swa-lab/pp19/issues/20). If the issue can be solved, this approach seems to be most appropriate and clean.\n\n#### Approach 2 (less preferable option)\n\nBranch: https://github.com/hpi-swa/ipolyglot/tree/feature/output_handling\n\nThis approach redirects the output from the code evaluation process to a log file and reads from it to send it to the Jupyter Notebook frontend. The solution works, however the lag can be pretty big at times and once you try to restart the kernel from the Jupyter Notebook frontend, the kernel becomes completely unresponsive and you have to restart the entire Jupyter Notebook server process and kill an orphaned/zombie (?) Node.js process manually. We suspected this might be due to a missing close or end call to the file write stream but we checked this and it doesn't seem to be the underlying issue.\n\nWe assume that the same approach can be taken to handle errors raised during code cell execution as well but have not tested this yet.\n\nIn node_modules/nel/lib/nel.js, a write stream `tmp_stdout` is created which writes into a file 'tmp_stdout.log'. This write stream is specified as the stdout handle for the code evaluation process via `this._config = { stdio: [\u003cstdin\u003e, tmp_stdout, ...] }`.\n\nThe code evaluation process itself defines a `stdout_tail` in node_modules/nel/lib/server/main.js which listens to any output redirected to the 'tmp_stdout.log' file and sends it to the Jupyter Notebook frontend.\n\n## Academic Publication\n\n*IPolyglot is based on the ideas presented in the following paper:*\n\nFabio Niephaus, Eva Krebs, Christian Flach, Jens Lincke, and Robert Hirschfeld.\n[*PolyJuS: A Squeak/Smalltalk-based Polyglot Notebook System for the GraalVM*][px19_paper]. In\nProceedings of [the Programming Experience 2019 (PX/19) Workshop][px19],\ncompanion volume to International Conference on the Art, Science, and\nEngineering of Programming (‹Programming›), co-located with the International\nConference on the Art, Science, and Engineering of Programming (‹Programming›),\n6 pages, Genova, Italy, April 1, 2019, ACM DL.  \n[![doi][px19_doi]][px19_paper] [![bibtex][bibtex]][px19_bibtex] [![Preprint][preprint]][px19_pdf]\n\n\n## Acknowledgments\n\nThis projects builds on the tremendous work of [Nicolas Riesco](https://github.com/n-riesco)'s [IJavascript](https://github.com/n-riesco/ijavascript), a Javascript kernel for Jupyter notebooks.\n\n\n[bibtex]: https://img.shields.io/badge/bibtex-download-blue.svg\n[preprint]: https://img.shields.io/badge/preprint-download-blue.svg\n[px19]: https://2019.programming-conference.org/track/px-2019-papers\n[px19_bibtex]: https://dl.acm.org/downformats.cfm?id=3328434\u0026parent_id=3328433\u0026expformat=bibtex\n[px19_doi]: https://img.shields.io/badge/doi-10.1145/3328433.3328434-blue.svg\n[px19_paper]: https://doi.org/10.1145/3328433.3328434\n[px19_pdf]: https://fniephaus.com/2019/px19-polyglot-notebooks.pdf\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhpi-swa%2Fipolyglot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhpi-swa%2Fipolyglot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhpi-swa%2Fipolyglot/lists"}