socketutils - socket wrappers

At its heart, Python can be viewed as an extension of the C programming language. Springing from the most popular systems programming language has made Python itself a great language for systems programming. One key to success in this domain is Python’s very serviceable socket module and its socket.socket type.

The socketutils module provides natural next steps to the socket builtin: straightforward, tested building blocks for higher-level protocols.

The BufferedSocket wraps an ordinary socket, providing a layer of intuitive buffering for both sending and receiving. This facilitates parsing messages from streams, i.e., all sockets with type SOCK_STREAM. The BufferedSocket enables receiving until the next relevant token, up to a certain size, or until the connection is closed. For all of these, it provides consistent APIs to size limiting, as well as timeouts that are compatible with multiple concurrency paradigms. Use it to parse the next one-off text or binary socket protocol you encounter.

This module also provides the NetstringSocket, a pure-Python implementation of the Netstring protocol, built on top of the BufferedSocket, serving as a ready-made, production-grade example.

Special thanks to Kurt Rose for his original authorship and all his contributions on this module. Also thanks to Daniel J. Bernstein, the original author of Netstring.

BufferedSocket

class boltons.socketutils.BufferedSocket(sock, timeout=_UNSET, maxsize=32768, recvsize=_UNSET)[source]

Mainly provides recv_until and recv_size. recv, send, sendall, and peek all function as similarly as possible to the built-in socket API.

This type has been tested against both the built-in socket type as well as those from gevent and eventlet. It also features support for sockets with timeouts set to 0 (aka nonblocking), provided the caller is prepared to handle the EWOULDBLOCK exceptions.

Parameters:
  • sock (socket) – The connected socket to be wrapped.
  • timeout (float) – The default timeout for sends and recvs, in seconds. Set to None for no timeout, and 0 for nonblocking. Defaults to sock‘s own timeout if already set, and 10 seconds otherwise.
  • maxsize (int) – The default maximum number of bytes to be received into the buffer before it is considered full and raises an exception. Defaults to 32 kilobytes.
  • recvsize (int) – The number of bytes to recv for every lower-level socket.recv() call. Defaults to maxsize.

timeout and maxsize can both be overridden on individual socket operations.

All recv methods return bytestrings (bytes) and can raise socket.error. Timeout, ConnectionClosed, and MessageTooLong all inherit from socket.error and exist to provide better error messages. Received bytes are always buffered, even if an exception is raised. Use BufferedSocket.getrecvbuffer() to retrieve partial recvs.

BufferedSocket does not replace the built-in socket by any means. While the overlapping parts of the API are kept parallel to the built-in socket.socket, BufferedSocket does not inherit from socket, and most socket functionality is only available on the underlying socket. socket.getpeername(), socket.getsockname(), socket.fileno(), and others are only available on the underlying socket that is wrapped. Use the BufferedSocket.sock attribute to access it. See the examples for more information on how to use BufferedSockets with built-in sockets.

The BufferedSocket is threadsafe, but consider the semantics of your protocol before accessing a single socket from multiple threads. Similarly, once the BufferedSocket is constructed, avoid using the underlying socket directly. Only use it for operations unrelated to messages, e.g., socket.getpeername().

buffer(data)[source]

Buffer data bytes for the next send operation.

close()[source]

Closes the wrapped socket, and empties the internal buffers. The send buffer is not flushed automatically, so if you have been calling buffer(), be sure to call flush() before calling this method. After calling this method, future socket operations will raise socket.error.

family

A passthrough to the wrapped socket’s family. BufferedSocket supports all widely-used families, so this read-only attribute can be one of socket.AF_INET for IP, socket.AF_INET6 for IPv6, and socket.AF_UNIX for UDS.

fileno()[source]

Returns the file descriptor of the wrapped socket. -1 if it has been closed on this end.

Note that this makes the BufferedSocket selectable, i.e., usable for operating system event loops without any external libraries. Keep in mind that the operating system cannot know about data in BufferedSocket’s internal buffer. Exercise discipline with calling recv* functions.

flush()[source]

Send the contents of the internal send buffer.

getpeername()[source]

Convenience function to return the remote address to which the wrapped socket is connected. See socket.getpeername() for more details.

getrecvbuffer()[source]

Returns the receive buffer bytestring (rbuf).

getsendbuffer()[source]

Returns a copy of the send buffer list.

getsockname()[source]

Convenience function to return the wrapped socket’s own address. See socket.getsockname() for more details.

getsockopt(level, optname, buflen=None)[source]

Convenience function passing through to the wrapped socket’s socket.getsockopt().

peek(size, timeout=_UNSET)[source]

Returns size bytes from the socket and/or internal buffer. Bytes are retained in BufferedSocket’s internal recv buffer. To only see bytes in the recv buffer, use getrecvbuffer().

Parameters:
  • size (int) – The exact number of bytes to peek at
  • timeout (float) – The timeout for this operation. Can be 0 for nonblocking and None for no timeout. Defaults to the value set in the constructor of BufferedSocket.

If the appropriate number of bytes cannot be fetched from the buffer and socket before timeout expires, then a Timeout will be raised. If the connection is closed, a ConnectionClosed will be raised.

proto

A passthrough to the wrapped socket’s protocol. The proto attribute is very rarely used, so it’s always 0, meaning “the default” protocol. Pretty much all the practical information is in type and family, so you can go back to never thinking about this.

recv(size, flags=0, timeout=_UNSET)[source]

Returns up to size bytes, using the internal buffer before performing a single socket.recv() operation.

Parameters:
  • size (int) – The maximum number of bytes to receive.
  • flags (int) – Kept for API compatibility with sockets. Only the default, 0, is valid.
  • timeout (float) – The timeout for this operation. Can be 0 for nonblocking and None for no timeout. Defaults to the value set in the constructor of BufferedSocket.

If the operation does not complete in timeout seconds, a Timeout is raised. Much like the built-in socket.socket, if this method returns an empty string, then the socket is closed and recv buffer is empty. Further calls to recv will raise socket.error.

recv_close(timeout=_UNSET, maxsize=_UNSET)[source]

Receive until the connection is closed, up to maxsize bytes. If more than maxsize bytes are received, raises MessageTooLong.

recv_size(size, timeout=_UNSET)[source]

Read off of the internal buffer, then off the socket, until size bytes have been read.

Parameters:
  • size (int) – number of bytes to read before returning.
  • timeout (float) – The timeout for this operation. Can be 0 for nonblocking and None for no timeout. Defaults to the value set in the constructor of BufferedSocket.

If the appropriate number of bytes cannot be fetched from the buffer and socket before timeout expires, then a Timeout will be raised. If the connection is closed, a ConnectionClosed will be raised.

recv_until(delimiter, timeout=_UNSET, maxsize=_UNSET, with_delimiter=False)[source]

Receive until delimiter is found, maxsize bytes have been read, or timeout is exceeded.

Parameters:
  • delimiter (bytes) – One or more bytes to be searched for in the socket stream.
  • timeout (float) – The timeout for this operation. Can be 0 for nonblocking and None for no timeout. Defaults to the value set in the constructor of BufferedSocket.
  • maxsize (int) – The maximum size for the internal buffer. Defaults to the value set in the constructor.
  • with_delimiter (bool) – Whether or not to include the delimiter in the output. False by default, but True is useful in cases where one is simply forwarding the messages.

recv_until will raise the following exceptions:

  • Timeout if more than timeout seconds expire.
  • ConnectionClosed if the underlying socket is closed by the sending end.
  • MessageTooLong if the delimiter is not found in the first maxsize bytes.
  • socket.error if operating in nonblocking mode (timeout equal to 0), or if some unexpected socket error occurs, such as operating on a closed socket.
send(data, flags=0, timeout=_UNSET)[source]

Send the contents of the internal send buffer, as well as data, to the receiving end of the connection. Returns the total number of bytes sent. If no exception is raised, all of data was sent and the internal send buffer is empty.

Parameters:
  • data (bytes) – The bytes to send.
  • flags (int) – Kept for API compatibility with sockets. Only the default 0 is valid.
  • timeout (float) – The timeout for this operation. Can be 0 for nonblocking and None for no timeout. Defaults to the value set in the constructor of BufferedSocket.

Will raise Timeout if the send operation fails to complete before timeout. In the event of an exception, use BufferedSocket.getsendbuffer() to see which data was unsent.

sendall(data, flags=0, timeout=_UNSET)[source]

A passthrough to send(), retained for parallelism to the socket.socket API.

setmaxsize(maxsize)[source]

Set the default maximum buffer size maxsize for future operations, in bytes. Does not truncate the current buffer.

setsockopt(level, optname, value)[source]

Convenience function passing through to the wrapped socket’s socket.setsockopt().

settimeout(timeout)[source]

Set the default timeout for future operations, in seconds.

shutdown(how)[source]

Convenience method which passes through to the wrapped socket’s shutdown(). Semantics vary by platform, so no special internal handling is done with the buffers. This method exists to facilitate the most common usage, wherein a full shutdown is followed by a close(). Developers requiring more support, please open an issue.

type

A passthrough to the wrapped socket’s type. Valid usages should only ever see socket.SOCK_STREAM.

Exceptions

These are a few exceptions that derive from socket.error and provide clearer code and better error messages.

exception boltons.socketutils.Error[source]

A subclass of socket.error from which all other socketutils exceptions inherit.

When using BufferedSocket and other socketutils types, generally you want to catch one of the specific exception types below, or socket.error.

exception boltons.socketutils.Timeout(timeout, extra='')[source]

Inheriting from socket.timeout, Timeout is used to indicate when a socket operation did not complete within the time specified. Raised from any of BufferedSocket‘s recv methods.

exception boltons.socketutils.ConnectionClosed[source]

Raised when receiving and the connection is unexpectedly closed from the sending end. Raised from BufferedSocket‘s peek(), recv_until(), and recv_size(), and never from its recv() or recv_close().

exception boltons.socketutils.MessageTooLong(bytes_read=None, delimiter=None)[source]

Raised from BufferedSocket.recv_until() and BufferedSocket.recv_closed() when more than maxsize bytes are read without encountering the delimiter or a closed connection, respectively.

Netstring

class boltons.socketutils.NetstringSocket(sock, timeout=10, maxsize=32768)[source]

Reads and writes using the netstring protocol.

More info: https://en.wikipedia.org/wiki/Netstring Even more info: http://cr.yp.to/proto/netstrings.txt

Nestring Exceptions

These are a few higher-level exceptions for Netstring connections.

exception boltons.socketutils.NetstringProtocolError[source]

Base class for all of socketutils’ Netstring exception types.

exception boltons.socketutils.NetstringInvalidSize(msg)[source]

NetstringInvalidSize is raised when the :-delimited size prefix of the message does not contain a valid integer.

Message showing valid size:

5:hello,

Here the 5 is the size. Anything in this prefix position that is not parsable as a Python integer (i.e., int) will raise this exception.

exception boltons.socketutils.NetstringMessageTooLong(size, maxsize)[source]

NetstringMessageTooLong is raised when the size prefix contains a valid integer, but that integer is larger than the NetstringSocket‘s configured maxsize.

When this exception is raised, it’s recommended to simply close the connection instead of trying to recover.