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.zmq.session

Session object for building, serializing, sending, and receiving messages in IPython. The Session object supports serialization, HMAC signatures, and metadata on messages.

Also defined here are utilities for working with Sessions: * A SessionFactory to be used as a base class for configurables that work with Sessions. * A Message object for convenience that allows attribute-access to the msg dict.

Authors:

• Min RK
• Brian Granger
• Fernando Perez

3 Classes

class IPython.kernel.zmq.session.SessionFactory(**kwargs)

Bases: IPython.config.configurable.LoggingConfigurable

The Base class for configurables that have a Session, Context, logger, and IOLoop.

__init__(**kwargs)

class IPython.kernel.zmq.session.Message(msg_dict)

Bases: object

A simple message object that maps dict keys to attributes.

A Message can be created from a dict and a dict from a Message instance simply by calling dict(msg_obj).

__init__(msg_dict)

class IPython.kernel.zmq.session.Session(**kwargs)

Bases: IPython.config.configurable.Configurable

Object for handling serialization and sending of messages.

The Session object handles building messages and sending them with ZMQ sockets or ZMQStream objects. Objects can communicate with each other over the network via Session objects, and only need to work with the dict-based IPython message spec. The Session will handle serialization/deserialization, security, and metadata.

Sessions support configurable serialiization via packer/unpacker traits, and signing with HMAC digests via the key/keyfile traits.

Parameters:

debug : bool

whether to trigger extra debugging statements

packer/unpacker : str

importstrings for methods to serialize message parts. If just ‘json’ or ‘pickle’, predefined JSON and pickle packers will be used. Otherwise, the entire importstring must be used.

The functions must accept at least valid JSON input, and output bytes.

For example, to use msgpack: packer = ‘msgpack.packb’, unpacker=’msgpack.unpackb’

pack/unpack : callables

You can also set the pack/unpack callables for serialization directly.

session : bytes

the ID of this Session object. The default is to generate a new UUID.

username : unicode

username added to message headers. The default is to ask the OS.

key : bytes

The key used to initialize an HMAC signature. If unset, messages will not be signed or checked.

keyfile : filepath

The file containing a key. If this is set, key will be initialized to the contents of the file.

__init__(**kwargs)

create a Session object

Parameters:

debug : bool

whether to trigger extra debugging statements

packer/unpacker : str

importstrings for methods to serialize message parts. If just ‘json’ or ‘pickle’, predefined JSON and pickle packers will be used. Otherwise, the entire importstring must be used.

The functions must accept at least valid JSON input, and output bytes.

For example, to use msgpack: packer = ‘msgpack.packb’, unpacker=’msgpack.unpackb’

pack/unpack : callables

You can also set the pack/unpack callables for serialization directly.

session : unicode (must be ascii)

the ID of this Session object. The default is to generate a new UUID.

bsession : bytes

The session as bytes

username : unicode

username added to message headers. The default is to ask the OS.

key : bytes

The key used to initialize an HMAC signature. If unset, messages will not be signed or checked.

signature_scheme : str

The message digest scheme. Currently must be of the form ‘hmac-HASH’, where ‘HASH’ is a hashing function available in Python’s hashlib. The default is ‘hmac-sha256’. This is ignored if ‘key’ is empty.

keyfile : filepath

The file containing a key. If this is set, key will be initialized to the contents of the file.

feed_identities(msg_list, copy=True)

Split the identities from the rest of the message.

Feed until DELIM is reached, then return the prefix as idents and remainder as msg_list. This is easily broken by setting an IDENT to DELIM, but that would be silly.

Parameters:

msg_list : a list of Message or bytes objects

The message to be split.

copy : bool

flag determining whether the arguments are bytes or Messages

Returns:

(idents, msg_list) : two lists

idents will always be a list of bytes, each of which is a ZMQ identity. msg_list will be a list of bytes or zmq.Messages of the form [HMAC,p_header,p_parent,p_content,buffer1,buffer2,...] and should be unpackable/unserializable via self.unserialize at this point.

msg(msg_type, content=None, parent=None, header=None, metadata=None)

Return the nested message dict.

This format is different from what is sent over the wire. The serialize/unserialize methods converts this nested message dict to the wire format, which is a list of message parts.

msg_id

always return new uuid

recv(socket, mode=1, content=True, copy=True)

Receive and unpack a message.

Parameters:

socket : ZMQStream or Socket

The socket or stream to use in receiving.

Returns:

[idents], msg

[idents] is a list of idents and msg is a nested message dict of same format as self.msg returns.

send(stream, msg_or_type, content=None, parent=None, ident=None, buffers=None, track=False, header=None, metadata=None)

Build and send a message via stream or socket.

The message format used by this function internally is as follows:

[ident1,ident2,...,DELIM,HMAC,p_header,p_parent,p_content,

buffer1,buffer2,...]

The serialize/unserialize methods convert the nested message dict into this format.

Parameters:

stream : zmq.Socket or ZMQStream

The socket-like object used to send the data.

msg_or_type : str or Message/dict

Normally, msg_or_type will be a msg_type unless a message is being sent more than once. If a header is supplied, this can be set to None and the msg_type will be pulled from the header.

content : dict or None

The content of the message (ignored if msg_or_type is a message).

header : dict or None

The header dict for the message (ignored if msg_to_type is a message).

parent : Message or dict or None

The parent or parent header describing the parent of this message (ignored if msg_or_type is a message).

ident : bytes or list of bytes

The zmq.IDENTITY routing path.

metadata : dict or None

The metadata describing the message

buffers : list or None

The already-serialized buffers to be appended to the message.

track : bool

Whether to track. Only for use with Sockets, because ZMQStream objects cannot track messages.

Returns:

msg : dict

The constructed message.

send_raw(stream, msg_list, flags=0, copy=True, ident=None)

Send a raw message via ident path.

This method is used to send a already serialized message.

Parameters:

stream : ZMQStream or Socket

The ZMQ stream or socket to use for sending the message.

msg_list : list

The serialized list of messages to send. This only includes the [p_header,p_parent,p_metadata,p_content,buffer1,buffer2,...] portion of the message.

ident : ident or list

A single ident or a list of idents to use in sending.

serialize(msg, ident=None)

Serialize the message components to bytes.

This is roughly the inverse of unserialize. The serialize/unserialize methods work with full message lists, whereas pack/unpack work with the individual message parts in the message list.

Parameters:

msg : dict or Message

The nexted message dict as returned by the self.msg method.

Returns:

msg_list : list

The list of bytes objects to be sent with the format:

[ident1, ident2, ..., DELIM, HMAC, p_header, p_parent,
 p_metadata, p_content, buffer1, buffer2, ...]

In this list, the p_* entities are the packed or serialized versions, so if JSON is used, these are utf8 encoded JSON strings.

sign(msg_list)

Sign a message with HMAC digest. If no auth, return b’‘.

Parameters:

msg_list : list

The [p_header,p_parent,p_content] part of the message list.

unserialize(msg_list, content=True, copy=True)

Unserialize a msg_list to a nested message dict.

This is roughly the inverse of serialize. The serialize/unserialize methods work with full message lists, whereas pack/unpack work with the individual message parts in the message list.

Parameters:

msg_list : list of bytes or Message objects

The list of message parts of the form [HMAC,p_header,p_parent, p_metadata,p_content,buffer1,buffer2,...].

content : bool (True)

Whether to unpack the content dict (True), or leave it packed (False).

copy : bool (True)

Whether to return the bytes (True), or the non-copying Message object in each place (False).

Returns:

msg : dict

The nested message dict with top-level keys [header, parent_header, content, buffers].

5 Functions

IPython.kernel.zmq.session.squash_unicode(obj)

coerce unicode back to bytestrings.

IPython.kernel.zmq.session.default_secure(cfg)

Set the default behavior for a config environment to be secure.

If Session.key/keyfile have not been set, set Session.key to a new random UUID.

IPython.kernel.zmq.session.msg_header(msg_id, msg_type, username, session)

IPython.kernel.zmq.session.extract_header(msg_or_header)

Given a message or header, return the header.

IPython.kernel.zmq.session.test_msg2obj()