PyZMQ Documentation

Table Of Contents

Previous topic

core.poll

Next topic

core.stopwatch

This Page

core.socket

Module: core.socket

Inheritance diagram for zmq.core.socket:

0MQ Socket class.

Socket

class zmq.core.socket.Socket(context, socket_type)

Bases: object

A 0MQ socket.

These objects will generally be constructed via the socket() method of a Context object.

Parameters :

context : Context

The 0MQ Context this Socket belongs to.

socket_type : int

The socket type, which can be any of the 0MQ socket types: REQ, REP, PUB, SUB, PAIR, XREQ, XREP, PULL, PUSH, XPUB, XSUB.

See also

Context.socket
method for creating a socket bound to a Context.
bind(addr)

Bind the socket to an address.

This causes the socket to listen on a network port. Sockets on the other side of this connection will use Socket.connect(addr) to connect to this socket.

Parameters :

addr : str

The address string. This has the form ‘protocol://interface:port’, for example ‘tcp://127.0.0.1:5555’. Protocols supported are tcp, upd, pgm, inproc and ipc. If the address is unicode, it is encoded to utf-8 first.

bind_to_random_port(addr, min_port=2000, max_port=20000, max_tries=100)

Bind this socket to a random port in a range.

Parameters :

addr : str

The address string without the port to pass to Socket.bind().

min_port : int, optional

The minimum port in the range of ports to try.

max_port : int, optional

The maximum port in the range of ports to try.

max_tries : int, optional

The number of attempt to bind.

Returns :

port : int

The port the socket was bound to.

Raises :

ZMQBindError :

if max_tries reached before successful bind

close()

Close the socket.

This can be called to close the socket by hand. If this is not called, the socket will automatically be closed when it is garbage collected.

closed
connect(addr)

Connect to a remote 0MQ socket.

Parameters :

addr : str

The address string. This has the form ‘protocol://interface:port’, for example ‘tcp://127.0.0.1:5555’. Protocols supported are tcp, upd, pgm, inproc and ipc. If the address is unicode, it is encoded to utf-8 first.

context
getsockopt(option)

Get the value of a socket option.

See the 0MQ documentation for details on specific options.

Parameters :

option : str

The name of the option to set. Can be any of: IDENTITY, HWM, SWAP, AFFINITY, RATE, RECOVERY_IVL, MCAST_LOOP, SNDBUF, RCVBUF, RCVMORE.

Returns :

optval : int, str

The value of the option as a string or int.

getsockopt_unicode(option, encoding='utf-8')

Get the value of a socket option.

See the 0MQ documentation for details on specific options.

Parameters :

option : unicode string

The name of the option to set. Can be any of: IDENTITY, HWM, SWAP, AFFINITY, RATE, RECOVERY_IVL, MCAST_LOOP, SNDBUF, RCVBUF, RCVMORE.

Returns :

optval : unicode

The value of the option as a unicode string.

rcvmore()

Are there more parts to a multipart message?

Returns :

more : bool

whether we are in the middle of a multipart message.

recv(flags=0, copy=True, track=False)

Receive a message.

Parameters :

flags : int

Any supported flag: NOBLOCK. If NOBLOCK is set, this method will raise a ZMQError with EAGAIN if a message is not ready. If NOBLOCK is not set, then this method will block until a message arrives.

copy : bool

Should the message be received in a copying or non-copying manner? If False a Message object is returned, if True a string copy of message is returned.

track : bool

Should the message be tracked for notification that ZMQ has finished with it? (ignored if copy=True)

Returns :

msg : str, Message

The returned message. If copy is False, then it will be a Message, otherwise a str.

Raises :

ZMQError :

for any of the reasons zmq_recv might fail.

recv_json(flags=0)

Receive a Python object as a message using json to serialize.

Parameters :

flags : int

Any valid recv flag.

Returns :

obj : Python object

The Python object that arrives as a message.

recv_multipart(flags=0, copy=True, track=False)

Receive a multipart message as a list of messages.

Parameters :

flags : int, optional

Any supported flag: NOBLOCK. If NOBLOCK is set, this method will raise a ZMQError with EAGAIN if a message is not ready. If NOBLOCK is not set, then this method will block until a message arrives.

copy : bool, optional

Should the message(s) be received in a copying or non-copying manner? If False a Message object is returned for part, if True a string copy of message is returned for each message part.

track : bool, optional

Should the message(s) be tracked for notification that ZMQ has finished with it? (ignored if copy=True)

Returns :

msg_parts : list

A list of messages in the multipart message; either Messages or strs, depending on copy.

recv_pyobj(flags=0)

Receive a Python object as a message using pickle to serialize.

Parameters :

flags : int

Any valid recv flag.

Returns :

obj : Python object

The Python object that arrives as a message.

recv_unicode(flags=0, encoding='utf-8')

Receive a unicode string, as sent by send_unicode.

Parameters :

flags : int

Any valid recv flag.

encoding : str [default: ‘utf-8’]

The encoding to be used

Returns :

s : unicode string

The Python unicode string that arrives as message bytes.

send(data, flags=0, copy=True, track=False)

Send a message on this socket.

This queues the message to be sent by the IO thread at a later time.

Parameters :

data : object, str, Message

The content of the message.

flags : int

Any supported flag: NOBLOCK, SNDMORE.

copy : bool

Should the message be sent in a copying or non-copying manner.

track : bool

Should the message be tracked for notification that ZMQ has finished with it? (ignored if copy=True)

Returns :

None : if copy or not track

None if message was sent, raises an exception otherwise.

MessageTracker : if track and not copy

a MessageTracker object, whose pending property will be True until the send is completed.

Raises :

TypeError :

If a unicode object is passed

ValueError :

If track=True, but an untracked Message is passed.

ZMQError :

If the send does not succeed for any reason.

send_json(obj, flags=0)

Send a Python object as a message using json to serialize.

Parameters :

obj : Python object

The Python object to send.

flags : int

Any valid send flag.

send_multipart(msg_parts, flags=0, copy=True, track=False)

Send a sequence of messages as a multipart message.

Parameters :

msg_parts : iterable

A sequence of messages to send as a multipart message. Each element can be any sendable object (Message, bytes, buffer-providers)

flags : int, optional

Only the NOBLOCK flagis supported, SNDMORE is handled automatically.

copy : bool, optional

Should the message(s) be sent in a copying or non-copying manner.

track : bool, optional

Should the message(s) be tracked for notification that ZMQ has finished with it (ignored if copy=True).

Returns :

None : if copy or not track

MessageTracker : if track and not copy

a MessageTracker object, whose pending property will be True until the last send is completed.

send_pyobj(obj, flags=0, protocol=-1)

Send a Python object as a message using pickle to serialize.

Parameters :

obj : Python object

The Python object to send.

flags : int

Any valid send flag.

protocol : int

The pickle protocol number to use. Default of -1 will select the highest supported number. Use 0 for multiple platform support.

send_unicode(u, flags=0, copy=False, encoding='utf-8')

Send a Python unicode object as a message with an encoding.

Parameters :

u : Python unicode object

The unicode string to send.

flags : int, optional

Any valid send flag.

encoding : str [default: ‘utf-8’]

The encoding to be used

setsockopt(option, optval)

Set socket options.

See the 0MQ documentation for details on specific options.

Parameters :

option : str

The name of the option to set. Can be any of: SUBSCRIBE, UNSUBSCRIBE, IDENTITY, HWM, SWAP, AFFINITY, RATE, RECOVERY_IVL, MCAST_LOOP, SNDBUF, RCVBUF.

optval : int or str

The value of the option to set.

setsockopt_unicode(option, optval, encoding='utf-8')

Set socket options with a unicode object it is simply a wrapper for setsockopt to protect from encoding ambiguity.

See the 0MQ documentation for details on specific options.

Parameters :

option : int

The name of the option to set. Can be any of: SUBSCRIBE, UNSUBSCRIBE, IDENTITY

optval : unicode

The value of the option to set.

encoding : str

The encoding to be used, default is utf8

socket_type