Socket I/O

class kaa.Socket(buffer_size=None, chunk_size=1048576)

Communicate over TCP or Unix sockets, implementing fully asynchronous reads and writes.

kaa.Socket requires an IPv6-capable stack, and favors IPv6 connectivity when available. This should generally be completely transparent on IPv4-only networks. See connect() for more information.

Synopsis

Class Hierarchy

kaa.Object
└─ kaa.IOChannel
     └─ kaa.Socket

Methods

connect()	Connects to the host specified in address.
listen()	Set the socket to accept incoming connections.
steal()
wrap()	Wraps an existing low-level socket object.

Properties

address	read-only	This property is deprecated; use peer instead.
alive	read-only	True if the socket is alive, and False otherwise.
buffer_size	read/write	Size of the send and receive socket buffers (SO_SNDBUF and SO_RCVBUF) in bytes.
connected	read-only	Boolean representing the connected state of the socket.
connecting	read-only	True if the socket is in the process of establishing a connection but is not yet connected.
fileno	read-only
listening	read-only	True if this is a listening socket, and False otherwise.
local	read-only	Returns either the tuple (host, port, flowinfo, scopeid, scope) representing the local end of a TCP socket, or the string containing the name of a Unix socket.
peer	read-only	Returns the tuple (host, port, flowinfo, scopeid, scope, reqhost) representing the remote end of the socket.
readable	read-only	True if the socket is readable, and False otherwise.

Signals

new-client	Emitted when a new client connects to a listening socket.

Methods

connect(addr, ipv6=True)

Connects to the host specified in address.

Parameters:

• addr (str, or 2- or 4-tuple) – Address for a remote host, or a Unix socket. If a str, it is either a Unix socket path or represents a TCP socket when in the form host:service[%scope]. See below for further details.
• ipv6 – if True, will connect to the remote host using IPv6 if it is reachable via IPv6. This is perfectly safe for IPv4 only hosts too. Set this to False if the remote host has a AAAA record and the local host has an IPv6 route to it, but you want to force IPv4 anyway.

Returns:

An InProgress object.

If addr is given as a 4-tuple, it is in the form (host, service, flowinfo, scope). If given as a 2-tuple, it is in the form (host, service), and in this case the flowinfo and scope are assumed to be 0.

The flowinfo and scope fields are only relevant for IPv6 hosts, where they represent the sin6_flowinfo and sin6_scope_id members in struct sockaddr_in6 in C. scope may be the name of an interface (e.g. eth0) or an interface id, and is needed when connecting to link-local addresses (fe80::/16).

If addr is given as a string, it is treated as a Unix socket path if it does not contain :, otherwise it is specified as host:service[%scope], where [x] indicates that x is optional, and where:

• host is a hostname, an IPv4 dotted quad, or an IPv6 address wrapped in square brackets. e.g. freevo.org, 192.168.0.1, [3000::1]
• service is a service name or port number. e.g. http, 80
• scope is an interface name or number. e.g. eth0, 2

When connecting to a link-local address (fe80::/16), scope must be specified. Relative Unix socket names (those not prefixed with /) are created via kaa.tempfile.

This function is executed in a thread to avoid blocking. It therefore returns an InProgress object. If the socket is connected, the InProgress is finished with no arguments. If the connection cannot be established, an exception is thrown to the InProgress.

listen(addr, backlog=5, ipv6=True)

Set the socket to accept incoming connections.

Parameters:

• addr (int, str, or 2- or 4-tuple) – Binds the socket to this address. If an int, this specifies a TCP port that is bound on all interfaces; if a str, it is either a Unix socket path or represents a TCP socket when in the form [host]:[service][%scope]. See below for further details.
• backlog (int) – the maximum length to which the queue of pending connections for the socket may grow.
• ipv6 (bool) – if True, will prefer binding to IPv6 addresses if addr is a hostname that contains both AAAA and A records. If addr is specified as an IP address, this argument does nothing.

Raises:

ValueError if addr is invalid, or socket.error if the bind fails.

If addr is given as a 4-tuple, it is in the form (host, service, flowinfo, scope). If passed as a 2-tuple, it is in the form (host, service), and in this case, it is assumed that flowinfo and scope are both 0. See connect() for more information.

If host is given as a string, it is treated as a Unix socket path if it does not contain :, otherwise it is specified as [host]:[service][%scope], where [x] indicates that x is optional, and where:

• host is a hostname, an IPv4 dotted quad, or an IPv6 address wrapped in square brackets. e.g. localhost, 192.168.0.1, [3000::1]. If host is not specified, the socket will listen on all interfaces.
• service is a service name or port number. e.g. http, 80
• scope is an interface name or number. e.g. eth0, 2

When binding to a link-local address (fe80::/16), scope must be specified. Relative Unix socket names (those not prefixed with /) are created via kaa.tempfile.

Warning

If the bind address supplied is a hostname rather than an IPv4 or IPv6 address, this function will block in order to resolve the hostname if the name is not specified in /etc/hosts. (In other words, localhost is probably safe.)

Once listening, new connections are automatically accepted, and the new-client signal is emitted for each new connection. Callbacks connecting to the signal will receive a new Socket object representing the client connection.

steal(socket)

wrap(sock, mode=3)

Wraps an existing low-level socket object.

addr specifies the 4-tuple address corresponding to the socket.

Properties

address

This property is deprecated; use peer instead.

alive

True if the socket is alive, and False otherwise.

A socket is considered alive when it is connected or in the process of connecting.

buffer_size

Size of the send and receive socket buffers (SO_SNDBUF and SO_RCVBUF) in bytes.

Setting this to higher values (say 1M) improves performance when sending large amounts of data across the socket. Note that the upper bound may be restricted by the kernel. (Under Linux, this can be tuned by adjusting /proc/sys/net/core/[rw]mem_max)

connected

Boolean representing the connected state of the socket.

connecting

True if the socket is in the process of establishing a connection but is not yet connected.

Once the socket is connected, the connecting property will be False, but the connected property will be True.

fileno

listening

True if this is a listening socket, and False otherwise.

local

Returns either the tuple (host, port, flowinfo, scopeid, scope) representing the local end of a TCP socket, or the string containing the name of a Unix socket.

scope is the interface name represented by scopeid, and is None if scopeid is 0.

On Python 2.6 and later, the returned value is a namedtuple.

peer

Returns the tuple (host, port, flowinfo, scopeid, scope, reqhost) representing the remote end of the socket.

scope is the interface name represented by scopeid, and is None if scopeid is 0. reqhost is the requested hostname if connect() was called, or None if this is a listening socket.

On Python 2.6 and later, the returned value is a namedtuple.

readable

True if the socket is readable, and False otherwise.

A socket is considered readable when it is listening or alive.

Signals

new-client

Emitted when a new client connects to a listening socket.

def callback(client, ...)

Parameter:client (Socket object) – the new client that just connected.