`usocket` –插座模块¶

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

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

与 CPython 的区别

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

套接字地址格式¶

usocket 模块的原生socket地址格式是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模块（注意与 usocket此处描述的本机 MicroPython模块的区别）提供了与 CPython 兼容的方式来使用元组指定地址，如下所述。请注意，根据 MicroPython 端口, socket模块可以内置或需要安装micropython-lib （如 MicroPython Unix 端口的情况），并且一些端口仍然只接受元组格式的数字地址，并且需要使用getaddrinfo函数来解析域名称。

总结：

getaddrinfo在编写便携式应用程序时始终使用。
如果您的端口支持，下面描述的元组地址可以用作快速黑客和交互使用的快捷方式。

socket模块的元组地址格式：

IPv4: (ipv4_address, port)，其中ipv4_address是一个带有点符号数字 IPv4 地址的字符串，例如"8.8.8.8"，并且port是 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 端口。

功能¶

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

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

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

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

将主机/端口参数转换为 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]异常对象的属性访问）。负值的使用是一个临时细节，将来可能会改变。

usocket.inet_ntop(af, bin_addr)¶

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

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

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 port.

特定于 WiPy 的常量：

usocket.IPPROTO_SEC¶: 用于创建 SSL 兼容套接字的特殊协议值。

类套接字¶

方法¶

socket.close()¶

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

套接字在被垃圾收集时会自动关闭，但建议close()您在完成对它们的工作后立即向它们明确推荐。

socket.bind(address)¶: 将套接字绑定到address。套接字必须尚未绑定。

socket.listen([backlog])¶: 启用服务器以接受连接。如果指定backlog，则必须至少为0（如果较低，则设置为0）；并指定系统在拒绝新连接之前允许的未接受连接数。如果未指定，则选择默认的合理值。

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

socket.connect(address)¶: 连接到地址为的远程套接字。

socket.send(bytes)¶: 向套接字发送数据。套接字必须连接到远程套接字。返回发送的字节数，可能小于数据长度（“短写”）。

socket.sendall(bytes)¶

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

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

socket.recv(bufsize)¶: 从套接字接收数据。返回值是一个字节对象，表示接收到的数据。一次接收的最大数据量由 bufsize 指定。

socket.sendto(bytes, address)¶: 向套接字发送数据。套接字不应连接到远程套接字，因为目标套接字由address指定。

socket.recvfrom(bufsize)¶: 从套接字接收数据。返回值是一对（字节，地址），其中字节是表示接收到的数据的字节对象，地址是发送数据的套接字的地址。

socket.setsockopt(level, optname, value)¶: 设置给定套接字选项的值。所需的符号常量在套接字模块（SO_* 等）中定义。该值可以是表示缓冲区的整数或类似字节的对象。

socket.settimeout(value)¶

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

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

并非每个MicroPython 端口都支持这种方法。一个更便携和通用的解决方案是使用uselect.pollobject. 这允许同时等待多个对象（不仅在套接字上，而且在 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 的区别

CPythonsocket.timeout 在超时的情况下引发异常，这是一个 OSError子类。MicroPython 会直接引发 OSError。如果您使用捕获异常，您的代码将在 MicroPython 和 CPython 中工作。except OSError:

socket.setblocking(flag)¶

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

此方法是某些settimeout() 调用的简写：

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

socket.makefile(mode='rb', buffering=0, /)¶: 返回与套接字关联的文件对象。确切的返回类型取决于提供给 makefile() 的参数。支持仅限于二进制模式（'rb'、'wb' 和 'rwb'）。不支持CPython 的参数：encoding、errors和newline。

与 CPython 的区别

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

与 CPython 的区别

关闭由 makefile() 返回的文件对象也将关闭原始套接字。

socket.read([size])¶: 从套接字读取最多 size 个字节。返回一个字节对象。如果未指定大小，则从套接字读取所有可用数据，直到 EOF；因此，该方法在套接字关闭之前不会返回。该函数尝试读取尽可能多的数据（没有“短读”）。但是，对于非阻塞套接字，这可能是不可能的，然后将返回较少的数据。

socket.readinto(buf[, nbytes])¶

将字节读入buf。如果指定了nbytes，则最多读取那么多字节。否则，最多读取len(buf)个字节。就像 read()，这种方法遵循“无短读”政策。

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

socket.readline()¶

读取一行，以换行符结尾。

返回值：读取的行。

socket.write(buf)¶

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

返回值：写入的字节数。

exception usocket.error¶: MicroPython 没有这个例外。

与 CPython 的区别

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

usocket –插座模块¶

套接字地址格式¶

功能¶

常数¶

类套接字¶

方法¶

`usocket` –插座模块¶