usocket.rst
:mod:`usocket` -- socket module
|see_cpython_module| :mod:`python:socket`.
This module provides access to the BSD socket interface.
Difference to CPython
For efficiency and consistency, socket objects in MicroPython implement a stream (file-like) interface directly. In CPython, you need to convert a socket to a file-like object using makefile() method. This method is still supported by MicroPython (but is a no-op), so where compatibility with CPython matters, be sure to use it.
Socket address format(s)
The native socket address format of the usocket
module is an opaque data type
returned by getaddrinfo function, which must be used to resolve textual address
(including numeric addresses):
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)
Using getaddrinfo is the most efficient (both in terms of memory and processing power) and portable way to work with addresses.
However, socket
module (note the difference with native MicroPython
usocket
module described here) provides CPython-compatible way to specify
addresses using tuples, as described below. Note that depending on a
MicroPython port, socket
module can be builtin or need to be
installed from micropython-lib (as in the case of MicroPython Unix port),
and some ports still accept only numeric addresses in the tuple format,
and require to use getaddrinfo function to resolve domain names.
Summing up:
- Always use getaddrinfo when writing portable applications.
- Tuple addresses described below can be used as a shortcut for quick hacks and interactive use, if your port supports them.
Tuple address format for socket
module:
- IPv4: (ipv4_address, port), where ipv4_address is a string with
dot-notation numeric IPv4 address, e.g.
"8.8.8.8"
, and port is and integer port number in the range 1-65535. Note the domain names are not accepted as ipv4_address, they should be resolved first using usocket.getaddrinfo(). - IPv6: (ipv6_address, port, flowinfo, scopeid), where ipv6_address
is a string with colon-notation numeric IPv6 address, e.g.
"2001:db8::1"
, and port is an integer port number in the range 1-65535. flowinfo must be 0. scopeid is the interface scope identifier for link-local addresses. Note the domain names are not accepted as ipv6_address, they should be resolved first using usocket.getaddrinfo(). Availability of IPv6 support depends on a MicroPython port.
Functions
Constants
Constants specific to WiPy: