JupyterHub brings the power of notebooks to groups of users. It gives users access to computational environments and resources without burdening the users with installation and maintenance tasks. Users, including students, researchers, and data scientists, can get their work done in their own workspaces on shared resources which can be managed efficiently by system administrators.
JupyterHub runs in the cloud or on your own hardware, and makes it possible to serve a pre-configured data science environment to any user in the world. It is customizable and scalable, and is suitable for small and large teams, academic courses, and large-scale infrastructure.
This package introduces a number of concepts, such as session context, etc. Here we give a brief overview of some of the top-level concepts in this package.
A client is a single entity connected to a kernel. Since kernel messages include the client id, it is easy for a client to filter kernel messages for just messages between it and the kernel. In JupyterLab, different activities, such as a console and a notebook, are usually considered separate clients when connected to the same kernel.
A kernel spec is the data about an available kernel on the system. We can retrieve a current list of kernel specs from the server.
A kernel represents a running process on the server that implements the Jupyter kernel messaging protocol.
A kernel model mirrors the server kernel models, and represents a single running kernel on the server. A kernel can be created, restarted, shut down, etc., through calls to the server. A kernel model’s lifecycle mirrors the server kernel model’s lifecycle, and it will be disposed when the server kernel is shut down.
A kernel connection represents a single client connecting to a kernel over a websocket (wss). Typically only one kernel connection handles comms for any given kernel. The kernel connection is disposed when the client no longer has a need for the connection. Disposing a kernel connection does not cause the kernel to shut down. However, if a kernel is shut down, (eventually) all of its kernel connections should be disposed if they were initiated from a kernel manager. If the kernel connections were instantiated outside of a manager, you are responsible for cleaning them up.
A kernel connection has a number of signals, such as kernel status, kernel connection status, etc.
A kernel manager is an object that maintains a list of kernel models by regular polling. The kernel manager can instantiate a kernel connection and will manage its lifecycle.E.g., when the kernel is shut down, the connections will be disposed.
The manager provides some minimal bookkeeping around kernels and their connections. Generally, it is easiest to interact with kernels on a server through a manager.
A session is a mapping on the server from an identifying string (the session’s path) to a kernel. A session has a few other pieces of information to allow for easy categorization and searching of sessions.
The primary usecase of a session is to enable persisting a connection to a kernel. For example, a notebook viewer may start a session with session path of the notebook’s file path. When a browser is refreshed, the notebook viewer can connect to the same kernel by asking the server for the session corresponding with the notebook file path.
A session model mirrors a server session. The session models can be refreshed from the server, created, changed (including creating a new session kernel), and shut down (which implies that the kernel will be shut down). A session model’s lifecycle mirrors the server session’s lifecycle, and it will be disposed when the server session is shut down.
A session connection represents a single client connected to a session’s kernel. A session’s kernel connection can change and may be null to signify no current kernel connection. A session connection owns the kernel connection, meaning the kernel connection is created and disposed by the session connection as needed. The session connection proxies signals from the kernel connection for convenience. E.g. you can listen to the session’s status signal to get status changes for whatever the current kernel is, without having to disconnect and reconnect your signal handlers every time the session kernel changes.
The session connection can be disposed when the client no longer is connected to that session’s kernel, and disposal will not cause the session model to be deleted.
A session manager is an object that maintains a list of session models by regular polling. The session manager can instantiate a session connection and will manage its lifecycle. E.g. when the session is shut down, the connections will be disposed.
The manager provides some minimal bookkeeping around sessions and their connections. Generally, it is easiest to interact with sessions on a server through a manager.
A session context is an object which has the same lifecycle as the client. The session context owns a session connection, which may be null if the client is not currently associated with a session. The session context proxies the current session connection’s signals for convenience. The session context primarily serves as a stable object for a client to keep track of the current session connection. The session context also contains some convenience functionality, such as preferences for whether a kernel should be started and a user-friendly kernel name and status.
Here is a diagram that provides an overview of the different components:
Find at swagger.io a selectable list of all API calls available: Jupyter Server API.