usocket – 网络套接字

该模块实现了相应CPython模块的子集，如下所述。有关更多信息，请参阅原始CPython文档: socket.

该模块提供对BSD套接字接口的访问

与CPython的区别

为了提高效率和一致性，MicroPython中的套接字对象直接实现了stream（类文件）接口。在CPython中，您需要使用makefile（）方法将套接字转换为类文件对象。 MicroPython仍支持此方法（但是无操作），因此在与CPython兼容的情况下，请务必使用它。

套接字地址格式

usocket模块的本机套接字地址格式是getaddrinfo函数返回的不透明数据类型，必须用它来解析文本地址（包括数字地址）：

sockaddr = usocket.getaddrinfo('www.micropython.org', 80)[0][-1]
# You must use getaddrinfo() even for numeric addresses
sockaddr = usocket.getaddrinfo('127.0.0.1', 80)[0][-1]
# Now you can use that address
sock.connect(addr)

使用getaddrinfo是最有效的（在内存和处理能力方面），而且也是使用地址的可移植方式。

但是，socket模块（注意与此处描述的本机MicroPythonusocket模块的区别）提供了与CPython兼容的方式来使用元组指定地址，如下所述。请注意，取决于MicroPython端口，可以在内置或需要从micropython-lib安装套接字模块（如“MicroPython Unix端口”的情况），并且某些端口仍然只接受元组中的数字地址格式，并要求使用getaddrinfo函数来解析域名。

总的来说：

• 编写便携式应用程序时始终使用getaddrinfo。

• 如果您的端口支持快速黑客和交互式使用，则下面描述的元组地址可用作快捷方式。

socket模块的元组地址格式：

• IPv4：（ipv4_address，port），其中ipv4_address是带有点符号数字IPv4地址的字符串，例如， “8.8.8.8”，端口号和整数端口号在1-65535范围内。请注意，域名不被接受为ipv4_address，应首先使用usocket.getaddrinfo（）解析它们。

• IPv6：（ipv6_address，port，flowinfo，scopeid），其中ipv6_address是带冒号数字IPv6地址的字符串，例如： “2001：db8 :: 1”，port是1-65535范围内的整数端口号。 flowinfo必须为0. scopeid是链路本地地址的接口范围标识符。请注意，域名不被接受为ipv6_address，应首先使用usocket.getaddrinfo（）解析它们。 IPv6支持的可用性取决于MicroPython端口。

函数

socket

usocket.socket(af=AF_INET, type=SOCK_STREAM, proto=IPPROTO_TCP)

使用给定的地址系列，套接字类型和协议号创建一个新套接字。请注意，在大多数情况下不需要指定proto（不推荐使用，因为一些MicroPython端口可能会省略IPPROTO_ *常量）。相反，type参数将自动选择所需的协议：

# Create STREAM TCP socket
socket(AF_INET, SOCK_STREAM)
# Create DGRAM UDP socket
socket(AF_INET, SOCK_DGRAM)

getaddrinfo

usocket.getaddrinfo(host, port, af=0, type=0, proto=0, flags=0)

将 host / port 参数转换为5元组序列，其中包含用于创建连接到该服务的套接字的所有必要参数。参数af，type和proto（与socket（）函数具有相同的含义）可用于过滤返回哪种地址。如果未指定参数或为零，则可以返回所有地址组合（需要在用户端进行过滤）。

生成的5元组列表具有以下结构：

(family, type, proto, canonname, sockaddr)

以下示例显示如何连接到给定的URL：

s = usocket.socket()
# This assumes that if "type" is not specified, an address for
# SOCK_STREAM will be returned, which may be not true
s.connect(usocket.getaddrinfo('www.micropython.org', 80)[0][-1])

建议使用过滤参数：

s = usocket.socket()
# Guaranteed to return an address which can be connect'ed to for
# stream operation.
s.connect(usocket.getaddrinfo('www.micropython.org', 80, 0, SOCK_STREAM)[0][-1])

与CPython的区别

如果此函数出错，CPython会引发socket.gaierror异常（OSError子类）。 MicroPython没有socket.gaierror并直接引发OSError。请注意，getaddrinfo（）的错误号形成一个单独的命名空间，可能与uerrno模块中的错误号不匹配。为了区分getaddrinfo（）错误，它们用负数表示，而标准系统错误是正数（错误号可以使用来自异常对象的e.args [0]属性访问）。使用负值是临时细节，可能在将来发生变化。

inet_ntop

usocket.inet_ntop(af, bin_addr)

将给定地址族af的二进制网络地址bin_addr转换为文本表示：

>>> usocket.inet_ntop(usocket.AF_INET, b"\x7f\0\0\1")
'127.0.0.1'

inet_pton

usocket.inet_pton(af, txt_addr)

将给定地址族af的文本网络地址txt_addr转换为二进制表示：

>>> usocket.inet_pton(usocket.AF_INET, "1.2.3.4")
b'\x01\x02\x03\x04'

常量

usocket.AF_INET usocket.AF_INET6

解决家庭类型。可用性取决于特定的MicroPython端口。

usocket.SOCK_STREAM usocket.SOCK_DGRAM

套接字类型。

usocket.IPPROTO_UDP usocket.IPPROTO_TCP

IP协议号。可用性取决于特定的MicroPython端口。注意，在调用usocket.socket（）时不需要指定它们，因为SOCK_STREAM套接字类型会自动选择IPPROTO_TCP和SOCK_DGRAM - IPPROTO_UDP。因此，这些常量的唯一实际用途是作为setsockopt（）的参数。

usocket.SOL_*

套接字选项级别（setsockopt（）的参数）。确切的库存取决于MicroPython端口。

usocket.SO_*

套接字选项（setsockopt（）的参数）。确切的库存取决于MicroPython端口。

类 socket

函数

close

socket.close()

标记套接字已关闭并释放所有资源。一旦发生这种情况，套接字对象上的所有未来操作都将失败。如果协议支持，远程端将接收EOF指示。

套接字在被垃圾收集时会自动关闭，但建议你在完成它们之后立即“关闭”它们。

(canmv 未实现)socket.bind(address)

将套接字绑定到地址。套接字必须尚未绑定。

(canmv 未实现)socket.listen([backlog])

使服务器接受连接。如果指定了积压，则必须至少为0（如果低，则将其设置为0）;并指定在拒绝新连接之前系统将允许的未接受连接数。如果未指定，则选择默认的合理值。

(canmv 未实现)socket.accept()

接受连接。套接字必须绑定到一个地址并侦听连接。返回值是一对（conn，address），其中conn是可用于在连接上发送和接收数据的新套接字对象，address是绑定到连接另一端的套接字的地址。

connect

socket.connect(address)

连接到地址处的远程套接字。

send

socket.send(bytes)

将数据发送到套接字。套接字必须连接到远程套接字。返回发送的字节数，可能小于数据长度（“短写”）。

sendall

socket.sendall(bytes)

将所有数据发送到套接字。套接字必须连接到远程套接字。与send（）不同，此方法将尝试通过连续发送数据块来发送所有数据。

此方法在非阻塞套接字上的行为未定义。因此，在MicroPython上，建议使用write（）方法，它具有相同的“无短写入”策略来阻塞套接字，并将返回在非阻塞套接字上发送的字节数。

recv

socket.recv(bufsize)

从套接字接收数据。返回值是表示接收数据的字节对象。一次接收的最大数据量由bufsize指定。

sendto

socket.sendto(bytes, address)

将数据发送到套接字。套接字不应连接到远程套接字，因为目标套接字由地址指定。

recvfrom

socket.recvfrom(bufsize)

从套接字接收数据。返回值是一对（字节，地址），其中bytes是表示接收数据的字节对象，address是发送数据的套接字的地址。

setsockopt

socket.setsockopt(level, optname, value)

设置给定套接字选项的值。所需的符号常量在套接字模块中定义（SO_ *等）。该值可以是整数或表示缓冲区的类字节对象。

settimeout

socket.settimeout(value)

注意：并非每个端口都支持此方法，请参阅下文。

阻止套接字操作设置超时。 value参数可以是表示秒的非负浮点数，也可以是None。如果给出非零值，则如果在操作完成之前已经过了超时时间值，则后续的套接字操作将引发“OSError”异常。如果给出零，则套接字处于非阻塞模式。如果给出None，则套接字处于阻塞模式。

并非每个“MicroPython端口”都支持此方法。更便携和通用的解决方案是使用uselect.poll对象。这允许同时等待多个对象（而不仅仅是在套接字上，而是在支持轮询的通用stream对象上）。例：

# Instead of:
s.settimeout(1.0)  # time in seconds
s.read(10)  # may timeout

# Use:
poller = uselect.poll()
poller.register(s, uselect.POLLIN)
res = poller.poll(1000)  # time in milliseconds
if not res:
    # s is still not ready for input, i.e. operation timed out

与CPython的区别

CPython在超时的情况下引发socket.timeout异常，这是一个OSError子类。 MicroPython直接引发了一个OSError。如果你使用除了OSError：来捕获异常，你的代码将在MicroPython和CPython中都有效。

setblocking

socket.setblocking(flag)

设置套接字的阻塞或非阻塞模式：如果flag为false，则套接字设置为非阻塞，否则设置为阻塞模式。

这个方法是某些settimeout（）调用的简写：

sock.setblocking(True) 相当于sock.settimeout(None) sock.setblocking(False) i相当于 sock.settimeout(0)

makefile

socket.makefile(mode='rb', buffering=0)

返回与套接字关联的文件对象。确切的返回类型取决于给makefile（）的参数。支持仅限于二进制模式（’rb’，’wb’和’rwb’）。 CPython的参数：不支持编码，错误和换行符。

与CPython的区别

由于MicroPython不支持缓冲流，因此忽略缓冲参数的值，并将其视为0（无缓冲）。

与CPython的区别

关闭makefile（）返回的文件对象也将关闭原始套接字。

read

socket.read([size])

从插槽中读取大小字节。返回一个字节对象。如果没有给出大小，它会读取插座中可用的所有数据，直到EOF;因此，在套接字关闭之前，该方法不会返回。此函数尝试读取所请求的数据（没有“短读取”）。但是，对于非阻塞套接字，这可能是不可能的，然后将返回更少的数据。

readinto

socket.readinto(buf[, nbytes])

将字节读入buf。如果指定了nbytes，则最多读取多个字节。否则，最多读取len（buf）字节。就像read（）一样，此方法遵循“无短读”策略。

返回值：读取并存储到buf中的字节数。

readline

socket.readline()

读一行，以换行符结尾。

返回值：读取的行。

write

socket.write(buf)

将字节缓冲区写入套接字。此函数将尝试将所有数据写入套接字（无“短写”）。但是，对于非阻塞套接字，这可能是不可能的，并且返回值将小于buf的长度。

返回值：写入的字节数。

exception usocket.error

MicroPython没有此异常。

与CPython的区别

CPython曾经有一个socket.error异常现在已被弃用，它是OSError的别名。在MicroPython中，直接使用OSError。