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 raisesocket.error
.Timeout
,ConnectionClosed
, andMessageTooLong
all inherit fromsocket.error
and exist to provide better error messages. Received bytes are always buffered, even if an exception is raised. UseBufferedSocket.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 theBufferedSocket.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()
.-
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 callflush()
before calling this method. After calling this method, future socket operations will raisesocket.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, andsocket.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.
-
getpeername
()[source]¶ Convenience function to return the remote address to which the wrapped socket is connected. See
socket.getpeername()
for more details.
-
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: 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, aConnectionClosed
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 intype
andfamily
, 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 andNone
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-insocket.socket
, if this method returns an empty string, then the socket is closed and recv buffer is empty. Further calls to recv will raisesocket.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: 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, aConnectionClosed
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, butTrue
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: Will raise
Timeout
if the send operation fails to complete before timeout. In the event of an exception, useBufferedSocket.getsendbuffer()
to see which data was unsent.
-
sendall
(data, flags=0, timeout=_UNSET)[source]¶ A passthrough to
send()
, retained for parallelism to thesocket.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()
.
-
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 fullshutdown
is followed by aclose()
. 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 othersocketutils
exceptions inherit.When using
BufferedSocket
and othersocketutils
types, generally you want to catch one of the specific exception types below, orsocket.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 ofBufferedSocket
’srecv
methods.
-
exception
boltons.socketutils.
ConnectionClosed
[source]¶ Raised when receiving and the connection is unexpectedly closed from the sending end. Raised from
BufferedSocket
’speek()
,recv_until()
, andrecv_size()
, and never from itsrecv()
orrecv_close()
.
-
exception
boltons.socketutils.
MessageTooLong
(bytes_read=None, delimiter=None)[source]¶ Raised from
BufferedSocket.recv_until()
andBufferedSocket.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.