{"id":13737210,"url":"https://github.com/stisa/jupyternim","last_synced_at":"2025-10-10T09:47:18.728Z","repository":{"id":45339298,"uuid":"66958470","full_name":"stisa/jupyternim","owner":"stisa","description":"A Jupyter kernel for nim","archived":false,"fork":false,"pushed_at":"2022-12-30T22:29:00.000Z","size":1042,"stargazers_count":165,"open_issues_count":5,"forks_count":14,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-23T21:22:24.343Z","etag":null,"topics":["hacktoberfest","ipython","jupyter","jupyter-kernel","jupyter-kernels","nim","nteract"],"latest_commit_sha":null,"homepage":"https://stisa.space/jupyternim/","language":"Nim","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/stisa.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":"2016-08-30T16:30:20.000Z","updated_at":"2025-02-08T01:39:05.000Z","dependencies_parsed_at":"2023-01-31T17:00:25.294Z","dependency_job_id":null,"html_url":"https://github.com/stisa/jupyternim","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stisa%2Fjupyternim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stisa%2Fjupyternim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stisa%2Fjupyternim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stisa%2Fjupyternim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stisa","download_url":"https://codeload.github.com/stisa/jupyternim/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248095967,"owners_count":21046953,"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":["hacktoberfest","ipython","jupyter","jupyter-kernel","jupyter-kernels","nim","nteract"],"created_at":"2024-08-03T03:01:37.553Z","updated_at":"2025-10-10T09:47:13.707Z","avatar_url":"https://github.com/stisa.png","language":"Nim","funding_links":[],"categories":["Development Tools"],"sub_categories":["REPL"],"readme":"![logo.svg](logo.svg) Jupyter Nim \n====\n\nThis is a beta  [jupyter](http://jupyter.org/) kernel for nim written in nim.  \nWorks with `notebook`, `lab`, `nteract`, should even work in `vscode-python`.  \nIf you use `nteract` or `vscode-python`, there are still some problems, please report them.  \nFor `jupyter lab`, you can also install the companion extension by `jupyter labextension install jupyternim-labextension`  \nthat provides syntax highlighting.\n  \nLook at [example-notebook](examples/example-notebook.ipynb) for some examples,  \nand at [example-display](examples/example-display.ipynb) for examples of displaying latex, md, etc.  \n\nNOTE: running a notebook with this creates a directory `~/.jupyternim` in which it stores blocks of code, pngs, compiled outputs, etc.\nCompilation output should be automatically cleaned up starting from version 0.6.0.\n\nNOTE2: `nteract` support is very wip, also `nteract` doesn't add a cellId to notebook cells so changing types is buggy, I'll work on it and maybe also provide a patch for nteract, but it's low priority, help appreciated.\n\nInstallation \n------------\nTL,DR:\n```\nnimble install jupyternim -y\n```\nDone!\n\n`jupyternim -v` has some details about how it was compiled.\n\n### Prereqs\n\n- a working `nim` installation ( [download](http://nim-lang.org/download.html) )\n- a `zeromq` installation. Currently tested only with [ZeroMQ](http://zeromq.org/intro:get-the-software) 4.2. **It must be in PATH or the kernel won't run**.\n  - you may already have this installed, it will be checked when you install `jupyternim` to see if you need to install it yourself\n- some kind of jupyter environment, some examples:\n  - `jupyter`  ( I recomend [miniconda3](http://conda.pydata.org/miniconda.html) and adding jupyter with `conda install jupyter` )\n  - `nteract` (get it [here](https://nteract.io/))\n  - `vscode`+`vscode-python` extension ( poor naming, but `vscode-python` also provides `jupyter` support )\n\n### Long version:\n\nThe kernel should be automatically compiled and registered by doing `nimble install jupyternim` ( or `nimble install https://github.com/stisa/jupyternim` if it's not in nimble yet).\n\nAlternatively, try the following:\n\n- clone this repo: `git clone https://github.com/stisa/jupyternim`\n- then go into the cloned dir `cd jupyternim`\n- register to nimble with `nimble install`\n- compile with `nimble dev`, this will give you a debug version\n- run `jupyternim`to register the kernel\n- run `jupyter notebook`\n\nNote that [ZeroMQ](http://zeromq.org/intro:get-the-software) is dinamically linked, so it needs to be installed **and added to path**  \n\n### HotCodeReloading\nTo enable the **very** experimental hotcodereloading support, you'll need to recompile `jupyternim` with `-d:useHcr` and then overwrite the one in `~/.nimble/pkgs/jupyternim-\u003cversion\u003e` with it.  \nThe hotcodereloading mostly works, but there are various bugs that prevent its use. For examples, printing a float crashes it.\n\nEditing\n-------\n\n`TAB` : completion request, for example `p\u003cTAB` -\u003e a pop up with possible completions  \n![completion](examples/jlabcompletion.gif)\n\nTODO:\n- [ ] `shift+TAB` : inspection request, for example `echo\u003cshift+TAB\u003e` -\u003e a pop with a description of echo \n- [ ] support the debugger protocol, support variable value inspection\n\nMagics:\n-------\n\n**passing flags**\n\n`#\u003eflags \u003c --some \u003e \u003c --d:flag \u003e`\nPass flags to nim compiler, default is `--verbosity:0 -d:release`.  \nPassing new flags overwrites all other previous flags, even default ones.\nExample: \n```nim\n#\u003eflags -d:test\n\necho \"hi\"\nwhen defined test:\n  echo \"test defined\"\nelse:\n  echo \"test not defined\"\n```\nOutputs:\n```\nhi\ntest defined\n```\nTODO: provide a way to override default compilation output file\n\n### Delete old temp files\n`#\u003eclear all`\n\n### Displaying data\nTo send back data to display, you can use the module [jupyternimpkg/display](src/jupyternimpkg/display.nim), example:  \n\n```nim\nimport nimPNG, jupyternimpkg/display\n\nlet file = r\"..\\\\src\\\\jupyternimspec\\\\logo-64x64.png\"\nshow dkPngFile, [64, 64]: # [width, height]\n    file\n```\n\nIf your file type is not supported by the `display` module yet, you need to implement the proc yourself.\nJust write to stdout a string containing a json object defined as\n```json\n{   //\u003cdata\u003e is base64 encoded for binary formats, eg png\n    \"data\": {\"\u003cmimetype\u003e\": \u003cdata\u003e}, \n    \"metadata\": {\"\u003cmimetype\u003e\": {\u003cmimespecific\u003e}},\n    \"transient\": {}\n}\n```\nenclosed in `#\u003cjndd\u003e#` and `#\u003coutjndd\u003e#` markers.\nFor example, to display a PNG image, simply:\n```nim\nimport json, base64\nvar \n  img = readFile(path).encode # encode the png file with base64\n  w = 320 # displayed width\n  h = 240 # displayed height\nvar content: JsonNode = %*{\n    \"data\": {\"image/png\": img }, \n    \"metadata\": %*{\"image/png\": {\"width\": w, \"height\":h}},\n    \"transient\": %*{}\n  }\n\necho \"#\u003cjndd\u003e#\" \u0026 $content $ \"#\u003coutjndd\u003e#\"\n```\nConsider sending a pr for the display module if you end up having to do this.\n\nTODO\n----\n- [ ] Finish implementing messaging ( completion, introspection, history, update_display_data... )\n- [ ] Connect to nimsuggest via socket, parse its output for introspection requests\n- [ ] Documentation lookup magic? \n  - eg. put docs in a subfolder, then `#\u003edoc sequtils` opens a browser to the correct `.html` page ( possibly local )  \n- [ ] improve hotcodereloading (probably needs work on the compiler side)\n- [ ] convince jupyter notebook maintainers to provide cellId, so I can stop patching the javascript\n- [ ] find a better way to fake a repl than re running prior code and discarding output (we have HCR! Buggy though)\n- [ ] use `JNsession` as name for temp files (allows multiple open kernels)\n- [ ] a better way to handle `display_data` than string delimiters\n\nGeneral structure\n-----------------\n\n### [jupyternim](src/jupyternim.nim)\nHandles init, start, stop of the various loops, as well as initial installation of the kernelspec. \n\n### [jupyternimpkg/messages](src/jupyternimpkg/messages.nim)\nHandles message specifications exposing low level procs to decode, encode messages\n\n### [jupyternimpkg/sockets](src/jupyternimpkg/sockets.nim)\nDefines sockets types, how they are created, how their loops work, how they send and receive messages\n\n### [jupyternimpkg/display](src/jupyternimpkg/display)\nHandle preparing and sending back data to display\n\n### [jupyternimspec](src/jupyternimspec/)\nLogos for jupyter, a `kernel.js` file to load syntax highlight and patch jupyter notebook to send\na cellId.\n\nInternal Notes\n--------------\nMessages must be multipart  \nsignature-must-be-lowercase  \n\nhttp://nim-lang.org/docs/tinyc.html  \n\n[Jupyter Kernel Docs](https://jupyter-client.readthedocs.io/en/latest/kernels.html#kernels)  \n[IHaskell](http://andrew.gibiansky.com/blog/ipython/ipython-kernels)  \n[Messaging Docs](https://jupyter-client.readthedocs.io/en/latest/messaging.html)  \n[Async logger in nim](https://hookrace.net/blog/writing-an-async-logger-in-nim/)  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstisa%2Fjupyternim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstisa%2Fjupyternim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstisa%2Fjupyternim/lists"}