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
socket module and its
socketutils module provides natural next steps to the
builtin: straightforward, tested building blocks for higher-level
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.
BufferedSocket(sock, timeout=_UNSET, maxsize=32768, recvsize=_UNSET)¶
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.
- sock (socket) – The connected socket to be wrapped.
- timeout (float) – The default timeout for sends and recvs, in
seconds. Set to
Nonefor 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
socket.recv()call. Defaults to maxsize.
timeout and maxsize can both be overridden on individual socket operations.
recvmethods return bytestrings (
bytes) and can raise
MessageTooLongall inherit from
socket.errorand 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.fileno(), and others are only available on the underlying socket that is wrapped. Use the
BufferedSocket.sockattribute 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.,
Buffer data bytes for the next send operation.
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
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_INET6for IPv6, and
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
Send the contents of the internal send buffer.
Convenience function to return the remote address to which the wrapped socket is connected. See
socket.getpeername()for more details.
Returns the receive buffer bytestring (rbuf).
Returns a copy of the send buffer list.
Convenience function to return the wrapped socket’s own address. See
socket.getsockname()for more details.
getsockopt(level, optname, buflen=None)¶
Convenience function passing through to the wrapped socket’s
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
A passthrough to the wrapped socket’s protocol. The
protoattribute is very rarely used, so it’s always 0, meaning “the default” protocol. Pretty much all the practical information is in
family, so you can go back to never thinking about this.
recv(size, flags=0, timeout=_UNSET)¶
Returns up to size bytes, using the internal buffer before performing a single
- size (int) – The maximum number of bytes to receive.
- flags (int) – Kept for API compatibility with sockets. Only
0, is valid.
- timeout (float) – The timeout for this operation. Can be
0for nonblocking and
Nonefor no timeout. Defaults to the value set in the constructor of BufferedSocket.
If the operation does not complete in timeout seconds, a
Timeoutis 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
Receive until the connection is closed, up to maxsize bytes. If more than maxsize bytes are received, raises
Read off of the internal buffer, then off the socket, until size bytes have been read.
recv_until(delimiter, timeout=_UNSET, maxsize=_UNSET, with_delimiter=False)¶
Receive until delimiter is found, maxsize bytes have been read, or timeout is exceeded.
- 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.
Falseby default, but
Trueis useful in cases where one is simply forwarding the messages.
recv_untilwill raise the following exceptions:
Timeoutif more than timeout seconds expire.
ConnectionClosedif the underlying socket is closed by the sending end.
MessageTooLongif the delimiter is not found in the first maxsize bytes.
socket.errorif 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)¶
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.
sendall(data, flags=0, timeout=_UNSET)¶
A passthrough to
send(), retained for parallelism to the
Set the default maximum buffer size maxsize for future operations, in bytes. Does not truncate the current buffer.
setsockopt(level, optname, value)¶
Convenience function passing through to the wrapped socket’s
Set the default timeout for future operations, in seconds.
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
shutdownis followed by a
close(). Developers requiring more support, please open an issue.
These are a few exceptions that derive from
provide clearer code and better error messages.
A subclass of
socket.errorfrom which all other
NetstringSocket(sock, timeout=10, maxsize=32768)¶
Reads and writes using the netstring protocol.
These are a few higher-level exceptions for Netstring connections.
Base class for all of socketutils’ Netstring exception types.
NetstringInvalidSize is raised when the
:-delimited size prefix of the message does not contain a valid integer.
Message showing valid size:
5is the size. Anything in this prefix position that is not parsable as a Python integer (i.e.,
int) will raise this exception.
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.