fsleyes.actions.notebook

This module provides the NotebookAction class, an action which starts an IPython kernel and a Jupyter notebook server, allowing the user to interact with FSLeyes via a jupyter notebook.

fsleyes.actions.notebook.AsyncMappingKernelManager

alias of mock

fsleyes.actions.notebook.FORWARD_SERVER_STDOUT = False

If True, standard output/error from the Jupyter notebook server will be forwarded to the standard output/error streams of the calling process. Otherwise, they will be suppressed, and only printed if the server crashes. This flag is only intended to be used for testing/debugging.

fsleyes.actions.notebook.SERVER_STARTUP_DELAY = 6.0

Amount of time in seconds to give the Jupyter server to start up. If the server has not started after this time, an error is assumed to have occurred. See the NotebookAction.__startServer() method.

fsleyes.actions.notebook.KERNEL_STARTUP_DELAY = 2.0

Amount of time in seconds to give the IPython kernel to start up. If the server has not started after this time, an error is assumed to have occurred. See the NotebookAction.__startKernel() method.

class fsleyes.actions.notebook.NotebookAction(*args, **kwargs)

Bases: Action

The NotebookAction is an Action which (if necessary) starts an embedded IPython kernel and a jupyter notebook server, and opens the server home page in a web browser allowing the user to interact with FSLeyes via notebooks.

__init__(overlayList, displayCtx, frame)

Create a NotebookAction.

Parameters:

• overlayList – The OverlayList.

• displayCtx – The master DisplayContext.

• frame – The FSLeyesFrame.

property kernel

Return a reference to the BackgroundIPythonKernel.

property server

Return a reference to the NotebookServer.

shutdown()

Shut down the notebook server and ipython kernel.

__openNotebooks(nbfile=None, openBrowser=True)

Called when this NotebookAction is invoked. Starts the server and kernel if necessary.

If the server/kernel have not yet been started and nbfile is provided, the server will be started with nbfile opened.

__bounce(secs, progdlg)

Used by __startKernel() and __startServer(). Blocks for secs, bouncing the Progress dialog ten times per second, and yielding to the wx main loop.

__startKernel(progdlg)

Attempts to create and start a BackgroundIPythonKernel.

Returns:

the kernel if it was started.

Raises:

A RuntimeError if the kernel did not start.

__startServer(progdlg, nbfile, openBrowser)

Attempts to create and start a NotebookServer.

Returns:

the server if it was started.

Raises:

A RuntimeError if the serer did not start.

__annotations__ = {}

__module__ = 'fsleyes.actions.notebook'

class fsleyes.actions.notebook.BackgroundIPythonKernel(overlayList, displayCtx, frame)

Bases: object

The BackgroundIPythonKernel creates an IPython jupyter kernel and makes it accessible over tcp (on the local machine only).

Before FSLeyes 0.28.0, this class derived from threading.Thread, and ran its own IOLoop which was used to run the IPython kernel. But now the IPython kernel is run on the main thread, by repeatedly scheduling calls to IPythonKernel.do_one_iteration on idle.idle().

This update was necessary due to changes in ipykernel from version 4 to version 5, namely that ipykernel 5 uses asyncio co-routines, making it difficult to transfer execution between threads.

Because the BackgroundIPythonKernel used to be a thread, it is still necessary to call its start() method to start the kernel loop.

The Jupyter/IPython documentation is quite fragmented at this point in time; this github issue was useful in figuring out the implementation details.

__init__(overlayList, displayCtx, frame)

Set up the kernel and zmq ports. A jupyter connection file containing the information needed to connect to the kernel is saved to a temporary file - its path is accessed as an attribute called connfile().

Parameters:

• overlayList – The OverlayList.

• displayCtx – The master DisplayContext.

• frame – The FSLeyesFrame.

is_alive()

Returns True if the kernel loop appears to be running, False otherwise

property kernel

The IPythonKernel object.

property env

The namespace passed to the kernel.

property connfile

The jupyter connection file containing information to connect to the IPython kernel.

property error

If an error occurs on the kernel loop causing it to crash, a reference to the Exception is stored here.

__screenshot(view=None)

Insert a screenshot of the given view panel into the notebook. If view is not specified, the first view is assumed.

start()

Start the IPython kernel loop. This method returns immediately - the kernel loop is driven on idle.idle().

stop()

Stops the kernel loop.

__eventloop()

Event loop used for the IPython kernel. Calls __kernelDispatch(), then schedules a future call to __eventloop via idle.idle() loop.

async __do_one_iteration()

Wrapper around IpythonKernel.do_one_iteration, to work around https://github.com/ipython/ipykernel/issues/763

__kernelDispatch()

Execute one kernel iteration, by scheduling a call to IPythonKernel.do_one_iteration on the kernel’s io loop.

__dict__ = mappingproxy({'__module__': 'fsleyes.actions.notebook', '__doc__': 'The BackgroundIPythonKernel creates an IPython jupyter kernel and makes\n    it accessible over tcp (on the local machine only).\n\n    Before FSLeyes 0.28.0, this class derived from ``threading.Thread``, and\n    ran its own ``IOLoop`` which was used to run the IPython kernel.  But now\n    the IPython kernel is run on the main thread, by repeatedly scheduling\n    calls to ``IPythonKernel.do_one_iteration`` on :func:`.idle.idle`.\n\n    This update was necessary due to changes in ``ipykernel`` from version 4\n    to version 5, namely that ipykernel 5 uses ``asyncio`` co-routines, making\n    it difficult to transfer execution between threads.\n\n    Because the ``BackgroundIPythonKernel`` used to be a thread, it is still\n    necessary to call its :meth:`start` method to start the kernel loop.\n\n    The Jupyter/IPython documentation is quite fragmented at this point in\n    time; `this github issue <https://github.com/ipython/ipython/issues/8097>`_\n    was useful in figuring out the implementation details.\n    ', '__init__': <function BackgroundIPythonKernel.__init__>, 'is_alive': <function BackgroundIPythonKernel.is_alive>, 'kernel': <property object>, 'env': <property object>, 'connfile': <property object>, 'error': <property object>, '_BackgroundIPythonKernel__screenshot': <function BackgroundIPythonKernel.__screenshot>, 'start': <function BackgroundIPythonKernel.start>, 'stop': <function BackgroundIPythonKernel.stop>, '_BackgroundIPythonKernel__eventloop': <function BackgroundIPythonKernel.__eventloop>, '_BackgroundIPythonKernel__do_one_iteration': <function BackgroundIPythonKernel.__do_one_iteration>, '_BackgroundIPythonKernel__kernelDispatch': <function BackgroundIPythonKernel.__kernelDispatch>, '__dict__': <attribute '__dict__' of 'BackgroundIPythonKernel' objects>, '__weakref__': <attribute '__weakref__' of 'BackgroundIPythonKernel' objects>, '__annotations__': {}})

__module__ = 'fsleyes.actions.notebook'

__weakref__

list of weak references to the object

class fsleyes.actions.notebook.FSLeyesIPythonKernel(stdout, stderr, *args, **kwargs)

Bases: mock

Custom IPython kernel used by FSLeyes. All this class does is ensure that the sys.stdout and sys.stderr streams are set appropriately when the kernel is executing code.

__init__(stdout, stderr, *args, **kwargs)

__patch_streams()

async execute_request(*args, **kwargs)

async dispatch_control(*args, **kwargs)

async dispatch_shell(*args, **kwargs)

__module__ = 'fsleyes.actions.notebook'

class fsleyes.actions.notebook.NotebookServer(connfile, nbfile=None, openBrowser=True)

Bases: Thread

Thread which starts a jupyter notebook server, and waits until it dies or is killed.

The server is configured such that all notebooks will connect to the same kernel, specified by the kernelFile parameter to __init__().

__init__(connfile, nbfile=None, openBrowser=True)

Create a NotebookServer thread.

Parameters:

• connfile – Connection file of the IPython kernel to connect to.

• nbfile – Path to a notebook file which should be opened on startup.

• openBrowser – If True (the default) the Jupyter notebook home page is opened in a web browser. This corresponds to the c.NotebookApp.open_browser setting.

property port

Returns the TCP port that the notebook server is listening on. Will return None before the server has started.

__readPort()

property ready

Returns True if the server is running and ready, False otherwise.

property token

Returns an authentication token to use for connectng to the notebook server.

property url

Returns the URL to use to connect to this server.

property stdout

After the server has died, returns its standard output. While the server is still running, returns None.

property stderr

After the server has died, returns its standard error. While the server is still running, returns None.

shutdown()

Shut down the notebook server. The server should be stopped within a second.

run()

Sets up a server configuration file, and then calls jupyer-notebook via subprocess.Popen. Waits until the notebook process dies.

__initConfigDir(cfgdir)

Creates a copy of the FSLeyes /assets/jupyter/ configuration directory in $TMPDIR, and customises its settings accordingly.

__module__ = 'fsleyes.actions.notebook'

class fsleyes.actions.notebook.FSLeyesNotebookKernelManager(*args, **kwargs)

Bases: mock

Custom jupyter AsyncMappingKernelManager which forces every notebook to connect to the embedded FSLeyes IPython kernel.

See https://github.com/ebanner/extipy

connfile = ''

Path to the IPython kernel connection file that all notebooks should connect to.

__annotations__ = {}

__init__(*args, **kwargs)

__module__ = 'fsleyes.actions.notebook'

__patch_connection(kernel)

Connects the given kernel to the IPython kernel specified by connfile.

async start_kernel(**kwargs)

Overrides AsyncMappingKernelManager.start_kernel. Connects all new kernels to the IPython kernel specified by connfile.

async restart_kernel(*args, **kwargs)

Overrides AsyncMappingKernelManager.restart_kernel. Does nothing.

class fsleyes.actions.notebook.mock

Bases: object

__annotations__ = {}

__dict__ = mappingproxy({'__module__': 'fsleyes.actions.notebook', '__dict__': <attribute '__dict__' of 'mock' objects>, '__weakref__': <attribute '__weakref__' of 'mock' objects>, '__doc__': None, '__annotations__': {}})

__module__ = 'fsleyes.actions.notebook'

__weakref__

list of weak references to the object

fsleyes.actions.notebook.nbmain(argv)

Wrapper around a Jupyter Notebook server entry point. Invoked by the NotebookServer, via a hook in fsleyes.main.main().

fsleyes.actions.notebook.findPythonExecutable()

Returns the path to the python executable. Used by the NotebookServer.run() method to start the notebook server in a separate process.