| Name | pyproject-local-kernel JSON |
| Version |
0.12.1
JSON |
| download |
| home_page | None |
| Summary | Python Jupyter kernel using project/environment manangers like Rye, Uv, PDM, Poetry, Hatch etc. |
| upload_time | 2024-10-24 22:24:48 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | # LICENSE Copyright 2023-2024 Ulrik Sverdrup "bluss" 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 |
interactive
interpreter
jupyter
pyproject
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Pyproject Local Jupyter Kernel
<p class="web_hidden">
[Website][] - [PyPI][] [][PyPi]
</p>
Separate dependencies for Jupyter notebooks - each notebook
project can have its own dependencies!
[Website]: https://bluss.github.io/pyproject-local-kernel/
[PyPi]: https://pypi.org/project/pyproject-local-kernel/
Instead of installing a myriad of Jupyter kernelspecs, one per project, with
this solution there is only one [kernel provisioner][kp] that enables the
environment for the project the notebook file resides in. This approach should
be more portable, usable to anyone who checks out your project structure from
git, and easier to use.
Pyproject Local supports **Uv, Poetry, Hatch, Rye, and PDM**
and reads `pyproject.toml` to figure out which kind of project it is.
Or it can use a custom command or a bare virtual environment directly.
[kp]: https://jupyter-client.readthedocs.io/en/latest/provisioning.html
## Quick Start (JupyterLab)
1. Install pyproject-local-kernel in your Jupyterlab environment and restart
Jupyterlab
2. Create a new directory for the notebook project
3. Create a new notebook and select the **Pyproject Local** kernel
4. In the *“fallback”* environment that appears - because it is an empty
project - create a new project.
(Example for Uv:)
`!uv init && uv add ipykernel`
5. Use the restart button in JupyterLab to restart the kernel after these changes.
6. Dependencies will quickly sync and you are good to go!
7. Use more `add` commands to add further dependencies.
See the examples directory for how to setup Jupyterlab and notebook projects
separately. JupyterLab and the notebook are installed in separate environments.
Do you want to use pyproject-local-kernel in other environments, like with
papermill, **VSCodium or VS Code**, or or other ways? See our [FAQ][] for more
information.
[FAQ]: FAQ.md
## User Experience
If started in an empty directory or where a project is not correctly set up,
the Pyproject Local will fail to start normally, but it will start a fallback
kernel so that you can fix the project.
It will show a message like this - with some details about the error.
```diff
! Error: Could not find `ipykernel` in environment.
! Add `ipykernel` as a dependency in your project and update the virtual environment.
! The detected project type is: Unknown
!
! This is a fallback - pyproject-local-kernel failed to start.
! The purpose of the fallback is to let you run shell commands to fix the
! environment - when you are done, restart the kernel and try again!
```
Remember that you can also use Jupyterlab's embedded terminal to help setting
up a project.
***If `pyproject.toml` is Missing***
If the Pyproject Local kernel is selected in a project where there is no `pyproject.toml`,
then starting the kernel fails. On first run it should show an error message in JupyterLab.
If this happens, create a new `pyproject.toml` with the editor or use
one of the project init commands to create a new project.
***If the `ipykernel` is Missing***
The notebook project needs to install `ipykernel` as a dependency.
Edit the `pyproject.toml` to include `ipykernel` in dependencies:
```toml
dependencies = [
"ipykernel>=6.29",
# .. more dependencies
]
```
sync the changes to the project using sync command for the project
manager you use, then restart the Pyproject local kernel in Jupyterlab.
## Configuration
Configuration is optional and is read from `pyproject.toml`. Only the
`pyproject.toml` closest to the notebook is read. Defaults are based on
“sniffing” the `pyproject.toml` to detect which project manager is in use.
### `python-cmd`
The key `tool.pyproject-local-kernel.python-cmd` should be a command that runs
python from the environment you want to use for the project.
If this is set then it overrides the default command. There is further
explanation in [the FAQ](FAQ.md#how-does-the-python-cmd-configuration-work).
**Default:** *Depends on project manager*<br>
**Type:** `list[str] | str`<br>
**Example:**
```toml
[tool.pyproject-local-kernel]
python-cmd = ["uv", "run", "--with", "ipykernel", "python"]
```
### `use-venv`
Path to virtual environment that should be used, relative to the
`pyproject.toml` file. Can also be an absolute path.
If this is set then it overrides the default command - the virtualenv is used
directly without invoking any project manager. Remember to explicitly install
or sync required dependencies.
**Default:** Not set<br>
**Type:** `str`<br>
**Example:**
```toml
[tool.pyproject-local-kernel]
use-venv = ".venv"
```
### `sanity-check`
If `true`, then run a check for `ipykernel` being installed in the project
before starting the kernel process.
**Default:** true<br>
**Type:** `bool`<br>
**Example:**
```toml
[tool.pyproject-local-kernel]
sanity-check = true
```
### `PyprojectKernelProvisioner`
The kernel provisioner is configurable in the same way as other Jupyter
objects, with the following settings. They can be set in your
`jupyter_lab_config.py` settings file.
When possible, prefer to use settings in `pyproject.toml` instead, to keep them
close to the project.
```python
#------------------------------------------------------------------------------
# PyprojectKernelProvisioner(LocalProvisioner) configuration
#------------------------------------------------------------------------------
## Enable sanity check for 'ipykernel' package in environment
# Default: True
# c.PyprojectKernelProvisioner.sanity_check = True
## Default setting for use-venv for projects using the 'use-venv' kernel
# Default: '.venv'
# c.PyprojectKernelProvisioner.use_venv = '.venv'
```
## About Particular Project Managers
The project manager command, be it rye, uv, pdm, etc needs to be
available on the path where Jupyterlab runs. Either install the project
manager in the Jupyterlab environment, or install the project manager
user-wide (using something like pipx, uv tool, rye tools, brew, or
other method to install it.)
***Uv***
- Uv is detected if the pyproject.toml contains `tool.uv`. It is also the
default fallback if no project manager is detected from a pyproject file.
- The command used is `uv run --with ipykernel python` which means that it ensures
`ipykernel` is used even if it's not already in the project(!). However, note that
it uses an [ephemeral virtual environment][eph] for ipykernel in that case.
Add ipykernel to the project to avoid this.
[eph]: https://docs.astral.sh/uv/reference/cli/
***Rye***
- Rye is detected if the pyproject.toml contains `tool.rye.managed = true`
which Rye sets by default for its new projects.
***PDM***
- PDM is detected if pyproject.toml contains `tool.pdm`
***Hatch***
- Hatch is detected if pyproject.toml contains `tool.hatch.envs`
- By default it calls out to `hatch env find`, to find the default virtualenv,
and runs from there. `hatch run` should not be used directly because
it's not compatible with how kernel interrupts work (as of this writing).
- It's best to create the hatch project, add ipykernel as dependency and sync
dependencies in a terminal before starting (it does not work so well with
shell commands in a notebook).
***Poetry***
- Poetry is detected if pyproject.toml contains `tool.poetry.name`
- Some commands are interactive by default and don't work in a notebook,
but they have an `-n` switch to make them non-interactive.
## Project Status
Additional interest and maintainer help is welcomed.
## Links
* <https://github.com/astral-sh/uv>
* <https://github.com/renan-r-santos/pixi-kernel>
* <https://github.com/goerz/python-localvenv-kernel>
* <https://github.com/pathbird/poetry-kernel>
## License
`pyproject-local-kernel` is open source. See the LICENSE.md file in the source
distribution for more information.
Raw data
{
"_id": null,
"home_page": null,
"name": "pyproject-local-kernel",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "Interactive, Interpreter, Jupyter, Pyproject",
"author": null,
"author_email": "Ulrik Sverdrup <ulrik.sverdrup@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/40/fb/94358922dd72d940b1a10e6cdcb11b97d9f39f9212717b8cce32f7f00a15/pyproject_local_kernel-0.12.1.tar.gz",
"platform": null,
"description": "\n# Pyproject Local Jupyter Kernel\n\n<p class=\"web_hidden\">\n\n[Website][] - [PyPI][] [][PyPi]\n\n</p>\n\nSeparate dependencies for Jupyter notebooks - each notebook\nproject can have its own dependencies!\n\n[Website]: https://bluss.github.io/pyproject-local-kernel/\n[PyPi]: https://pypi.org/project/pyproject-local-kernel/\n\nInstead of installing a myriad of Jupyter kernelspecs, one per project, with\nthis solution there is only one [kernel provisioner][kp] that enables the\nenvironment for the project the notebook file resides in. This approach should\nbe more portable, usable to anyone who checks out your project structure from\ngit, and easier to use.\n\nPyproject Local supports **Uv, Poetry, Hatch, Rye, and PDM**\nand reads `pyproject.toml` to figure out which kind of project it is.\nOr it can use a custom command or a bare virtual environment directly.\n\n[kp]: https://jupyter-client.readthedocs.io/en/latest/provisioning.html\n\n\n\n## Quick Start (JupyterLab)\n\n1. Install pyproject-local-kernel in your Jupyterlab environment and restart\n Jupyterlab\n2. Create a new directory for the notebook project\n3. Create a new notebook and select the **Pyproject Local** kernel\n4. In the *\u201cfallback\u201d* environment that appears - because it is an empty\n project - create a new project.\n\n (Example for Uv:)\n\n `!uv init && uv add ipykernel`\n\n5. Use the restart button in JupyterLab to restart the kernel after these changes.\n6. Dependencies will quickly sync and you are good to go!\n7. Use more `add` commands to add further dependencies.\n\n\nSee the examples directory for how to setup Jupyterlab and notebook projects\nseparately. JupyterLab and the notebook are installed in separate environments.\n\n\nDo you want to use pyproject-local-kernel in other environments, like with\npapermill, **VSCodium or VS Code**, or or other ways? See our [FAQ][] for more\ninformation.\n\n[FAQ]: FAQ.md\n\n## User Experience\n\nIf started in an empty directory or where a project is not correctly set up,\nthe Pyproject Local will fail to start normally, but it will start a fallback\nkernel so that you can fix the project.\n\nIt will show a message like this - with some details about the error.\n\n```diff\n! Error: Could not find `ipykernel` in environment.\n! Add `ipykernel` as a dependency in your project and update the virtual environment.\n! The detected project type is: Unknown\n!\n! This is a fallback - pyproject-local-kernel failed to start.\n! The purpose of the fallback is to let you run shell commands to fix the\n! environment - when you are done, restart the kernel and try again!\n```\n\nRemember that you can also use Jupyterlab's embedded terminal to help setting\nup a project.\n\n***If `pyproject.toml` is Missing***\n\nIf the Pyproject Local kernel is selected in a project where there is no `pyproject.toml`,\nthen starting the kernel fails. On first run it should show an error message in JupyterLab.\n\nIf this happens, create a new `pyproject.toml` with the editor or use\none of the project init commands to create a new project.\n\n***If the `ipykernel` is Missing***\n\nThe notebook project needs to install `ipykernel` as a dependency.\n\nEdit the `pyproject.toml` to include `ipykernel` in dependencies:\n\n```toml\ndependencies = [\n \"ipykernel>=6.29\",\n # .. more dependencies\n]\n```\n\nsync the changes to the project using sync command for the project\nmanager you use, then restart the Pyproject local kernel in Jupyterlab.\n\n## Configuration\n\nConfiguration is optional and is read from `pyproject.toml`. Only the\n`pyproject.toml` closest to the notebook is read. Defaults are based on\n\u201csniffing\u201d the `pyproject.toml` to detect which project manager is in use.\n\n### `python-cmd`\n\nThe key `tool.pyproject-local-kernel.python-cmd` should be a command that runs\npython from the environment you want to use for the project.\n\nIf this is set then it overrides the default command. There is further\nexplanation in [the FAQ](FAQ.md#how-does-the-python-cmd-configuration-work).\n\n**Default:** *Depends on project manager*<br>\n**Type:** `list[str] | str`<br>\n**Example:**\n\n```toml\n[tool.pyproject-local-kernel]\npython-cmd = [\"uv\", \"run\", \"--with\", \"ipykernel\", \"python\"]\n```\n\n### `use-venv`\n\nPath to virtual environment that should be used, relative to the\n`pyproject.toml` file. Can also be an absolute path.\n\nIf this is set then it overrides the default command - the virtualenv is used\ndirectly without invoking any project manager. Remember to explicitly install\nor sync required dependencies.\n\n**Default:** Not set<br>\n**Type:** `str`<br>\n**Example:**\n\n```toml\n[tool.pyproject-local-kernel]\nuse-venv = \".venv\"\n```\n\n### `sanity-check`\n\nIf `true`, then run a check for `ipykernel` being installed in the project\nbefore starting the kernel process.\n\n**Default:** true<br>\n**Type:** `bool`<br>\n**Example:**\n\n```toml\n[tool.pyproject-local-kernel]\nsanity-check = true\n```\n\n\n### `PyprojectKernelProvisioner`\n\nThe kernel provisioner is configurable in the same way as other Jupyter\nobjects, with the following settings. They can be set in your\n`jupyter_lab_config.py` settings file.\nWhen possible, prefer to use settings in `pyproject.toml` instead, to keep them\nclose to the project.\n\n```python\n#------------------------------------------------------------------------------\n# PyprojectKernelProvisioner(LocalProvisioner) configuration\n#------------------------------------------------------------------------------\n## Enable sanity check for 'ipykernel' package in environment\n# Default: True\n# c.PyprojectKernelProvisioner.sanity_check = True\n\n## Default setting for use-venv for projects using the 'use-venv' kernel\n# Default: '.venv'\n# c.PyprojectKernelProvisioner.use_venv = '.venv'\n```\n\n\n## About Particular Project Managers\n\nThe project manager command, be it rye, uv, pdm, etc needs to be\navailable on the path where Jupyterlab runs. Either install the project\nmanager in the Jupyterlab environment, or install the project manager\nuser-wide (using something like pipx, uv tool, rye tools, brew, or\nother method to install it.)\n\n***Uv***\n\n- Uv is detected if the pyproject.toml contains `tool.uv`. It is also the\n default fallback if no project manager is detected from a pyproject file.\n\n- The command used is `uv run --with ipykernel python` which means that it ensures\n `ipykernel` is used even if it's not already in the project(!). However, note that\n it uses an [ephemeral virtual environment][eph] for ipykernel in that case.\n Add ipykernel to the project to avoid this.\n\n[eph]: https://docs.astral.sh/uv/reference/cli/\n\n***Rye***\n\n- Rye is detected if the pyproject.toml contains `tool.rye.managed = true`\n which Rye sets by default for its new projects.\n\n***PDM***\n\n- PDM is detected if pyproject.toml contains `tool.pdm`\n\n***Hatch***\n\n- Hatch is detected if pyproject.toml contains `tool.hatch.envs`\n\n- By default it calls out to `hatch env find`, to find the default virtualenv,\n and runs from there. `hatch run` should not be used directly because\n it's not compatible with how kernel interrupts work (as of this writing).\n\n- It's best to create the hatch project, add ipykernel as dependency and sync\n dependencies in a terminal before starting (it does not work so well with\n shell commands in a notebook).\n\n***Poetry***\n\n- Poetry is detected if pyproject.toml contains `tool.poetry.name`\n\n- Some commands are interactive by default and don't work in a notebook,\n but they have an `-n` switch to make them non-interactive.\n\n## Project Status\n\nAdditional interest and maintainer help is welcomed.\n\n## Links\n\n* <https://github.com/astral-sh/uv>\n* <https://github.com/renan-r-santos/pixi-kernel>\n* <https://github.com/goerz/python-localvenv-kernel>\n* <https://github.com/pathbird/poetry-kernel>\n\n## License\n\n`pyproject-local-kernel` is open source. See the LICENSE.md file in the source\ndistribution for more information.\n",
"bugtrack_url": null,
"license": "# LICENSE Copyright 2023-2024 Ulrik Sverdrup \"bluss\" 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": "Python Jupyter kernel using project/environment manangers like Rye, Uv, PDM, Poetry, Hatch etc.",
"version": "0.12.1",
"project_urls": {
"Homepage": "https://bluss.github.io/pyproject-local-kernel/",
"Repository": "https://github.com/bluss/pyproject-local-kernel"
},
"split_keywords": [
"interactive",
" interpreter",
" jupyter",
" pyproject"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a717f2b6d2c93896d19bfe53bea78a23bf65e5b8f36890dd2dc4d9fc56d49e60",
"md5": "b21975e41d1dd7ecaab3af259ab73803",
"sha256": "ed788fa70864c4635ff65a4414739cc247a7908a9d9b3543e705514d1b98dce2"
},
"downloads": -1,
"filename": "pyproject_local_kernel-0.12.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b21975e41d1dd7ecaab3af259ab73803",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 19236,
"upload_time": "2024-10-24T22:24:46",
"upload_time_iso_8601": "2024-10-24T22:24:46.911076Z",
"url": "https://files.pythonhosted.org/packages/a7/17/f2b6d2c93896d19bfe53bea78a23bf65e5b8f36890dd2dc4d9fc56d49e60/pyproject_local_kernel-0.12.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "40fb94358922dd72d940b1a10e6cdcb11b97d9f39f9212717b8cce32f7f00a15",
"md5": "3abc4fd05b5a51c93b5a91f8e736419d",
"sha256": "a983a370a4c8b29acfbcc4ccda22d13215c97f24e2b51d980830fa7d5d37fcc5"
},
"downloads": -1,
"filename": "pyproject_local_kernel-0.12.1.tar.gz",
"has_sig": false,
"md5_digest": "3abc4fd05b5a51c93b5a91f8e736419d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 331109,
"upload_time": "2024-10-24T22:24:48",
"upload_time_iso_8601": "2024-10-24T22:24:48.373970Z",
"url": "https://files.pythonhosted.org/packages/40/fb/94358922dd72d940b1a10e6cdcb11b97d9f39f9212717b8cce32f7f00a15/pyproject_local_kernel-0.12.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-24 22:24:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bluss",
"github_project": "pyproject-local-kernel",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pyproject-local-kernel"
}
