kernel

one running kernel: execute and complete over the shell channel, variables over its in-kernel

Run one local or gateway kernel. Execution returns nbformat outputs. Inspection uses the Dhrishti HTTP API.

KERNELS lists supported Python launchers. Unknown launcher names use ipykernel.

_give_up_after stops waiting for shutdown after the timeout.

t = time.time()
await _give_up_after(asyncio.sleep(30), timeout=.05)      # the deadline ends this, not the sleep
async def never_answers(): raise RuntimeError('the kernel never answered')
await _give_up_after(never_answers()), time.time() - t < 1
(None, True)

never_answers

async def never_answers():

Call self as a function.

source

ipymini_available

def ipymini_available():

True when the ipymini package can be imported in this interpreter.

ipymini_available checks whether the package can be imported without importing it.

ipymini_available()
True

_Inspector holds state and Dhrishti client methods shared by local and gateway kernels.

p = Probe('http://127.0.0.1:8123')
p.token, p._headers(), Probe().token
('S3CRET', {'X-Dhrishti-Token': 'S3CRET'}, None)
p.touch()
p.busy, p.idle_for < 1, p.kernel_kind
(False, True, 'ipykernel')

names returns top-level names from Dhrishti’s grouped response.

class Rows(Probe):
    "The inspector's answer, without the inspector."
    async def api(self, path, params=None, timeout=15):
        self.asked = path
        return {'groups': [{'name': 'data', 'nodes': [{'name': 'df'}, {'name': 'raw'}]}, {'name': 'other', 'nodes': [{'name': 'x'}]}]}
r = Rows('http://127.0.0.1:8123')
await r.names(), r.asked
(['df', 'raw', 'x'], '/api/rows')

Rows

def Rows(
    base:NoneType=None, name:str='nb'
):

The inspector’s answer, without the inspector.

stop interrupts the active execution. It restarts the kernel when the execution does not stop before the timeout.

async def one_cell(obeys):
    k = Running(obeys)
    return (await k.stop(timeout=.05))['note'], k.restarted
print(await Probe().stop())
for obeys in (True, False): print(await one_cell(obeys))
{'ok': False, 'forced': False, 'note': 'nothing is running'}
('cell interrupted', False)
('kernel restarted after interrupt was ignored', True)

one_cell

async def one_cell(
    obeys
):

Call self as a function.

source

Kernel

def Kernel(
    cwd:NoneType=None, name:NoneType=None, python:NoneType=None, inspect:bool=True, agent:str='restricted',
    port:int=8000, kernel:str='ipykernel', lang:str='python',
    known:NoneType=None, # the host's `{language: kernelspec}`, handed down by the pool
    install:str='', # what would install a kernel for `lang`, for the error when none is
):

One ipykernel process: execute/complete over jupyter_client, live variables over its in-kernel.

Kernel owns one local kernel process and its Jupyter client. start waits for the kernel and then starts Dhrishti when inspection is enabled.

k = Kernel(kernel='not-a-kernel', inspect=False)
j = Kernel(cwd='/proj', lang='julia', inspect=True)
k.kernel, (j.kernel, j.inspect, await j.chdir('/proj'))
('ipykernel', ('ipykernel', False, False))

Execution on a stopped kernel returns a failed ExecOutcome. Each request collects only messages with its own parent ID.

k.alive, k.pid, (await k.execute('1+1')).error, await k.complete('1+', 2), await k.inspect_obj('1+', 2)
(False, None, 'kernel is not running', {'from': 2, 'matches': []}, '')

Registered language kernels use their installed kernelspec. A missing kernelspec raises KernelStartError.

_as_output converts one IOPub message to an nbformat output. Messages without output return None.

[Kernel._as_output('stream', {'name': 'stdout', 'text': 'hello\n'}),
 Kernel._as_output('execute_result', {'data': {'text/plain': '42'}, 'execution_count': 1}),
 Kernel._as_output('update_display_data', {'data': {'text/plain': 'second'}}),
 Kernel._as_output('status', {'execution_state': 'idle'})]
[{'output_type': 'stream', 'name': 'stdout', 'text': 'hello\n'},
 {'output_type': 'execute_result',
  'data': {'text/plain': '42'},
  'metadata': {},
  'execution_count': 1},
 {'output_type': 'display_data',
  'data': {'text/plain': 'second'},
  'metadata': {}},
 None]

source

check_gateway_deps

def check_gateway_deps():

Check the gateway dependencies and versions.

check_gateway_deps reports a missing or incompatible gateway package. jupyasyncclient 0.2.8 is excluded because it does not execute requests.

try: check_gateway_deps()
except RuntimeError as e: print(e)

source

GatewayService

def GatewayService(
    port:int=8787, token:NoneType=None
):

One supervised jupygate for all workspace kernels in this host process.

GatewayService starts one Jupyter gateway for this process and returns its connection details.

g = GatewayService(port='8899', token='shared-secret')
g.url, g.server
('http://127.0.0.1:8899', None)

source

GatewayKernel

def GatewayKernel(
    gateway, cwd:NoneType=None, name:NoneType=None, python:NoneType=None, inspect:bool=True, agent:str='restricted',
    port:int=8000, kernel:str='ipykernel'
):

The Kernel interface over jupygate + jupyasyncclient, so a kernel outlives a client reconnect.

GatewayKernel implements the Kernel interface over a gateway WebSocket. The gateway owns the kernel process.

gk = GatewayKernel(None, name='nb', inspect=False)
gk.alive, gk.pid, gk.lang, gk._boot_name.startswith('nb:'), (await gk.execute('1+1')).error
(False, None, 'python', True, 'kernel is not running')