| Name | jupynium JSON |
| Version |
0.2.5
JSON |
| download |
| home_page | None |
| Summary | Neovim plugin that automates Jupyter Notebook editing/browsing using Selenium. |
| upload_time | 2024-11-14 13:18:43 |
| maintainer | None |
| docs_url | None |
| author | Kiyoon Kim |
| requires_python | >=3.8 |
| license | MIT License Copyright (c) 2023 Kiyoon Kim Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
neovim
vim
jupyter
selenium
jupyter-notebook
nvim
neovim-plugin
nvim-plugin
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Jupynium: Control Jupyter Notebook on Neovim with ZERO Compromise
<a href="https://github.com/kiyoon/jupynium.nvim/actions/workflows/tests.yml">
<img src="https://github.com/kiyoon/jupynium.nvim/workflows/Tests/badge.svg?style=flat" />
</a>
**It's just like a markdown live preview, but it's Jupyter Notebook live preview!**
Jupynium uses Selenium to automate Jupyter Notebook, synchronising everything you type on Neovim.
Never leave Neovim. Switch tabs on the browser as you switch files on Neovim.
Note that it doesn't sync from Notebook to Neovim so only modify from Neovim.
<img src=https://user-images.githubusercontent.com/12980409/221559945-46f12a38-2fb8-4156-bb94-b87e831ac8f5.gif width=100% />
## How does it work?
<img src=https://user-images.githubusercontent.com/12980409/211933889-e31e844c-1cf3-4d1a-acdc-70cb6e244ee4.png width=50% />
The Jupynium server will receive events from Neovim, keep the copy of the buffer and apply that to the Jupyter Notebook by using Selenium browser automation. It interacts only through the front end so it doesn't require installing extensions on the kernel etc., which makes it possible to:
- Develop locally, run remotely (or vice versa)
- Use university-hosted Jupyter Notebook
- Use any other languages / kernels such as R
## 🛠️ Installation
### Requirements
- 💻 Linux, macOS and Windows (CMD, PowerShell, WSL2)
- ✌️ Neovim >= v0.8
- 🦊 Firefox
- Other browsers are not supported due to their limitation with Selenium (see [#49](https://github.com/kiyoon/jupynium.nvim/issues/49#issuecomment-1443304753))
- 🦎 Mozilla geckodriver
- May already be installed with Firefox. Check `geckodriver -V`
- 🐍 Python >= 3.8
- Supported Python installation methods include system-level and [Conda](https://docs.conda.io/en/latest/miniconda.html)
- 📔 Jupyter Notebook >= 6.2
- Jupyter Lab is not supported
-
```sh
# jupyter-console is optional and used for `:JupyniumKernelOpenInTerminal`
pip install notebook nbclassic jupyter-console
```
#### Important note about Notebook 7 (breaking change!)
Jupynium does not support Notebook 7 yet. In the meantime, you can change the `default_notebook_URL = "localhost:8888/nbclassic"` in `require("jupynium").setup({ ... })` to use the classic (Notebook 6) interface with Jupynium. This is the new default setting from now on.
Don't forget to upgrade your notebook and install nbclassic (`pip install --upgrade notebook nbclassic`) when you set this.
### Install Python
Don't have system Python 3.8? You can use [Conda](https://docs.conda.io/en/latest/miniconda.html):
```bash
conda create -n jupynium python=3
conda activate jupynium
```
Upgrade pip. This solves many problems:
```bash
# pip >= 23.0 recommended
pip3 install --upgrade pip
```
### Install Jupynium
<details>
<summary>
Click to see vim-plug and packer installation.
</summary>
With vim-plug:
```vim
Plug 'kiyoon/jupynium.nvim', { 'do': 'pip3 install --user .' }
" Plug 'kiyoon/jupynium.nvim', { 'do': 'conda run --no-capture-output -n jupynium pip install .' }
Plug 'rcarriga/nvim-notify' " optional
Plug 'stevearc/dressing.nvim' " optional, UI for :JupyniumKernelSelect
```
With packer.nvim:
```lua
use { "kiyoon/jupynium.nvim", run = "pip3 install --user ." }
-- use { "kiyoon/jupynium.nvim", run = "conda run --no-capture-output -n jupynium pip install ." }
use { "rcarriga/nvim-notify" } -- optional
use { "stevearc/dressing.nvim" } -- optional, UI for :JupyniumKernelSelect
```
</details>
With 💤lazy.nvim:
```lua
{
"kiyoon/jupynium.nvim",
build = "pip3 install --user .",
-- build = "conda run --no-capture-output -n jupynium pip install .",
-- enabled = vim.fn.isdirectory(vim.fn.expand "~/miniconda3/envs/jupynium"),
},
"rcarriga/nvim-notify", -- optional
"stevearc/dressing.nvim", -- optional, UI for :JupyniumKernelSelect
```
#### Configure Jupynium
The default configuration values are below and work well for system-level Python users. If you're a Conda user, you need to change `python_host` to execute using the `conda` command instead.
<details>
<summary>
Click to see the setup defaults
</summary>
```lua
require("jupynium").setup({
--- For Conda environment named "jupynium",
-- python_host = { "conda", "run", "--no-capture-output", "-n", "jupynium", "python" },
python_host = vim.g.python3_host_prog or "python3",
default_notebook_URL = "localhost:8888/nbclassic",
-- Write jupyter command but without "notebook"
-- When you call :JupyniumStartAndAttachToServer and no notebook is open,
-- then Jupynium will open the server for you using this command. (only when notebook_URL is localhost)
jupyter_command = "jupyter",
--- For Conda, maybe use base environment
--- then you can `conda install -n base nb_conda_kernels` to switch environment in Jupyter Notebook
-- jupyter_command = { "conda", "run", "--no-capture-output", "-n", "base", "jupyter" },
-- Used when notebook is launched by using jupyter_command.
-- If nil or "", it will open at the git directory of the current buffer,
-- but still navigate to the directory of the current buffer. (e.g. localhost:8888/nbclassic/tree/path/to/buffer)
notebook_dir = nil,
-- Used to remember the last session (password etc.).
-- e.g. '~/.mozilla/firefox/profiles.ini'
-- or '~/snap/firefox/common/.mozilla/firefox/profiles.ini'
firefox_profiles_ini_path = nil,
-- nil means the profile with Default=1
-- or set to something like 'default-release'
firefox_profile_name = nil,
-- Open the Jupynium server if it is not already running
-- which means that it will open the Selenium browser when you open this file.
-- Related command :JupyniumStartAndAttachToServer
auto_start_server = {
enable = false,
file_pattern = { "*.ju.*" },
},
-- Attach current nvim to the Jupynium server
-- Without this step, you can't use :JupyniumStartSync
-- Related command :JupyniumAttachToServer
auto_attach_to_server = {
enable = true,
file_pattern = { "*.ju.*", "*.md" },
},
-- Automatically open an Untitled.ipynb file on Notebook
-- when you open a .ju.py file on nvim.
-- Related command :JupyniumStartSync
auto_start_sync = {
enable = false,
file_pattern = { "*.ju.*", "*.md" },
},
-- Automatically keep filename.ipynb copy of filename.ju.py
-- by downloading from the Jupyter Notebook server.
-- WARNING: this will overwrite the file without asking
-- Related command :JupyniumDownloadIpynb
auto_download_ipynb = true,
-- Automatically close tab that is in sync when you close buffer in vim.
auto_close_tab = true,
-- Always scroll to the current cell.
-- Related command :JupyniumScrollToCell
autoscroll = {
enable = true,
mode = "always", -- "always" or "invisible"
cell = {
top_margin_percent = 20,
},
},
scroll = {
page = { step = 0.5 },
cell = {
top_margin_percent = 20,
},
},
-- Files to be detected as a jupynium file.
-- Add highlighting, keybindings, commands (e.g. :JupyniumStartAndAttachToServer)
-- Modify this if you already have lots of files in Jupytext format, for example.
jupynium_file_pattern = { "*.ju.*" },
use_default_keybindings = true,
textobjects = {
use_default_keybindings = true,
},
syntax_highlight = {
enable = true,
},
-- Dim all cells except the current one
-- Related command :JupyniumShortsightedToggle
shortsighted = false,
-- Configure floating window options
-- Related command :JupyniumKernelHover
kernel_hover = {
floating_win_opts = {
max_width = 84,
border = "none",
},
},
notify = {
ignore = {
-- "download_ipynb",
-- "error_download_ipynb",
-- "attach_and_init",
-- "error_close_main_page",
-- "notebook_closed",
},
},
})
-- You can link highlighting groups.
-- This is the default (when colour scheme is unknown)
-- Try with CursorColumn, Pmenu, Folded etc.
vim.cmd [[
hi! link JupyniumCodeCellSeparator CursorLine
hi! link JupyniumMarkdownCellSeparator CursorLine
hi! link JupyniumMarkdownCellContent CursorLine
hi! link JupyniumMagicCommand Keyword
]]
-- Please share your favourite settings on other colour schemes, so I can add defaults.
-- Currently, tokyonight is supported.
```
</details>
#### Optionally, configure `nvim-cmp` to show Jupyter kernel completion
```lua
local cmp = require "cmp"
local compare = cmp.config.compare
cmp.setup {
sources = {
{ name = "jupynium", priority = 1000 }, -- consider higher priority than LSP
{ name = "nvim_lsp", priority = 100 },
-- ...
},
sorting = {
priority_weight = 1.0,
comparators = {
compare.score, -- Jupyter kernel completion shows prior to LSP
compare.recently_used,
compare.locality,
-- ...
},
},
}
```
#### Optionally, configure `nvim-ufo` to fold cells
There is an API serving as a folds provider, which will return a table with format `{startLine=#num, endLine=#num}`.
```lua
require("jupynium").get_folds()
```
You should use it with a fold plugin like [nvim-ufo](https://github.com/kevinhwang91/nvim-ufo).
See [#88](https://github.com/kiyoon/jupynium.nvim/pull/88) for more detail and an example configuration.
## 🏃 Quick Start
- Open a `*.ju.py` file.
- Execute `:JupyniumStartAndAttachToServer`. This will open Jupyter Notebook on the Firefox browser.
- If not, clarify option `jupyter_command` or just open the Notebook server by yourself: `jupyter notebook`
- Execute `:JupyniumStartSync`. This will create an `Untitled.ipynb` file on the browser.
- Now you can type `# %%` in Neovim to create a code cell.
- You'll see everything you type below that will be synchronised in the browser.
- Execute cells using the default keybind `<space>x`.
For detailed instructions, see Usage below.
## 🚦 Usage
There are 2 general steps to using Jupynium:
1. Setup a Jupynium file
2. Connect to the Jupynium server
The Jupynium server stays alive as long as the browser is alive. So you can see them as the same thing in this doc.
For example:
- Starting Jupynium server = opening a Selenium browser
- Manually closing the browser = closing the Jupynium server
### Setup a Jupynium file
Jupynium uses a Jupytext's percent format (see the `Jupynium file format` section below). This Jupytext file named `.ju.py` is what you will primarily be interacting with, rather than the `.ipynb` file directly. The contents of the Jupynium file are synced to the browser notebook where it can be viewed in real-time. If you want to keep a copy of the notebook, it can be downloaded as an `.ipynb` file later.
First, it's recommended to set a password on your notebook (rather than using tokens):
```console
$ jupyter notebook password
Enter password: 🔒
$ jupyter notebook # leave notebook opened
```
#### If you want to start a new notebook
1. Manually create a local Jupynium file called `<filename>.ju.py`
2. Done! The rest happens after connecting to the server
#### If you want to open an existing notebook
There are currently 2 ways of converting an existing `.ipynb` file to a Jupynium file:
**Option 1**: Use an included command line tool:
```bash
ipynb2jupytext [-h] [--stdout] [--code_only] file.ipynb [file.ju.py]
```
If you're already familiar with Jupytext, feel free to use it instead.
**Option 2**: This method requires that you have already connected to the Jupynium server:
1. Open your `.ipynb` file in the web browser after connecting to the server
2. In a new Neovim buffer, run `:JupyniumLoadFromIpynbTab`. This will convert the contents of the notebook file to Jupynium format.
3. Save your buffer as `<filename>.ju.py`
When using Jupynium for the first time, it's recommended to start a new notebook to make sure everything works before trying to load existing files.
### Connect to the Jupynium server
(This is for local Neovim only. For remote Neovim, see [Command-Line Usage](#%EF%B8%8F-command-line-usage-attach-to-remote-neovim))
In Neovim, with your Jupynium `.ju.py` file open, you can run `:JupyniumStartAndAttachToServer` to start the notebook server.
#### Sync current buffer to the Jupynium server
You need to be on the main notebook page (file browser) for the next few steps.
Although Neovim is now attached to the server, it won't automatically start syncing.
To sync your Neovim Jupynium file to a notebook, run `:JupyniumStartSync`.
You can also:
- `:JupyniumStartSync filename` to give a name to the notebook (`filename.ipynb`) instead of `Untitled.ipynb`. This does not open existing files. If a file with that name already exists then the filename argument will just be ignored.
- To sync a Jupynium file to an existing notebook, manually open the file in the browser, and `:JupyniumStartSync 2` to sync to the 2nd tab (count from 1).
At this point, any changes you make within the Neovim Jupynium file will be reflected live in the browser. Make sure you do not make changes inside the browser itself, as the sync is only one-way (from Neovim to browser).
If you want to save a copy of the `.ipynb` file, run `:JupyniumDownloadIpynb`. There is also a configuration option to enable automatic downloading.
#### Sync multiple Jupynium files
You can sync multiple files at the same time. Simple run `:JupyniumStartSync` again with the new file you want to sync.
#### Use multiple Neovim
You can run `:JupyniumStartSync` on a new Neovim instance.
If you have `auto_attach_to_server = false` during setup, you need to run `:JupyniumAttachToServer` and `:JupyniumStartSync`.
## 📝 Jupynium file format (.ju.py or .ju.\*)
The Jupynium file format follows Jupytext's percent format. In order for Jupynium to detect the files, name them as `*.ju.py` or specify `jupynium_file_pattern` in `require("jupynium").setup()`.
**Code cell:**
Any code below this line (and before the next separator) will be the content of a code cell.
- `# %%`
**Magic commands**
- `# %time` becomes `%time` in notebook.
- If you want to really comment out magic commands, comment it two times like `## %time`.
**Markdown cell:**
Any code below this line will be markdown cell content.
- `# %% [md]`
- `# %% [markdown]`
In Python, the recommended way is to wrap the whole cell content as a multi-line string.
```python
# %% [md]
"""
# This is a markdown heading
This is markdown content
"""
```
In other languages like R, you'll need to comment every line.
```r
# %% [md]
# # This is a markdown heading
# This is markdown content
```
**Explicitly specify the first cell separator to use it like a notebook.**
- If there is one or more cells, it works as a notebook mode.
- Contents before the first cell are ignored, so use it as a heading (shebang etc.)
- If there is no cell, it works as a markdown preview mode.
- It will still open ipynb file but will one have one markdown cell.
## ⌨️ Keybindings
- `<space>x`: Execute selected cells
- `<space>c`: Clear selected cells
- `<PageUp>`, `<PageDown>`: Scroll notebook
- `<space>js`: Scroll to cell (if autoscroll is disabled)
- `<space>K`: Hover (inspect a variable)
- `<space>jo`: Toggle output scroll (when output is long)
If you want custom keymaps, add `use_default_keybindings = false` and follow `M.default_keybindings()` in [lua/jupynium/init.lua](lua/jupynium/init.lua).
### Textobjects
- `[j`, `]j`: go to previous / next cell separator
- Repeat with `;` and `,` if you have [nvim-treesitter-textobjects](https://github.com/nvim-treesitter/nvim-treesitter-textobjects).
Follow their instructions for keybindings for this.
- `<space>jj`: go to current cell separator
- `vaj`,`vij`, `vaJ`, `viJ`: select current cell
- `a`: include separator, `i`: exclude separator
- `j`: exclude next separator, `J`: include next separator
If you want custom keymaps, add `textobjects = { use_default_keybindings = false }` and follow `M.default_keybindings()` in [lua/jupynium/textobj.lua](lua/jupynium/textobj.lua).
## 📡 Available Vim Commands
```vim
" Server (only used when Neovim is local. See Command-Line Usage for remote neovim)
:JupyniumStartAndAttachToServer [notebook_URL]
:JupyniumStartAndAttachToServerInTerminal [notebook_URL] " Useful for debugging
:JupyniumAttachToServer [notebook_URL]
" Sync
:JupyniumStartSync [filename / tab_index]
:JupyniumStopSync
:JupyniumLoadFromIpynbTab tab_index
:JupyniumLoadFromIpynbTabAndStartSync tab_index
" Notebook (while syncing)
:JupyniumSaveIpynb
:JupyniumDownloadIpynb [filename]
:JupyniumAutoDownloadIpynbToggle
:JupyniumScrollToCell
:JupyniumScrollUp
:JupyniumScrollDown
:JupyniumAutoscrollToggle
:JupyniumExecuteSelectedCells
:JupyniumClearSelectedCellsOutputs
:JupyniumToggleSelectedCellsOutputsScroll
:JupyniumKernelRestart
:JupyniumKernelInterrupt
:JupyniumKernelSelect
:JupyniumKernelHover " See value like LSP hover
:JupyniumKernelOpenInTerminal [hostname] " Connect to kernel of synchronized notebook
" Highlight
:JupyniumShortsightedToggle
```
## Lua API
The core API is provided as a global function.
```lua
--- Execute javascript in the browser. It will switch to the correct tab before executing.
---@param bufnr: integer | nil If given, before executing the code it will switch to the tab of this buffer. Requires syncing in advance.
---@param code string Javascript code
---@return boolean, object: Success, response
Jupynium_execute_javascript(bufnr, code)
```
Example: get kernel name and language
```lua
-- Use bufnr=nil if you don't want to switch tab
local code = [[return [Jupyter.notebook.kernel.name, Jupyter.kernelselector.kernelspecs];]]
local status_ok, kernel_name_and_spec = Jupynium_execute_javascript(0, code)
if status_ok then
local kernel_name = kernel_name_and_spec[1] -- "python3"
local kernel_spec = kernel_name_and_spec[2]
local kernel_language = kernel_spec[kernel_name].spec.language -- "python"
local kernel_display_name = kernel_spec[kernel_name].spec.display_name -- "Python 3 (ipykernel)"
end
```
## 👨💻️ Command-Line Usage (attach to remote Neovim)
**You don't need to install the vim plugin to use Jupynium.** The plugin is responsible of adding `:JupyniumStartAndAttachToServer` etc. that just calls the command line program, plus it has textobjects and shortsighted support.
Install Jupynium if you haven't already:
```bash
pip3 install jupynium
```
Open a python/markdown file with nvim and see `:echo v:servername`.
Run Jupynium like:
```bash
jupynium --nvim_listen_addr /tmp/your_socket_path
```
Or, you can run Neovim like
```bash
nvim --listen localhost:18898 notebook.ju.py
```
Then start Jupynium as well as attaching the neovim to it.
```bash
jupynium --nvim_listen_addr localhost:18898
```
Note that you can attach to remote neovim by changing `localhost` to `servername.com` or using SSH port forwarding.
This will open Firefox with Selenium, defaulting to `http://localhost:8888/nbclassic`.
Additionally,
- You can run `jupynium` command multiple times to attach more than one Neovim instance.
- `jupynium --notebook_URL localhost:18888` to view different notebook.
- You can just run `jupynium` without arguments to just leave the server / browser running and wait for nvim to attach.
## ⚠️ Caution
The program is in the alpha stage. If it crashes it's likely that the whole browser turns off without saving!
### Rules
1. Always leave the home page accessible. Jupynium interacts with it to open files. Do not close, or move to another website.
- It's okay to move between directories.
2. It's OK to close the notebook pages. If you do so, it will stop syncing that buffer.
3. Changing tab ordering or making it to a separate window is OK.
## 🤔 FAQ
> 🌽 How do I use different languages / kernels?
Instead of `*.ju.py` if you make files named `*.ju.*` (e.g. `*.ju.r`) you will see all the keybindings and commands.
All the procedures should be the same.
> The notebook content is not in sync with vim. How do I fix it?
You probably would have accidentally modified directly from the notebook.
1. If you want to keep the vim content and sync to the notebook, just <ins>add one more cell in the notebook and start making changes in vim</ins>. It works because Jupynium tries to only update the currently modified cell if the number of cells is the same in both. If it differs, it will fully update the entire content.
2. To keep the notebook content and load that to vim, run `:JupyniumLoadFromIpynbTab [tab_index]` without making changes on vim.
## 📰 Fun Facts
- I spent my whole Christmas and New Year holidays (and more) just making this plugin.
- This is the star history chart with relevant plugins. Thank you for helping it grow!
[](https://star-history.com/#kiyoon/jupynium.nvim&imbue-ai/jupyter_ascending&imbue-ai/jupyter_ascending.vim&dccsillag/magma-nvim&luk400/vim-jukit&Date)
Raw data
{
"_id": null,
"home_page": null,
"name": "jupynium",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "neovim, vim, jupyter, selenium, jupyter-notebook, nvim, neovim-plugin, nvim-plugin",
"author": "Kiyoon Kim",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/c5/fe/9fd3de4e6840f73e6bcb43fb1d55da8e17d773eebdf7681b3d94511391d9/jupynium-0.2.5.tar.gz",
"platform": null,
"description": "# Jupynium: Control Jupyter Notebook on Neovim with ZERO Compromise\n\n<a href=\"https://github.com/kiyoon/jupynium.nvim/actions/workflows/tests.yml\">\n<img src=\"https://github.com/kiyoon/jupynium.nvim/workflows/Tests/badge.svg?style=flat\" />\n</a>\n\n**It's just like a markdown live preview, but it's Jupyter Notebook live preview!**\n\nJupynium uses Selenium to automate Jupyter Notebook, synchronising everything you type on Neovim. \nNever leave Neovim. Switch tabs on the browser as you switch files on Neovim.\n\nNote that it doesn't sync from Notebook to Neovim so only modify from Neovim.\n\n<img src=https://user-images.githubusercontent.com/12980409/221559945-46f12a38-2fb8-4156-bb94-b87e831ac8f5.gif width=100% />\n\n## How does it work?\n\n<img src=https://user-images.githubusercontent.com/12980409/211933889-e31e844c-1cf3-4d1a-acdc-70cb6e244ee4.png width=50% />\n\nThe Jupynium server will receive events from Neovim, keep the copy of the buffer and apply that to the Jupyter Notebook by using Selenium browser automation. It interacts only through the front end so it doesn't require installing extensions on the kernel etc., which makes it possible to:\n\n- Develop locally, run remotely (or vice versa)\n- Use university-hosted Jupyter Notebook\n- Use any other languages / kernels such as R\n\n## \ud83d\udee0\ufe0f Installation\n\n### Requirements\n\n- \ud83d\udcbb Linux, macOS and Windows (CMD, PowerShell, WSL2)\n- \u270c\ufe0f Neovim >= v0.8\n- \ud83e\udd8a Firefox\n - Other browsers are not supported due to their limitation with Selenium (see [#49](https://github.com/kiyoon/jupynium.nvim/issues/49#issuecomment-1443304753))\n- \ud83e\udd8e Mozilla geckodriver\n - May already be installed with Firefox. Check `geckodriver -V`\n- \ud83d\udc0d Python >= 3.8\n - Supported Python installation methods include system-level and [Conda](https://docs.conda.io/en/latest/miniconda.html)\n- \ud83d\udcd4 Jupyter Notebook >= 6.2\n - Jupyter Lab is not supported\n - \n ```sh\n # jupyter-console is optional and used for `:JupyniumKernelOpenInTerminal`\n pip install notebook nbclassic jupyter-console\n ```\n\n#### Important note about Notebook 7 (breaking change!)\nJupynium does not support Notebook 7 yet. In the meantime, you can change the `default_notebook_URL = \"localhost:8888/nbclassic\"` in `require(\"jupynium\").setup({ ... })` to use the classic (Notebook 6) interface with Jupynium. This is the new default setting from now on.\n\nDon't forget to upgrade your notebook and install nbclassic (`pip install --upgrade notebook nbclassic`) when you set this.\n\n\n### Install Python\n\nDon't have system Python 3.8? You can use [Conda](https://docs.conda.io/en/latest/miniconda.html):\n\n```bash\nconda create -n jupynium python=3\nconda activate jupynium\n```\n\nUpgrade pip. This solves many problems:\n\n```bash\n# pip >= 23.0 recommended\npip3 install --upgrade pip\n```\n\n### Install Jupynium\n\n<details>\n<summary>\nClick to see vim-plug and packer installation.\n</summary>\n\nWith vim-plug:\n\n```vim\nPlug 'kiyoon/jupynium.nvim', { 'do': 'pip3 install --user .' }\n\" Plug 'kiyoon/jupynium.nvim', { 'do': 'conda run --no-capture-output -n jupynium pip install .' }\nPlug 'rcarriga/nvim-notify' \" optional\nPlug 'stevearc/dressing.nvim' \" optional, UI for :JupyniumKernelSelect\n```\n\nWith packer.nvim:\n\n```lua\nuse { \"kiyoon/jupynium.nvim\", run = \"pip3 install --user .\" }\n-- use { \"kiyoon/jupynium.nvim\", run = \"conda run --no-capture-output -n jupynium pip install .\" }\nuse { \"rcarriga/nvim-notify\" } -- optional\nuse { \"stevearc/dressing.nvim\" } -- optional, UI for :JupyniumKernelSelect\n```\n</details>\n\nWith \ud83d\udca4lazy.nvim:\n\n```lua\n {\n \"kiyoon/jupynium.nvim\",\n build = \"pip3 install --user .\",\n -- build = \"conda run --no-capture-output -n jupynium pip install .\",\n -- enabled = vim.fn.isdirectory(vim.fn.expand \"~/miniconda3/envs/jupynium\"),\n },\n \"rcarriga/nvim-notify\", -- optional\n \"stevearc/dressing.nvim\", -- optional, UI for :JupyniumKernelSelect\n```\n\n#### Configure Jupynium\n\nThe default configuration values are below and work well for system-level Python users. If you're a Conda user, you need to change `python_host` to execute using the `conda` command instead.\n\n<details>\n<summary>\nClick to see the setup defaults\n</summary>\n\n```lua\nrequire(\"jupynium\").setup({\n --- For Conda environment named \"jupynium\",\n -- python_host = { \"conda\", \"run\", \"--no-capture-output\", \"-n\", \"jupynium\", \"python\" },\n python_host = vim.g.python3_host_prog or \"python3\",\n\n default_notebook_URL = \"localhost:8888/nbclassic\",\n\n -- Write jupyter command but without \"notebook\"\n -- When you call :JupyniumStartAndAttachToServer and no notebook is open,\n -- then Jupynium will open the server for you using this command. (only when notebook_URL is localhost)\n jupyter_command = \"jupyter\",\n --- For Conda, maybe use base environment\n --- then you can `conda install -n base nb_conda_kernels` to switch environment in Jupyter Notebook\n -- jupyter_command = { \"conda\", \"run\", \"--no-capture-output\", \"-n\", \"base\", \"jupyter\" },\n\n -- Used when notebook is launched by using jupyter_command.\n -- If nil or \"\", it will open at the git directory of the current buffer,\n -- but still navigate to the directory of the current buffer. (e.g. localhost:8888/nbclassic/tree/path/to/buffer)\n notebook_dir = nil,\n\n -- Used to remember the last session (password etc.).\n -- e.g. '~/.mozilla/firefox/profiles.ini'\n -- or '~/snap/firefox/common/.mozilla/firefox/profiles.ini'\n firefox_profiles_ini_path = nil,\n -- nil means the profile with Default=1\n -- or set to something like 'default-release'\n firefox_profile_name = nil,\n\n -- Open the Jupynium server if it is not already running\n -- which means that it will open the Selenium browser when you open this file.\n -- Related command :JupyniumStartAndAttachToServer\n auto_start_server = {\n enable = false,\n file_pattern = { \"*.ju.*\" },\n },\n\n -- Attach current nvim to the Jupynium server\n -- Without this step, you can't use :JupyniumStartSync\n -- Related command :JupyniumAttachToServer\n auto_attach_to_server = {\n enable = true,\n file_pattern = { \"*.ju.*\", \"*.md\" },\n },\n\n -- Automatically open an Untitled.ipynb file on Notebook\n -- when you open a .ju.py file on nvim.\n -- Related command :JupyniumStartSync\n auto_start_sync = {\n enable = false,\n file_pattern = { \"*.ju.*\", \"*.md\" },\n },\n\n -- Automatically keep filename.ipynb copy of filename.ju.py\n -- by downloading from the Jupyter Notebook server.\n -- WARNING: this will overwrite the file without asking\n -- Related command :JupyniumDownloadIpynb\n auto_download_ipynb = true,\n\n -- Automatically close tab that is in sync when you close buffer in vim.\n auto_close_tab = true,\n\n -- Always scroll to the current cell.\n -- Related command :JupyniumScrollToCell\n autoscroll = {\n enable = true,\n mode = \"always\", -- \"always\" or \"invisible\"\n cell = {\n top_margin_percent = 20,\n },\n },\n\n scroll = {\n page = { step = 0.5 },\n cell = {\n top_margin_percent = 20,\n },\n },\n\n -- Files to be detected as a jupynium file.\n -- Add highlighting, keybindings, commands (e.g. :JupyniumStartAndAttachToServer)\n -- Modify this if you already have lots of files in Jupytext format, for example.\n jupynium_file_pattern = { \"*.ju.*\" },\n\n use_default_keybindings = true,\n textobjects = {\n use_default_keybindings = true,\n },\n\n syntax_highlight = {\n enable = true,\n },\n\n -- Dim all cells except the current one\n -- Related command :JupyniumShortsightedToggle\n shortsighted = false,\n\n -- Configure floating window options\n -- Related command :JupyniumKernelHover\n kernel_hover = {\n floating_win_opts = {\n max_width = 84,\n border = \"none\",\n },\n },\n\n notify = {\n ignore = {\n -- \"download_ipynb\",\n -- \"error_download_ipynb\",\n -- \"attach_and_init\",\n -- \"error_close_main_page\",\n -- \"notebook_closed\",\n },\n },\n})\n\n-- You can link highlighting groups.\n-- This is the default (when colour scheme is unknown)\n-- Try with CursorColumn, Pmenu, Folded etc.\nvim.cmd [[\nhi! link JupyniumCodeCellSeparator CursorLine\nhi! link JupyniumMarkdownCellSeparator CursorLine\nhi! link JupyniumMarkdownCellContent CursorLine\nhi! link JupyniumMagicCommand Keyword\n]]\n\n-- Please share your favourite settings on other colour schemes, so I can add defaults.\n-- Currently, tokyonight is supported.\n```\n\n</details>\n\n#### Optionally, configure `nvim-cmp` to show Jupyter kernel completion\n\n```lua\nlocal cmp = require \"cmp\"\nlocal compare = cmp.config.compare\n\ncmp.setup {\n sources = {\n { name = \"jupynium\", priority = 1000 }, -- consider higher priority than LSP\n { name = \"nvim_lsp\", priority = 100 },\n -- ...\n },\n sorting = {\n priority_weight = 1.0,\n comparators = {\n compare.score, -- Jupyter kernel completion shows prior to LSP\n compare.recently_used,\n compare.locality,\n -- ...\n },\n },\n}\n```\n\n#### Optionally, configure `nvim-ufo` to fold cells\n\nThere is an API serving as a folds provider, which will return a table with format `{startLine=#num, endLine=#num}`. \n\n```lua\nrequire(\"jupynium\").get_folds()\n```\n\nYou should use it with a fold plugin like [nvim-ufo](https://github.com/kevinhwang91/nvim-ufo). \nSee [#88](https://github.com/kiyoon/jupynium.nvim/pull/88) for more detail and an example configuration.\n\n## \ud83c\udfc3 Quick Start\n\n- Open a `*.ju.py` file.\n- Execute `:JupyniumStartAndAttachToServer`. This will open Jupyter Notebook on the Firefox browser.\n - If not, clarify option `jupyter_command` or just open the Notebook server by yourself: `jupyter notebook`\n- Execute `:JupyniumStartSync`. This will create an `Untitled.ipynb` file on the browser.\n- Now you can type `# %%` in Neovim to create a code cell.\n - You'll see everything you type below that will be synchronised in the browser.\n - Execute cells using the default keybind `<space>x`.\n\nFor detailed instructions, see Usage below.\n\n## \ud83d\udea6 Usage\n\nThere are 2 general steps to using Jupynium:\n\n1. Setup a Jupynium file\n2. Connect to the Jupynium server\n\nThe Jupynium server stays alive as long as the browser is alive. So you can see them as the same thing in this doc.\nFor example:\n\n- Starting Jupynium server = opening a Selenium browser\n- Manually closing the browser = closing the Jupynium server\n\n### Setup a Jupynium file\n\nJupynium uses a Jupytext's percent format (see the `Jupynium file format` section below). This Jupytext file named `.ju.py` is what you will primarily be interacting with, rather than the `.ipynb` file directly. The contents of the Jupynium file are synced to the browser notebook where it can be viewed in real-time. If you want to keep a copy of the notebook, it can be downloaded as an `.ipynb` file later.\n\nFirst, it's recommended to set a password on your notebook (rather than using tokens):\n\n```console\n$ jupyter notebook password\nEnter password: \ud83d\udd12\n\n$ jupyter notebook # leave notebook opened\n```\n\n#### If you want to start a new notebook\n\n1. Manually create a local Jupynium file called `<filename>.ju.py`\n2. Done! The rest happens after connecting to the server\n\n#### If you want to open an existing notebook\n\nThere are currently 2 ways of converting an existing `.ipynb` file to a Jupynium file:\n\n**Option 1**: Use an included command line tool:\n\n```bash\nipynb2jupytext [-h] [--stdout] [--code_only] file.ipynb [file.ju.py]\n```\n\nIf you're already familiar with Jupytext, feel free to use it instead.\n\n**Option 2**: This method requires that you have already connected to the Jupynium server:\n\n1. Open your `.ipynb` file in the web browser after connecting to the server\n2. In a new Neovim buffer, run `:JupyniumLoadFromIpynbTab`. This will convert the contents of the notebook file to Jupynium format.\n3. Save your buffer as `<filename>.ju.py`\n\nWhen using Jupynium for the first time, it's recommended to start a new notebook to make sure everything works before trying to load existing files.\n\n### Connect to the Jupynium server\n\n(This is for local Neovim only. For remote Neovim, see [Command-Line Usage](#%EF%B8%8F-command-line-usage-attach-to-remote-neovim))\n\nIn Neovim, with your Jupynium `.ju.py` file open, you can run `:JupyniumStartAndAttachToServer` to start the notebook server.\n\n#### Sync current buffer to the Jupynium server\n\nYou need to be on the main notebook page (file browser) for the next few steps.\n\nAlthough Neovim is now attached to the server, it won't automatically start syncing.\n\nTo sync your Neovim Jupynium file to a notebook, run `:JupyniumStartSync`.\n\nYou can also:\n\n- `:JupyniumStartSync filename` to give a name to the notebook (`filename.ipynb`) instead of `Untitled.ipynb`. This does not open existing files. If a file with that name already exists then the filename argument will just be ignored.\n- To sync a Jupynium file to an existing notebook, manually open the file in the browser, and `:JupyniumStartSync 2` to sync to the 2nd tab (count from 1).\n\nAt this point, any changes you make within the Neovim Jupynium file will be reflected live in the browser. Make sure you do not make changes inside the browser itself, as the sync is only one-way (from Neovim to browser).\n\nIf you want to save a copy of the `.ipynb` file, run `:JupyniumDownloadIpynb`. There is also a configuration option to enable automatic downloading.\n\n#### Sync multiple Jupynium files\n\nYou can sync multiple files at the same time. Simple run `:JupyniumStartSync` again with the new file you want to sync.\n\n#### Use multiple Neovim\n\nYou can run `:JupyniumStartSync` on a new Neovim instance. \nIf you have `auto_attach_to_server = false` during setup, you need to run `:JupyniumAttachToServer` and `:JupyniumStartSync`.\n\n## \ud83d\udcdd Jupynium file format (.ju.py or .ju.\\*)\n\nThe Jupynium file format follows Jupytext's percent format. In order for Jupynium to detect the files, name them as `*.ju.py` or specify `jupynium_file_pattern` in `require(\"jupynium\").setup()`.\n\n**Code cell:** \nAny code below this line (and before the next separator) will be the content of a code cell.\n\n- `# %%`\n\n**Magic commands**\n\n- `# %time` becomes `%time` in notebook.\n- If you want to really comment out magic commands, comment it two times like `## %time`.\n\n**Markdown cell:**\nAny code below this line will be markdown cell content.\n\n- `# %% [md]`\n- `# %% [markdown]`\n\nIn Python, the recommended way is to wrap the whole cell content as a multi-line string.\n\n```python\n# %% [md]\n\"\"\"\n# This is a markdown heading\nThis is markdown content\n\"\"\"\n```\n\nIn other languages like R, you'll need to comment every line.\n\n```r\n# %% [md]\n# # This is a markdown heading\n# This is markdown content\n```\n\n**Explicitly specify the first cell separator to use it like a notebook.**\n\n- If there is one or more cells, it works as a notebook mode.\n - Contents before the first cell are ignored, so use it as a heading (shebang etc.)\n- If there is no cell, it works as a markdown preview mode.\n - It will still open ipynb file but will one have one markdown cell.\n\n## \u2328\ufe0f Keybindings\n\n- `<space>x`: Execute selected cells\n- `<space>c`: Clear selected cells\n- `<PageUp>`, `<PageDown>`: Scroll notebook\n- `<space>js`: Scroll to cell (if autoscroll is disabled)\n- `<space>K`: Hover (inspect a variable)\n- `<space>jo`: Toggle output scroll (when output is long)\n\nIf you want custom keymaps, add `use_default_keybindings = false` and follow `M.default_keybindings()` in [lua/jupynium/init.lua](lua/jupynium/init.lua).\n\n### Textobjects\n\n- `[j`, `]j`: go to previous / next cell separator\n - Repeat with `;` and `,` if you have [nvim-treesitter-textobjects](https://github.com/nvim-treesitter/nvim-treesitter-textobjects).\n Follow their instructions for keybindings for this.\n- `<space>jj`: go to current cell separator\n- `vaj`,`vij`, `vaJ`, `viJ`: select current cell\n - `a`: include separator, `i`: exclude separator\n - `j`: exclude next separator, `J`: include next separator\n\nIf you want custom keymaps, add `textobjects = { use_default_keybindings = false }` and follow `M.default_keybindings()` in [lua/jupynium/textobj.lua](lua/jupynium/textobj.lua).\n\n## \ud83d\udce1 Available Vim Commands\n\n```vim\n\" Server (only used when Neovim is local. See Command-Line Usage for remote neovim)\n:JupyniumStartAndAttachToServer [notebook_URL]\n:JupyniumStartAndAttachToServerInTerminal [notebook_URL] \" Useful for debugging\n:JupyniumAttachToServer [notebook_URL]\n\n\" Sync\n:JupyniumStartSync [filename / tab_index]\n:JupyniumStopSync\n:JupyniumLoadFromIpynbTab tab_index\n:JupyniumLoadFromIpynbTabAndStartSync tab_index\n\n\" Notebook (while syncing)\n:JupyniumSaveIpynb\n:JupyniumDownloadIpynb [filename]\n:JupyniumAutoDownloadIpynbToggle\n\n:JupyniumScrollToCell\n:JupyniumScrollUp\n:JupyniumScrollDown\n:JupyniumAutoscrollToggle\n\n:JupyniumExecuteSelectedCells\n:JupyniumClearSelectedCellsOutputs\n:JupyniumToggleSelectedCellsOutputsScroll\n\n:JupyniumKernelRestart\n:JupyniumKernelInterrupt\n:JupyniumKernelSelect\n:JupyniumKernelHover \" See value like LSP hover\n:JupyniumKernelOpenInTerminal [hostname] \" Connect to kernel of synchronized notebook\n\n\" Highlight\n:JupyniumShortsightedToggle\n```\n\n## Lua API\n\nThe core API is provided as a global function.\n\n```lua\n--- Execute javascript in the browser. It will switch to the correct tab before executing.\n---@param bufnr: integer | nil If given, before executing the code it will switch to the tab of this buffer. Requires syncing in advance.\n---@param code string Javascript code\n---@return boolean, object: Success, response\nJupynium_execute_javascript(bufnr, code)\n```\n\nExample: get kernel name and language\n\n```lua\n-- Use bufnr=nil if you don't want to switch tab\nlocal code = [[return [Jupyter.notebook.kernel.name, Jupyter.kernelselector.kernelspecs];]]\nlocal status_ok, kernel_name_and_spec = Jupynium_execute_javascript(0, code)\nif status_ok then\n local kernel_name = kernel_name_and_spec[1] -- \"python3\"\n local kernel_spec = kernel_name_and_spec[2]\n local kernel_language = kernel_spec[kernel_name].spec.language -- \"python\"\n local kernel_display_name = kernel_spec[kernel_name].spec.display_name -- \"Python 3 (ipykernel)\"\nend\n```\n\n## \ud83d\udc68\u200d\ud83d\udcbb\ufe0f Command-Line Usage (attach to remote Neovim)\n\n**You don't need to install the vim plugin to use Jupynium.** The plugin is responsible of adding `:JupyniumStartAndAttachToServer` etc. that just calls the command line program, plus it has textobjects and shortsighted support.\n\nInstall Jupynium if you haven't already:\n\n```bash\npip3 install jupynium\n```\n\nOpen a python/markdown file with nvim and see `:echo v:servername`. \nRun Jupynium like:\n\n```bash\njupynium --nvim_listen_addr /tmp/your_socket_path\n```\n\nOr, you can run Neovim like\n\n```bash\nnvim --listen localhost:18898 notebook.ju.py\n```\n\nThen start Jupynium as well as attaching the neovim to it.\n\n```bash\njupynium --nvim_listen_addr localhost:18898\n```\n\nNote that you can attach to remote neovim by changing `localhost` to `servername.com` or using SSH port forwarding.\n\nThis will open Firefox with Selenium, defaulting to `http://localhost:8888/nbclassic`.\n\nAdditionally,\n\n- You can run `jupynium` command multiple times to attach more than one Neovim instance.\n- `jupynium --notebook_URL localhost:18888` to view different notebook.\n- You can just run `jupynium` without arguments to just leave the server / browser running and wait for nvim to attach.\n\n## \u26a0\ufe0f Caution\n\nThe program is in the alpha stage. If it crashes it's likely that the whole browser turns off without saving!\n\n### Rules\n\n1. Always leave the home page accessible. Jupynium interacts with it to open files. Do not close, or move to another website.\n\n- It's okay to move between directories.\n\n2. It's OK to close the notebook pages. If you do so, it will stop syncing that buffer.\n3. Changing tab ordering or making it to a separate window is OK.\n\n## \ud83e\udd14 FAQ\n\n> \ud83c\udf3d How do I use different languages / kernels?\n\nInstead of `*.ju.py` if you make files named `*.ju.*` (e.g. `*.ju.r`) you will see all the keybindings and commands. \nAll the procedures should be the same.\n\n> The notebook content is not in sync with vim. How do I fix it?\n\nYou probably would have accidentally modified directly from the notebook.\n\n1. If you want to keep the vim content and sync to the notebook, just <ins>add one more cell in the notebook and start making changes in vim</ins>. It works because Jupynium tries to only update the currently modified cell if the number of cells is the same in both. If it differs, it will fully update the entire content.\n2. To keep the notebook content and load that to vim, run `:JupyniumLoadFromIpynbTab [tab_index]` without making changes on vim.\n\n## \ud83d\udcf0 Fun Facts\n\n- I spent my whole Christmas and New Year holidays (and more) just making this plugin.\n- This is the star history chart with relevant plugins. Thank you for helping it grow!\n\n[](https://star-history.com/#kiyoon/jupynium.nvim&imbue-ai/jupyter_ascending&imbue-ai/jupyter_ascending.vim&dccsillag/magma-nvim&luk400/vim-jukit&Date)\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2023 Kiyoon Kim Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Neovim plugin that automates Jupyter Notebook editing/browsing using Selenium.",
"version": "0.2.5",
"project_urls": {
"Homepage": "https://github.com/kiyoon/jupynium.nvim"
},
"split_keywords": [
"neovim",
" vim",
" jupyter",
" selenium",
" jupyter-notebook",
" nvim",
" neovim-plugin",
" nvim-plugin"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c5fe9fd3de4e6840f73e6bcb43fb1d55da8e17d773eebdf7681b3d94511391d9",
"md5": "bfd5b7257acce5861ae77529b28a20ca",
"sha256": "bffea7350c53bea7afdbdd8b6d181e8e7dee150734f94939182cabc974a52567"
},
"downloads": -1,
"filename": "jupynium-0.2.5.tar.gz",
"has_sig": false,
"md5_digest": "bfd5b7257acce5861ae77529b28a20ca",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 74747,
"upload_time": "2024-11-14T13:18:43",
"upload_time_iso_8601": "2024-11-14T13:18:43.926612Z",
"url": "https://files.pythonhosted.org/packages/c5/fe/9fd3de4e6840f73e6bcb43fb1d55da8e17d773eebdf7681b3d94511391d9/jupynium-0.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-14 13:18:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kiyoon",
"github_project": "jupynium.nvim",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "jupynium"
}
