kernelspec naming

[rgbkrk]

Something that isn't completely clear to me documentation wise from the command line tools to the notebook API is the "kernelspec". I want to be clear when talking to users and operators as well as in code.

$ jupyter kernelspec list --json
{
  "kernelspecs": {
    "python3": { // Is this the kernelspec
      "resource_dir": "/Users/kylek/Library/Jupyter/kernels/python3",
      "spec": { // or is this the kernelspec
        "display_name": "Python 3",
        "env": {},
        "argv": [
          "/usr/local/opt/python3/bin/python3.5",
          "-m",
          "ipykernel",
          "-f",
          "{connection_file}"
        ],
        "language": "python"
      }
    }
  }
}

I usually refer to the contents of the kernel.json within the kernels folder as the kernelspec. That's what the spec key is above:

{
  "display_name": "Python 3",
  "env": {},
  "argv": [
    "/usr/local/opt/python3/bin/python3.5",
    "-m",
    "ipykernel",
    "-f",
    "{connection_file}"
  ],
  "language": "python"
}

If that's the kernelspec, what's this higher level Object that comes back on jupyter kernelspec list --json or by GET /api/kernelspecs on the notebook server? Additionally, the notebook format has a kernelspec too, although it is missing the argv portion (normally):

...
"metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
}
...

There are at least a few concepts here:

• kernel name (python3 in the example above)
• kernel spec (the spec key on that object)
• kernel resources (?)

{
  "kernelspecs": {
    "python3": { // kernel name
      // kernel resources, includes spec
      "resource_dir": "/Users/kylek/Library/Jupyter/kernels/python3",
      "spec": { // kernelspec
        "display_name": "Python 3",
        "env": {},
        "argv": [
          "/usr/local/opt/python3/bin/python3.5",
          "-m",
          "ipykernel",
          "-f",
          "{connection_file}"
        ],
        "language": "python"
      }
    }
  }
}

Thoughts?

[takluyver]

I'd say that the directory containing the kernel.json file is technically a kernelspec. However, as kernel.json is the most important part of that, and the only essential part, we often refer to the data it contains as the kernelspec too. Calling the key in the JSON 'spec' was a lazy choice, in hindsight.

The entry in notebook metadata is a reference to a kernelspec by name. I.e. it identifies a kernelspec but is not itself a kernelspec. Then we copy some data in to use if the kernelspec is not found. If we had thought about it more carefully, we would probably have made the keys something like:

"metadata": {
  "kernel_info": {
   "display_name": "Python 3",
   "language": "python",
   "kernelspec_name": "python3"
  },
}

[blink1073]

@minrk and I had some discussion about this: https://github.com/jupyterlab/services/issues/259

[rgbkrk]

Ooooh thank you @takluyver and @blink1073! I looked in jupyterlab, I should have checked services. I figured you unearthed this while typescripting.