socketutils - socket 包装纸

从本质上讲，可以将Python视为C编程语言的扩展。从最流行的系统编程语言中脱颖而出的Python使其本身成为一种伟大的系统编程语言。在这个领域取得成功的一个关键是，Python的可用性非常强 socket 模块及其智能控制系统 socket.socket 键入。

这个 socketutils 模块提供了自然的后续步骤 socket 内置：用于更高级别协议的简单、经过测试的构建块。

这个 BufferedSocket 包装普通套接字，为发送和接收提供一层直观的缓冲区。这有助于解析来自流的消息，即具有类型的所有套接字 SOCK_STREAM 。BufferedSocket允许接收，直到下一个相关令牌，直到某个大小，或者直到连接关闭。对于所有这些，它提供了一致的API来限制大小，以及与多个并发范例兼容的超时。使用它来解析您遇到的下一个一次性文本或二进制套接字协议。

此模块还提供 NetstringSocket ，一个纯Python实现的 the Netstring protocol ，建在 BufferedSocket ，作为现成的、生产级的例子。

特别感谢 Kurt Rose 感谢他的原著和他在这个模块上的所有贡献。也要感谢 Daniel J. Bernstein ，原著作者 Netstring 。

BufferedSocket

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

主要提供recv_Until和recv_Size。Recv、Send、Sendall和Peek的功能都尽可能类似于内置套接字API。

该类型已经针对内置套接字类型以及来自GEvent和Eventlet的类型进行了测试。它还支持超时设置为0(也称为非阻塞)的套接字，前提是调用方准备好处理EWOULDBLOCK异常。

参数:

• sock (socket) -- 要包装的已连接插座。

• timeout (float) -- 发送和接收的默认超时时间，以秒为单位。设为 None 表示无超时，0表示非阻塞。默认为 sock 如果已设置，则为自己的超时，否则为10秒。

• maxsize (int) -- 在缓冲区被视为已满并引发异常之前要接收到缓冲区的默认最大字节数。默认为32千字节。

• recvsize (int) -- 要为每个较低级别接收的字节数 socket.recv() 打电话。默认为 maxsize 。

timeout 和 maxsize 两者都可以在单个套接字操作上被重写。

全 recv 方法返回字节字符串 (bytes )，并可以筹集 socket.error 。 Timeout ， ConnectionClosed ，及 MessageTooLong 所有内容都继承自 socket.error 并存在以提供更好的错误消息。即使引发异常，也始终会缓冲接收到的字节。使用 BufferedSocket.getrecvbuffer() 以检索部分recv。

BufferedSocket无论如何都不会取代内置套接字。而API的重叠部分与内置的 socket.socket ，BufferedSocket不是从套接字继承的，并且大多数套接字功能仅在基础套接字上可用。 socket.getpeername() ， socket.getsockname() ， socket.fileno() ，而其他仅在包装的底层套接字上可用。使用 BufferedSocket.sock 属性来访问它。有关如何将BufferedSockets与内置套接字一起使用的更多信息，请参阅示例。

BufferedSocket是线程安全的，但在从多个线程访问单个套接字之前，请考虑协议的语义。同样，一旦构造了BufferedSocket，就避免直接使用底层套接字。仅将其用于与消息无关的操作，例如， socket.getpeername() 。

buffer(data)

缓冲层 data 下一次发送操作的字节数。

close()

关闭包装的套接字，并清空内部缓冲区。发送缓冲区不会自动刷新，因此如果您一直在调用 buffer() ，一定要打电话给我 flush() 在调用此方法之前。调用此方法后，将来的套接字操作将引发 socket.error 。

property family

一条通向被包裹的插座家人的通道。BufferedSocket支持所有广泛使用的系列，因此此只读属性可以是 socket.AF_INET 对于IP， socket.AF_INET6 对于IPv6，以及 socket.AF_UNIX 为UDS服务。

fileno()

返回包装的套接字的文件描述符。如果在这一端已关闭。

请注意，这使得BufferedSocket是可选择的，即，在没有任何外部库的情况下可用于操作系统事件循环。请记住，操作系统不能知道BufferedSocket的内部缓冲区中的数据。用召唤来践行纪律 recv* 功能。

flush()

发送内部发送缓冲区的内容。

getpeername()

函数返回包装套接字所连接的远程地址。看见 socket.getpeername() 了解更多详细信息。

getrecvbuffer()

返回接收缓冲区字节串(Rbuf)。

getsendbuffer()

返回发送缓冲区列表的副本。

getsockname()

函数返回包装的套接字自己的地址。看见 socket.getsockname() 了解更多详细信息。

getsockopt(level, optname, buflen=None)

传递到包装套接字的便利函数 socket.getsockopt() 。

peek(size, timeout=_UNSET)

退货 size 来自套接字和/或内部缓冲区的字节。字节保留在BufferedSocket的内部recv缓冲区中。若要仅查看recv缓冲区中的字节，请使用 getrecvbuffer() 。

参数:

• size (int) -- 要查看的确切字节数

• timeout (float) -- 此操作的超时时间。对于非阻塞，可以为0；对于无超时，可以为None。默认为在BufferedSocket的构造函数中设置的值。

如果之前无法从缓冲区和套接字获取适当数量的字节 timeout 过期，然后一个 Timeout 将会被唤醒。如果连接关闭，则会引发 ConnectionClosed 将会被唤醒。

property proto

到包装套接字的协议的直通。这个 proto 属性很少使用，因此它始终为0，这意味着“默认”协议。几乎所有的实用信息都在 type 和 family ，所以你可以回到过去，永远不去想这件事。

recv(size, flags=0, timeout=_UNSET)

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

参数:

• size (int) -- 要接收的最大字节数。

• flags (int) -- 保留是为了与套接字的API兼容。只有默认情况下， 0 是有效的。

• timeout (float) -- 此操作的超时时间。可以是 0 对于非阻塞和 None 没有超时。默认为在BufferedSocket的构造函数中设置的值。

如果该操作未在 timeout 秒，a Timeout 都被养大了。就像内置的 socket.socket 如果此方法返回空字符串，则套接字关闭，recv缓冲区为空。对Recv的进一步呼吁将提高 socket.error 。

recv_close(timeout=_UNSET, maxsize=_UNSET)

接收，直到连接关闭，最多 maxsize 字节数。如果超过 maxsize 字节被接收，引发 MessageTooLong 。

recv_size(size, timeout=_UNSET)

从内部缓冲区读取，然后从套接字读取，直到 size 已读取字节。

参数:

• size (int) -- 返回前要读取的字节数。

• timeout (float) -- 此操作的超时时间。对于非阻塞，可以为0；对于无超时，可以为None。默认为在BufferedSocket的构造函数中设置的值。

如果之前无法从缓冲区和套接字获取适当数量的字节 timeout 过期，然后一个 Timeout 将会被唤醒。如果连接关闭，则会引发 ConnectionClosed 将会被唤醒。

recv_until(delimiter, timeout=_UNSET, maxsize=_UNSET, with_delimiter=False)

接收截止时间 delimiter 会被发现， maxsize 已读取字节，或者 timeout 被超过了。

参数:

• delimiter (bytes) -- 要在套接字流中搜索的一个或多个字节。

• timeout (float) -- 此操作的超时时间。对于非阻塞，可以为0；对于无超时，可以为None。默认为在BufferedSocket的构造函数中设置的值。

• maxsize (int) -- 内部缓冲区的最大大小。默认为构造函数中设置的值。

• with_delimiter (bool) -- 是否在输出中包括分隔符。 False 默认情况下，但是 True 在简单地转发消息的情况下很有用。

recv_until 将引发以下例外：

• Timeout 如果超过 timeout 秒数到期。

• ConnectionClosed 如果发送端关闭了基础套接字。

• MessageTooLong 如果未在第一个 maxsize 字节数。

• socket.error 如果在非阻塞模式下运行( timeout 等于0)，或者如果发生某种意外的套接字错误，例如在关闭的套接字上操作。

send(data, flags=0, timeout=_UNSET)

发送内部发送缓冲区的内容以及 data 连接的接收端。返回发送的总字节数。如果没有引发异常，则所有 data 已发送，并且内部发送缓冲区为空。

参数:

• data (bytes) -- 要发送的字节数。

• flags (int) -- 保留是为了与套接字的API兼容。只有默认的0才有效。

• timeout (float) -- 此操作的超时时间。对于非阻塞，可以为0；对于无超时，可以为None。默认为在BufferedSocket的构造函数中设置的值。

将筹集 Timeout 如果发送操作之前未能完成 timeout 。在发生异常的情况下，使用 BufferedSocket.getsendbuffer() 查看哪些数据未发送。

sendall(data, flags=0, timeout=_UNSET)

一条通向 send() ，保留是为了与 socket.socket 原料药。

setmaxsize(maxsize)

设置默认的最大缓冲区大小 maxsize 对于将来的操作，以字节为单位。不截断当前缓冲区。

setsockopt(level, optname, value)

传递到包装套接字的便利函数 socket.setsockopt() 。

settimeout(timeout)

设置默认设置 timeout 对于未来的操作，以秒为单位。

shutdown(how)

传递到包装套接字的 shutdown() 。语义因平台而异，因此不会对缓冲区进行特殊的内部处理。这种方法的存在是为了方便最常见的使用，其中完整的 shutdown 后跟一个 close() 。需要更多支持的开发者，请打开 an issue 。

property type

到包装套接字的类型的传递。有效的用法应该只看到 socket.SOCK_STREAM 。

例外情况

这些都是源自 socket.error 并提供更清晰的代码和更好的错误消息。

exception boltons.socketutils.Error

的一个子类 socket.error 所有其他人都来自 socketutils 例外情况会继承。

使用时 BufferedSocket 及其他 socketutils 类型，通常您希望捕获下面的某个特定异常类型，或者 socket.error 。

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

继承自 socket.timeout ，超时用于指示套接字操作在指定时间内未完成的时间。从以下任何一项筹集 BufferedSocket %s recv 方法：研究方法。

exception boltons.socketutils.ConnectionClosed

在接收且从发送端意外关闭连接时引发。募集自 BufferedSocket %s peek() ， recv_until() ，及 recv_size() ，而不是从它的 recv() 或 recv_close() 。

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

募集自 BufferedSocket.recv_until() 和 BufferedSocket.recv_closed() 当超过 maxsize 读取字节时，分别不会遇到分隔符或关闭的连接。

网络字符串

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

使用网络字符串协议进行读写。

更多信息：https://en.wikipedia.org/wiki/Netstring更多信息：http://cr.yp.to/proto/netstrings.txt

新字符串例外

这些是网络字符串连接的几个较高级别的例外。

exception boltons.socketutils.NetstringProtocolError

所有socketutils的网络字符串异常类型的基类。

exception boltons.socketutils.NetstringInvalidSize(msg)

时将引发NetStrong InvalidSize : -消息的分隔大小前缀不包含有效的整数。

显示有效大小的消息：：

5:hello,

在这里， 5 是它的大小。在该前缀位置中不能被解析为Python整数的任何东西(即， int )将引发此例外。

exception boltons.socketutils.NetstringMessageTooLong(size, maxsize)

当SIZE前缀包含有效整数，但该整数大于 NetstringSocket 已配置 maxsize 。

当引发此异常时，建议您直接关闭连接，而不是尝试恢复。