|Build Status| |Coverage Status|
========
Callisto
========
*The fourth Galilean moon of Jupyter.*
A command line utility to create kernels in Jupyter from virtual environments.
Installation
============
Callisto may be installed `from pypi <https://pypi.python.org/pypi/callisto>`_:
::
pip install callisto
Tested against python 2.7, 3.4, 3.5, 3.6.
Basic Usage.
============
Typical use is to just activate it inside a virtual environment:
::
$ virtualenv venv
...
$ source venv/bin/activate
(venv) $ callisto
Successfully installed a new jupyter kernel "venv":
{
"env": {},
"language": "python",
"display_name": "venv",
"argv": [
"/Users/colin/venv/bin/python",
"-m",
"ipykernel",
"-f",
"{connection_file}"
]
}
See /Users/colin/Library/Jupyter/kernels/venv/kernel.json to edit.
Jupyter servers will now have an option for a kernel called `venv`.
.. image:: https://colindcarroll.com/img/venv.png
Naming the kernel.
==================
You may also give kernels a more descriptive name:
::
(venv) $ callisto -n pete
Successfully installed a new jupyter kernel "pete":
{
"env": {},
"display_name": "pete",
"argv": [
"/Users/colin/venv/bin/python",
"-m",
"ipykernel",
"-f",
"{connection_file}"
],
"language": "python"
}
See /Users/colin/Library/Jupyter/kernels/pete/kernel.json to edit.
Jupyter servers will now have an option for a kernel called `venv`, and `pete`.
.. image:: https://colindcarroll.com/img/venv_and_pete.png
Deleting kernels.
=================
Sometimes you may want to tidy kernels up a bit.
::
(venv) $ callisto -d
Deleted jupyter kernel "venv" from /Users/colin/Library/Jupyter/kernels/venv/kernel.json:
{
"argv": [
"/Users/colin/venv/bin/python",
"-m",
"ipykernel",
"-f",
"{connection_file}"
],
"env": {},
"language": "python",
"display_name": "venv"
}
Jupyter servers will no longer have a kernel named `venv`.
Lacking courage.
================
Callisto doesn't try to be too clever.
::
(venv) $ deactivate
$ callisto
Usage: callisto [OPTIONS]
Error: The environment variable VIRTUAL_ENV is not set (usually this is set
automatically activating a virtualenv). Please make sure you are in a
virtual environment!
Viewing existing kernels.
=========================
If you forgot the informative message about the kernel information, you can see it later.
::
$ source venv/bin/activate
(venv) $ callisto --list
No kernel found at /Users/colin/Library/Jupyter/kernels/venv/kernel.json
(venv) $ callisto -l --name pete
Found kernel "pete" at /Users/colin/Library/Jupyter/kernels/pete/kernel.json:
{
"display_name": "pete",
"language": "python",
"argv": [
"/Users/colin/venv/bin/python",
"-m",
"ipykernel",
"-f",
"{connection_file}"
],
"env": {}
}
Adjusting the `PYTHONPATH`.
===========================
With isolated kernels, you may wish to run all your notebooks from a single directory,
but using code from the project directories.
::
(venv) $ callisto -n pete --path=$(pwd)
Successfully installed a new jupyter kernel "pete":
{
"argv": [
"/Users/colin/venv/bin/python",
"-m",
"ipykernel",
"-f",
"{connection_file}"
],
"language": "python",
"env": {
"PYTHONPATH": "/Users/colin/projects/pete:PYTHONPATH"
},
"display_name": "pete"
}
See /Users/colin/Library/Jupyter/kernels/pete/kernel.json to edit.
Now the `pete` kernel will be able to import from the folder `/Users/colin/projects/pete`.
.. |Build Status| image:: https://travis-ci.org/ColCarroll/callisto.svg?branch=master
:target: https://travis-ci.org/ColCarroll/callisto
.. |Coverage Status| image:: https://coveralls.io/repos/github/ColCarroll/callisto/badge.svg?branch=master
:target: https://coveralls.io/github/ColCarroll/callisto?branch=master