Warning
This documentation is for an old version of IPython. You can find docs for newer versions here.
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.
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 serialization 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.
-
deserialize
(msg_list, content=True, copy=True)¶ Unserialize a msg_list to a nested message dict.
This is roughly the inverse of serialize. The serialize/deserialize 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].
-
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.deserialize 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/deserialize 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/deserialize 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 deserialize. The serialize/deserialize 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 next 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.
-
6 Functions¶
-
IPython.kernel.zmq.session.
compare_digest
(a, b) → bool¶ Return ‘a == b’. This function uses an approach designed to prevent timing analysis, making it appropriate for cryptography. a and b must both be of the same type: either str (ASCII only), or any bytes-like object.
Note: If a and b are of different lengths, or if an error occurs, a timing attack could theoretically reveal information about the types and lengths of a and b–but not their values.
-
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
()¶