Poetry Kernel
Use per-directory Poetry environments to run Jupyter kernels. No need to install a Jupyter kernel per Python virtual environment!
The idea behind this project is to allow you to capture the exact state of your environment. This means you can email your work to your peers, and they'll have exactly the same set of packages that you do! Reproducibility!
Why not virtual environments (venvs)?
Virtual environments were (and are) an important advancement to Python's package management story, but they have a few shortcomings:
- They are not great for reproducibility. Usually, you'll create a new virtual environment using a
requirements.txtwhich includes all the direct dependencies (numpy, pandas, etc.), but not transient dependencies (pandas depends on pytz for timezone support, for example). And usually, even the direct dependencies are specified only as minimum (or semver) ranges (e.g.,numpy>=1.21) which can make it hard or impossible to accurately recreate thevenvlater. - With Jupyter, they usually require that the kernels be installed globally. This means you'll need need to have a separate kernelspec for every venv you want to use with Jupyter.
Poetry uses venvs transparently under the hood by constructing them from the pyproject.toml and poetry.lock files. The poetry.lock file records the exact state of dependencies (and transient dependencies) and can be used to more accurately reproduce the environment.
Additionally, Poetry Kernel means you only have to install one kernelspec. It then uses the pyproject.toml file from the directory of the notebook (or any parent directory) to choose which environment to run the notebook in.
Shameless plug
The reason we created this package was to make sure that the code environments created for running student code on Pathbird exactly match your development environment. Interested in developing interactive, engaging, inquiry-based lessons for your students? Check out Pathbird for more information!
Usage
- Install Poetry if not yet installed.
- Install this package:
# NOTE: Do **NOT** install this package in your Poetry project, it should be # installed at the system or user level. pip3 install --user poetry-kernel
- Initialize a Poetry project (only required if you do not have an existing Poetry project ready to use):
poetry init -n
- IMPORTANT: Add
ipykernelto your project's dependencies:# In the directory of your Poetry project poetry add ipykernel - Start a "Poetry" Jupyter kernel and see it in action!
Troubleshooting
Kernel isn't starting ("No Kernel" message)
Pro-tip: Check the output of the terminal window where you launched Jupyter. It will usually explain why the kernel is failing to start.
- Make sure that you are launching a notebook in a directory/folder that contains a Poetry project (
pyproject.tomlandpoetry.lockfiles). You can turn a directory into a Poetry project by running:
poetry init -n
- Make sure that you've installed
ipykernelinto your project:
poetry add ipykernel
-
Make sure the Poetry project is installed! This is especially important for projects that you have downloaded from others (warning: installing a Poetry project could run arbitrary code on your computer, make sure you trust your download first!):
poetry install
-
Still can't figure it out? Open an issue!
A package I added won't import properly
If you added the package after starting the kernel, you might need to restart the kernel for it to see the new package.
![FileNotFoundError: [Errno 2] No such file or directory: 'poetry'.](https://avatars.githubusercontent.com/u/1420654?v=4)
37 Jan 03, 2023
1.1k Dec 19, 2022
14 Dec 08, 2022
43 Nov 21, 2022
3 Oct 14, 2022
523 Jan 04, 2023
192 Dec 26, 2022
234 Dec 30, 2022
39 Apr 26, 2022
441 Dec 05, 2022
173 Jan 03, 2023
12 Jun 07, 2022
15 Dec 02, 2022
297 Dec 12, 2022
50 Sep 03, 2022
147 Aug 02, 2022
2 Aug 22, 2022
401 Dec 28, 2022
51 Nov 17, 2022
0 Jan 10, 2022