# poetry-jupyter-plugin
## overview
This is a really simple plugin to allow you to install your
[Poetry](https://python-poetry.org) virtual environment as a
[Jupyter](https://jupyter.org) kernel. You may wish to do this to keep your
dependencies locked down for reproducible notebooks, or to set up a single
"data science" notebook for one-off calculations without fiddling about with
installing packages globally or dealing with `ipykernel` directly.
## getting started
Install the plugin with:
```sh
$ poetry self add poetry-jupyter-plugin
```
Then, from within your poetry project:
```sh
$ poetry install ipykernel -G dev
$ poetry jupyter install
```
Remove the kernelspec with:
```sh
$ poetry jupyter remove
```
### configuration
By default, the installed kernel will use the name of the project and a default
Poetry icon. To configure these options, add this block to your `pyproject.toml`:
```toml
[tool.jupyter.kernel]
name = "my-cool-kernel"
display = "My cool kernel"
icon = "/path/to/icon.png"
```
## prior art
There are other projects in this space, notably Pathbird's [`poetry-kernel`].
`poetry-kernel` installs a single kernelspec globally which then patches the
virtualenv based on the specific project folder that you're running Jupyter in.
This has some pros and cons over this project.
Pros:
1. Single kernelspec, avoiding polluting the kernelspec list with lots of specs.
2. Easy context switching between projects.
Cons:
1. Notebooks have to be in the same folder (or a subfolder from) as the
`pyproject.toml` folder.
2. Requires forwarding signals from the launcher into Jupyter, introducing a
layer of complexity and is brittle to changes in Jupyter protocol/underlying
OS.
3. Implicit dependency on `ipykernel`, and may fail to start without it.
In contrast, this project installs one kernelspec per virtualenv and leaves it
up to Jupyter to launch the kernel normally without interception. This design
decision also allows multiple projects to be based out of one kernel.
Additionally, the tool checks for the existence of `ipykernel` to make sure
that the kernel can be installed properly.
## who?
This was written by [patrick kage](//ka.ge).
Raw data
{
"_id": null,
"home_page": "https://github.com/pkage/poetry-jupyter-plugin",
"name": "poetry-jupyter-plugin",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"keywords": "poetry,poetry-plugin,plugin,jupyter,jupyter-kernel",
"author": "Patrick Kage",
"author_email": "patrick.r.kage@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/ec/47/56208e225481b00394f28c0a1a967a0c3fa870fdc6f953ae082ef6ad280c/poetry_jupyter_plugin-0.1.4.tar.gz",
"platform": null,
"description": "# poetry-jupyter-plugin\n\n## overview\n\nThis is a really simple plugin to allow you to install your\n[Poetry](https://python-poetry.org) virtual environment as a\n[Jupyter](https://jupyter.org) kernel. You may wish to do this to keep your\ndependencies locked down for reproducible notebooks, or to set up a single\n\"data science\" notebook for one-off calculations without fiddling about with\ninstalling packages globally or dealing with `ipykernel` directly.\n\n## getting started\n\nInstall the plugin with:\n\n```sh\n$ poetry self add poetry-jupyter-plugin\n```\n\nThen, from within your poetry project:\n\n```sh\n$ poetry install ipykernel -G dev\n$ poetry jupyter install\n```\n\nRemove the kernelspec with:\n\n```sh\n$ poetry jupyter remove\n```\n\n### configuration\n\nBy default, the installed kernel will use the name of the project and a default\nPoetry icon. To configure these options, add this block to your `pyproject.toml`:\n\n```toml\n[tool.jupyter.kernel]\nname = \"my-cool-kernel\"\ndisplay = \"My cool kernel\"\nicon = \"/path/to/icon.png\"\n```\n\n## prior art\n\nThere are other projects in this space, notably Pathbird's [`poetry-kernel`].\n`poetry-kernel` installs a single kernelspec globally which then patches the\nvirtualenv based on the specific project folder that you're running Jupyter in.\nThis has some pros and cons over this project.\n\nPros:\n\n1. Single kernelspec, avoiding polluting the kernelspec list with lots of specs.\n2. Easy context switching between projects.\n\nCons:\n\n1. Notebooks have to be in the same folder (or a subfolder from) as the\n `pyproject.toml` folder.\n2. Requires forwarding signals from the launcher into Jupyter, introducing a\n layer of complexity and is brittle to changes in Jupyter protocol/underlying\n OS.\n3. Implicit dependency on `ipykernel`, and may fail to start without it.\n\nIn contrast, this project installs one kernelspec per virtualenv and leaves it\nup to Jupyter to launch the kernel normally without interception. This design\ndecision also allows multiple projects to be based out of one kernel.\nAdditionally, the tool checks for the existence of `ipykernel` to make sure\nthat the kernel can be installed properly.\n\n## who?\n\nThis was written by [patrick kage](//ka.ge).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Poetry plugin to manage Jupyter kernels",
"version": "0.1.4",
"project_urls": {
"Homepage": "https://github.com/pkage/poetry-jupyter-plugin",
"Repository": "https://github.com/pkage/poetry-jupyter-plugin"
},
"split_keywords": [
"poetry",
"poetry-plugin",
"plugin",
"jupyter",
"jupyter-kernel"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f099eb4fe4b465388f6874811baba2f1066991be51fe206e878547df667d7704",
"md5": "1d1f45c53bc0e4878192bb135b85f3e6",
"sha256": "0a13d501ef81b9958ebcfffc8b7ee971f5e18d1dadc940e90a10e046636191c7"
},
"downloads": -1,
"filename": "poetry_jupyter_plugin-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1d1f45c53bc0e4878192bb135b85f3e6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 118875,
"upload_time": "2023-07-03T20:39:59",
"upload_time_iso_8601": "2023-07-03T20:39:59.633481Z",
"url": "https://files.pythonhosted.org/packages/f0/99/eb4fe4b465388f6874811baba2f1066991be51fe206e878547df667d7704/poetry_jupyter_plugin-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ec4756208e225481b00394f28c0a1a967a0c3fa870fdc6f953ae082ef6ad280c",
"md5": "9991654cde5c15fd6a7c9f7340705e2f",
"sha256": "0f5148c45903e69aa848e3c1a776fbd3615743b175006bdf1ee5a634668743bc"
},
"downloads": -1,
"filename": "poetry_jupyter_plugin-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "9991654cde5c15fd6a7c9f7340705e2f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 119847,
"upload_time": "2023-07-03T20:40:02",
"upload_time_iso_8601": "2023-07-03T20:40:02.131666Z",
"url": "https://files.pythonhosted.org/packages/ec/47/56208e225481b00394f28c0a1a967a0c3fa870fdc6f953ae082ef6ad280c/poetry_jupyter_plugin-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-03 20:40:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pkage",
"github_project": "poetry-jupyter-plugin",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "poetry-jupyter-plugin"
}
JSON
