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异常。
- 参数:
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()
。- close()[源代码]¶
关闭包装的套接字,并清空内部缓冲区。发送缓冲区不会自动刷新,因此如果您一直在调用
buffer()
,一定要打电话给我flush()
在调用此方法之前。调用此方法后,将来的套接字操作将引发socket.error
。
- property family¶
一条通向被包裹的插座家人的通道。BufferedSocket支持所有广泛使用的系列,因此此只读属性可以是
socket.AF_INET
对于IP,socket.AF_INET6
对于IPv6,以及socket.AF_UNIX
为UDS服务。
- fileno()[源代码]¶
返回包装的套接字的文件描述符。如果在这一端已关闭。
请注意,这使得BufferedSocket是可选择的,即,在没有任何外部库的情况下可用于操作系统事件循环。请记住,操作系统不能知道BufferedSocket的内部缓冲区中的数据。用召唤来践行纪律
recv*
功能。
- peek(size, timeout=_UNSET)[源代码]¶
退货 size 来自套接字和/或内部缓冲区的字节。字节保留在BufferedSocket的内部recv缓冲区中。若要仅查看recv缓冲区中的字节,请使用
getrecvbuffer()
。- 参数:
如果之前无法从缓冲区和套接字获取适当数量的字节 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.- 参数:
如果该操作未在 timeout 秒,a
Timeout
都被养大了。就像内置的socket.socket
如果此方法返回空字符串,则套接字关闭,recv缓冲区为空。对Recv的进一步呼吁将提高socket.error
。
- recv_close(timeout=_UNSET, maxsize=_UNSET)[源代码]¶
接收,直到连接关闭,最多 maxsize 字节数。如果超过 maxsize 字节被接收,引发
MessageTooLong
。
- recv_size(size, timeout=_UNSET)[源代码]¶
从内部缓冲区读取,然后从套接字读取,直到 size 已读取字节。
- 参数:
如果之前无法从缓冲区和套接字获取适当数量的字节 timeout 过期,然后一个
Timeout
将会被唤醒。如果连接关闭,则会引发ConnectionClosed
将会被唤醒。
- recv_until(delimiter, timeout=_UNSET, maxsize=_UNSET, with_delimiter=False)[源代码]¶
接收截止时间 delimiter 会被发现, maxsize 已读取字节,或者 timeout 被超过了。
- 参数:
recv_until
将引发以下例外:Timeout
如果超过 timeout 秒数到期。ConnectionClosed
如果发送端关闭了基础套接字。MessageTooLong
如果未在第一个 maxsize 字节数。socket.error
如果在非阻塞模式下运行( timeout 等于0),或者如果发生某种意外的套接字错误,例如在关闭的套接字上操作。
- send(data, flags=0, timeout=_UNSET)[源代码]¶
发送内部发送缓冲区的内容以及 data 连接的接收端。返回发送的总字节数。如果没有引发异常,则所有 data 已发送,并且内部发送缓冲区为空。
- 参数:
将筹集
Timeout
如果发送操作之前未能完成 timeout 。在发生异常的情况下,使用BufferedSocket.getsendbuffer()
查看哪些数据未发送。
- sendall(data, flags=0, timeout=_UNSET)[源代码]¶
一条通向
send()
,保留是为了与socket.socket
原料药。
- 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
%srecv
方法:研究方法。
- exception boltons.socketutils.ConnectionClosed[源代码]¶
在接收且从发送端意外关闭连接时引发。募集自
BufferedSocket
%speek()
,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.NetstringInvalidSize(msg)[源代码]¶
时将引发NetStrong InvalidSize
:
-消息的分隔大小前缀不包含有效的整数。显示有效大小的消息::
5:hello,
在这里,
5
是它的大小。在该前缀位置中不能被解析为Python整数的任何东西(即,int
)将引发此例外。
- exception boltons.socketutils.NetstringMessageTooLong(size, maxsize)[源代码]¶
当SIZE前缀包含有效整数,但该整数大于
NetstringSocket
已配置 maxsize 。当引发此异常时,建议您直接关闭连接,而不是尝试恢复。