Note

This documentation is for a development version of IPython. There may be significant differences from the latest stable release (1.2.1).

Module: kernel.connect

Utilities for connecting to kernels

Authors:

• Min Ragan-Kelley

1 Class

class IPython.kernel.connect.ConnectionFileMixin(**kwargs)

Bases: IPython.config.configurable.Configurable

Mixin for configurable classes that work with connection files

cleanup_connection_file()

Cleanup connection file if we wrote it

Will not raise if the connection file was already removed somehow.

cleanup_ipc_files()

Cleanup ipc files if we wrote them.

connect_control(identity=None)

return zmq Socket connected to the Heartbeat channel

connect_hb(identity=None)

return zmq Socket connected to the Heartbeat channel

connect_iopub(identity=None)

return zmq Socket connected to the IOPub channel

connect_shell(identity=None)

return zmq Socket connected to the Shell channel

connect_stdin(identity=None)

return zmq Socket connected to the StdIn channel

get_connection_info()

return the connection info as a dict

load_connection_file()

Load connection info from JSON dict in self.connection_file.

write_connection_file()

Write connection info to JSON dict in self.connection_file.

6 Functions

IPython.kernel.connect.write_connection_file(fname=None, shell_port=0, iopub_port=0, stdin_port=0, hb_port=0, control_port=0, ip='', key='', transport='tcp', signature_scheme='hmac-sha256')

Generates a JSON config file, including the selection of random ports.

Parameters:

fname : unicode

The path to the file to write

shell_port : int, optional

The port to use for ROUTER (shell) channel.

iopub_port : int, optional

The port to use for the SUB channel.

stdin_port : int, optional

The port to use for the ROUTER (raw input) channel.

control_port : int, optional

The port to use for the ROUTER (control) channel.

hb_port : int, optional

The port to use for the heartbeat REP channel.

ip : str, optional

The ip address the kernel will bind to.

key : str, optional

The Session key used for message authentication.

signature_scheme : str, optional

The scheme used for message authentication. This has the form ‘digest-hash’, where ‘digest’ is the scheme used for digests, and ‘hash’ is the name of the hash function used by the digest scheme. Currently, ‘hmac’ is the only supported digest scheme, and ‘sha256’ is the default hash function.

IPython.kernel.connect.get_connection_file(app=None)

Return the path to the connection file of an app

Parameters:

app : IPKernelApp instance [optional]

If unspecified, the currently running app will be used

IPython.kernel.connect.find_connection_file(filename, profile=None)

find a connection file, and return its absolute path.

The current working directory and the profile’s security directory will be searched for the file if it is not given by absolute path.

If profile is unspecified, then the current running application’s profile will be used, or ‘default’, if not run from IPython.

If the argument does not match an existing file, it will be interpreted as a fileglob, and the matching file in the profile’s security dir with the latest access time will be used.

Parameters:

filename : str

The connection file or fileglob to search for.

profile : str [optional]

The name of the profile to use when searching for the connection file, if different from the current IPython session or ‘default’.

Returns:

str : The absolute path of the connection file.

IPython.kernel.connect.get_connection_info(connection_file=None, unpack=False, profile=None)

Return the connection information for the current Kernel.

Parameters:

connection_file : str [optional]

The connection file to be used. Can be given by absolute path, or IPython will search in the security directory of a given profile. If run from IPython,

If unspecified, the connection file for the currently running IPython Kernel will be used, which is only allowed from inside a kernel.

unpack : bool [default: False]

if True, return the unpacked dict, otherwise just the string contents of the file.

profile : str [optional]

The name of the profile to use when searching for the connection file, if different from the current IPython session or ‘default’.

Returns:

The connection dictionary of the current kernel, as string or dict,

depending on unpack.

IPython.kernel.connect.connect_qtconsole(connection_file=None, argv=None, profile=None)

Connect a qtconsole to the current kernel.

This is useful for connecting a second qtconsole to a kernel, or to a local notebook.

Parameters:

connection_file : str [optional]

The connection file to be used. Can be given by absolute path, or IPython will search in the security directory of a given profile. If run from IPython,

If unspecified, the connection file for the currently running IPython Kernel will be used, which is only allowed from inside a kernel.

argv : list [optional]

Any extra args to be passed to the console.

profile : str [optional]

The name of the profile to use when searching for the connection file, if different from the current IPython session or ‘default’.

Returns:

subprocess.Popen instance running the qtconsole frontend

IPython.kernel.connect.tunnel_to_kernel(connection_info, sshserver, sshkey=None)

tunnel connections to a kernel via ssh

This will open four SSH tunnels from localhost on this machine to the ports associated with the kernel. They can be either direct localhost-localhost tunnels, or if an intermediate server is necessary, the kernel must be listening on a public IP.

Parameters:

connection_info : dict or str (path)

Either a connection dict, or the path to a JSON connection file

sshserver : str

The ssh sever to use to tunnel to the kernel. Can be a full user@server:port string. ssh config aliases are respected.

sshkey : str [optional]

Path to file containing ssh key to use for authentication. Only necessary if your ssh config does not already associate a keyfile with the host.

Returns:

(shell, iopub, stdin, hb) : ints

The four ports on localhost that have been forwarded to the kernel.